# Aikit Runtime

> Agent-native, governed AI runtime for Rust, Python, and TypeScript — native providers, MCP, tools, routing, memory, budgets, audit, and containment.

- **Type:** MCP server
- **Install:** `agentstack add mcp-matakartal-aikit-runtime`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [matakartal](https://agentstack.voostack.com/s/matakartal)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [matakartal](https://github.com/matakartal)
- **Source:** https://github.com/matakartal/aikit-runtime
- **Website:** https://github.com/matakartal/aikit-runtime#readme

## Install

```sh
agentstack add mcp-matakartal-aikit-runtime
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# aikit-runtime

One governed runtime for serious AI agents.

Build provider-aware agents in **Rust**, **Python**, and **TypeScript** without reimplementing
streaming, tools, policy, routing, budgets, audit, memory, or sessions in every language.

[](https://github.com/matakartal/aikit-runtime/actions/workflows/ci.yml)
[](https://github.com/matakartal/aikit-runtime/actions/workflows/release.yml)
[](Cargo.toml)
[](crates/aikit-py/pyproject.toml)
[](crates/aikit-node/package.json)
[](#license)

**One core. Three SDKs. Four native providers. Four compatible endpoints. One policy boundary.**

[Quick start](#quick-start) · [CLI](#command-line-interface) · [Architecture](#architecture) · [Governance](#governed-tool-execution) · [SDKs](#one-runtime-three-sdks) · [Documentation](#documentation)

---

`aikit-runtime` keeps correctness-sensitive agent behavior in one Rust core and exposes it through
thin native bindings. Anthropic, OpenAI, Google, and DeepSeek retain their native wire formats,
while your application gets one canonical runtime contract.

## Why aikit?

| One runtime | Provider-native | Governed execution |
|---|---|---|
| Rust owns the agent loop; Python and Node call the same implementation. | Provider-specific reasoning, tool calls, citations, usage, and metadata stay intact. | Every side effect passes schema validation, hooks, permissions, budgets, and audit. |
| **Typed developer experience** | **Agent primitives included** | **Production controls built in** |
| Streaming text, structured objects, multimodal messages, typed errors, and cancellation. | Tools, subagents, parallel fan-out, councils, memory, sessions, routing, and retries. | Fail-closed containment, metadata-safe audit, cost limits, scoped tools, and explicit approvals. |

## Architecture

```mermaid
flowchart TB
    subgraph Apps[Application code]
        R[Rust]
        P[Python]
        N[TypeScript / Node.js]
    end

    R --> F[Rust facade: aikit]
    P --> PY[PyO3 binding]
    N --> JS[napi binding]

    F --> CORE
    PY --> CORE
    JS --> CORE

    subgraph CORE[aikit-runtime-core]
        direction LR
        MSG[Canonical messagesstreaming + objects]
        LOOP[Agent looptools + subagents]
        GOV[Governancehooks + permissions]
        OPS[Budgets + routingaudit + state]
        MSG --> LOOP --> GOV --> OPS
    end

    CORE --> A[AnthropicMessages]
    CORE --> O[OpenAIResponses]
    CORE --> G[GoogleGemini]
    CORE --> D[DeepSeekChat Completions]
    CORE --> C[Compatible endpointsOpenRouter · Groq · Mistral · xAI]

    CORE --> HOST[Host callbacks]
    CORE --> BUILTIN[Jailed built-in tools]
    BUILTIN --> BOUNDARY[Seatbelt · Linux namespaces + seccompWindows Job · hardened Docker]
```

The bindings translate host values and async callbacks at the edge. They do not duplicate policy,
provider translation, or orchestration logic.

## Quick start

The repository includes a deterministic provider, so you can exercise the complete runtime with
**no API key and no network call**.

```bash
git clone https://github.com/matakartal/aikit-runtime.git
cd aikit-runtime
cargo run -p aikit-runtime --example quickstart
```

Expected output:

```text
Araç sonucunu aldım; görevi tamamladım.
```

## Command-line interface

The source-first CLI makes the runtime usable without writing an application. Its default model
is the deterministic, offline `mock-1` provider:

```bash
cargo run -p aikit-cli -- run "Explain aikit in one sentence"
cargo run -p aikit-cli -- chat
cargo run -p aikit-cli -- providers
cargo run -p aikit-cli -- doctor
cargo run -p aikit-cli -- eval evals/smoke.json
```

Choose a configured provider explicitly only when you intend to make a network call:

```bash
XAI_API_KEY='...' cargo run -p aikit-cli -- run --model grok-4.5 "Say hello"
```

The CLI supports text, JSON, and JSONL output, stable exit codes, stdin prompts, canonical
multi-turn history, secret-safe provider discovery, containment diagnostics, deterministic eval
gates, and shell completion generation. See the [CLI guide](crates/aikit-cli/README.md) for the
full contract.

### Rust

```rust
use aikit::Agent;

#[tokio::main]
async fn main() -> Result> {
    let answer = Agent::new()
        .generate_text("Say hello in Turkish", "mock-1", 128)
        .await?;

    println!("{}", answer.text);
    Ok(())
}
```

Run it from this checkout:

```bash
cargo run -p aikit-runtime --example quickstart
```

### Python

Build the native binding once, then use the same core from Python:

```bash
python3 -m venv .venv
.venv/bin/pip install "maturin==1.14.1"
.venv/bin/maturin develop --manifest-path crates/aikit-py/Cargo.toml
```

```python
import asyncio
import aikit

async def main() -> None:
    agent = aikit.Agent.from_env({})
    answer = await agent.generate_text("Say hello in Turkish")
    print(answer["text"])

asyncio.run(main())
```

### TypeScript / Node.js

```bash
./scripts/build-node.sh
```

```js
const { Agent } = require("./crates/aikit-node");

async function main() {
  const agent = Agent.fromEnv({});
  const answer = await agent.generateText("Say hello in Turkish");
  console.log(answer.text);
}

main();
```

## Built for agent workloads

| Capability | What aikit provides |
|---|---|
| Streaming | Incremental text, reasoning, tool-call, tool-result, usage, and terminal events. |
| Structured output | JSON Schema plus async semantic validation, bounded repair, streaming attempts, Pydantic and Zod materialization. |
| Evaluation | Deterministic text, tool-trajectory, terminal-state, usage, turn, and model-attempt gates over the current invocation. |
| Canonical messages | Text, reasoning, tools, media, citations, usage, and provider-owned metadata without flattening. |
| Governance | Global allow / ask / deny, declarative JSON policy, async approval, lifecycle hooks, and authoritative denial. |
| Plan mode | Whole-approach HITL: the agent proposes a plan; a human approves, revises, or rejects before tools run. |
| Smart approval | Keyless risk scoring auto-allows low-risk `ask` calls and escalates the rest to a human. |
| Reliability rules | Declarative tool ordering, prerequisites, and use caps — separate from security permissions. |
| Off-prompt output | Large or sensitive tool results stored by reference so they do not fill the model context. |
| Guardrails | Deterministic secret/PII redaction, regex blocking, and fail-closed MCP safety-server interop. |
| Self-extension | Human-governed capability requests: the agent asks for a tool it lacks, a human decides, the grant is recorded — never a silent escalation. |
| Tool runtime | Host callbacks plus opt-in Read, Write, Edit, Glob, Grep, and contained Bash. |
| MCP | Bounded stdio and Streamable HTTP client with tools, resources, prompts, auth/session propagation, exact allow/deny visibility filters, and governed execution. |
| Routing | Explicit or automatic model selection from a caller-owned catalog with hard capability and cost gates. |
| Resilience | Typed failures, bounded retry, pre-stream fallback, cancellation, deadlines, and terminal outcomes. |
| Orchestration | Scoped subagents, ordered parallel fan-out, council synthesis, quorum, and shared budget accounting. |
| State | Namespaced memory, revisioned sessions, JSON/transactional SQLite persistence, canonical recording, and resume. |
| Compaction | Opt-in transcript bounding: keep the task anchor and recent tail within a token budget, preserving tool pairing. |
| Web and browser | HTTPS allowlisted fetch/search plus an existing-session WebDriver executor; browser registration requires an explicit assertion of caller-owned pre-request egress enforcement. |
| Observability | Typed audit lifecycle, metadata-only redaction by default, JSONL sinks, and an optional Rust OpenTelemetry bridge. |

## Governed tool execution

Tool authorization happens immediately before the side effect—not in a prompt and not in a UI
convention.

```mermaid
flowchart TD
    START[Model emits tool call] --> SCHEMA[Compile and validate input schema]
    SCHEMA -->|invalid| REJECT[Return typed error]
    SCHEMA --> PRE[Run scoped PreTool hooks]
    PRE -->|block| REJECT
    PRE --> POLICY{Permission decision}
    POLICY -->|deny| DENY[Authoritative denialexecutor is never called]
    POLICY -->|ask| APPROVE{Host approval}
    POLICY -->|allow| VALIDATE[Revalidate rewritten input]
    APPROVE -->|deny| DENY
    APPROVE -->|allow / rewrite| VALIDATE
    VALIDATE --> EXEC[Execute exactly once]
    EXEC --> POST[PostTool or failure hooks]
    POST --> AUDIT[Record audit + usage + outcome]
    AUDIT --> CONTINUE[Return result to model]
    DENY --> CONTINUE
    REJECT --> CONTINUE
```

A denied tool never reaches its callback. Approval and hook rewrites are schema-validated again
before execution.

### Example: policy around a host tool

```python
agent = aikit.Agent.from_env({})

async def lookup(payload: dict) -> str:
    return f"price:{payload['symbol']}"

agent.add_tool(
    "lookup",
    "Look up one market symbol",
    {
        "type": "object",
        "properties": {"symbol": {"type": "string"}},
        "required": ["symbol"],
        "additionalProperties": False,
    },
    lookup,
)

agent.set_permissions([
    {"id": "approve-lookups", "effect": "ask", "tool": "lookup"},
])

async def approve(request: dict):
    return "allow" if request["input"]["symbol"] == "AAPL" else "deny"

agent.can_use_tool(approve)
```

The same lifecycle exists in Rust and TypeScript; only the host callback syntax changes.

### Declarative policy, plan mode, and reliability

Rust also ships higher-level governance primitives that compose with the same engine:

```rust
// Declarative JSON → enforcing PermissionEngine
use aikit_core::PolicySpec;
let engine = PolicySpec::from_json(r#"{
  "mode": "allow",
  "deny": ["Bash(rm -rf *)"],
  "ask": ["Bash(git push *)"],
  "allow": ["Read(*)"]
}"#)?.build()?;

// Plan mode: review the whole approach before any tool runs
// cargo run -p aikit-runtime-core --example plan_mode

// Smart approval: auto-allow Low risk, escalate the rest
// cargo run -p aikit-runtime-core --example smart_approval

// Reliability: deploy only after test, at most once
// cargo run -p aikit-runtime-core --example reliability
```

See the [feature reference](docs/FEATURES.md#governance-and-hooks) for plan review, risk scoring,
reliability rules, off-prompt tool output, and capability requests.

## Provider fidelity

`aikit` uses native adapters rather than forcing every provider through one lossy compatibility
shape.

| Provider | Native API | Reasoning continuation | Structured output | Vision |
|---|---|---|---|---:|
| Anthropic | Messages | Signed thinking replayed unchanged | Native JSON Schema constraint | Yes |
| OpenAI | Responses | Opaque reasoning item replayed unchanged | Strict JSON Schema | Yes |
| Google | Gemini `generateContent` | Thought signature retained on the exact function-call part | `responseJsonSchema` | Yes |
| DeepSeek | Chat Completions | Full `reasoning_content` retained for tool continuation | JSON mode + validation and repair | No |

OpenRouter, Groq, Mistral, and xAI are supported through isolated OpenAI-compatible endpoints.
They do not inherit native-provider fidelity claims automatically; capability checks still apply.

### Grok through xAI

Set `XAI_API_KEY`, then select Grok with either its natural model id or the explicit xAI namespace:

```python
agent = aikit.Agent.from_env({"XAI_API_KEY": "..."})
answer = await agent.generate_text("Hello from Grok", model="grok-4.5")
# Equivalent explicit form: model="xai:grok-4.5"
```

The adapter uses xAI's OpenAI-compatible Chat Completions endpoint. Model availability can change;
choose a model currently enabled for your xAI account.

Generated objects report their actual fidelity:

- `native_constrained`
- `forced_tool_call`
- `prompted_and_parsed`

Your application can branch on that grade instead of assuming every JSON-shaped answer has the
same guarantee.

After JSON Schema succeeds, an optional async semantic validator can return `Accept`,
`Retry(reason)`, or `Reject(reason)`. Retry uses the existing bounded repair budget; reject and
callback failures stop with a typed structured-output error. Validators must be pure/idempotent,
and aikit never copies the candidate object into validator errors or audit events automatically.
Retry reasons are provider-facing, so return a safe summary rather than the raw object. Reject and
callback-error details are returned to the host but persist only as generic audit failure markers;
keep those details secret-free too because an application may log exceptions.

## One runtime, three SDKs

| Concept | Rust | Python | TypeScript |
|---|---|---|---|
| Agent | `Agent::new()` | `aikit.Agent()` | `new Agent()` |
| Text | `generate_text` | `generate_text` | `generateText` |
| Streaming | `stream_text` | `stream_text` | `streamText` |
| Structured output | `generate_object` | `generate_object` | `generateObject` |
| Outcome evaluation | `evaluate_outcome` | `evaluate_outcome` | `evaluateOutcome` |
| Tool registration | `tool` / executor | `add_tool` | `addTool` |
| Permissions | `Governance` | `set_permissions` | `setPermissions` |
| Memory | `remember` / `recall` | `remember` / `recall` | `remember` / `recall` |
| Parallel agents | `parallel` | `parallel` | `parallel` |
| Persistent audit | `JsonlAuditSink` | `configure_jsonl_audit` | `configureJsonlAudit` |

Cross-language conformance runs canonical scenarios through all three SDKs and compares normalized
results byte for byte.

## Multimodal and structured input

All text and object surfaces accept a string or canonical message history:

```python
messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe this chart"},
        {
            "type": "media",
            "media_type": "image/png",
            "source": {"kind": "url", "url": "https://example.com/chart.png"},
        },
    ],
}]

result = await agent.generate_text(messages, model="your-model")
```

Unsupported media is rejected with a typed error instead of being silently dropped.

## Tools and containment

Built-in tools are explicit and scoped:

```python
agent.register_builtin_tools(["./workspace"])
agent.configure_jsonl_audit("./state/audit.jsonl")
agent.use_memory_file("./state/memory.json", namespace="project-a")
agent.use_session_file("./state/sessions.json")
```

| Surface | Boundary |
|---|---|
| Read / Write / Edit / Glob / Grep | Descriptor-relative jail, registered roots only, no symlink following. |
| Built-in Bash | Required containment: probed macOS Seatbelt, Linux namespaces+seccomp, Windows Job Objects, or hardened digest-pinned Docker. |
| Host callbacks | Your application process and your responsibility to isolate further when needed. |

If required containment is unavailable, built-in Bash is denied before process launch.

## Source module map

`aikit-runtime` is currently distributed from this GitHub repository. Registry packages are a
release gate, not a claim about artifacts that exist today.

| Ecosystem | Workspace package | Import / library |
|---|---|---|
| Rust facade | `aikit-runtime` | `aikit` |
| Rust core | `aikit-runtime-core` | `aikit_core` |
| Python | `aikit-runtime` | `import aikit` |
| Node wrapper | `aikit-runtime` | local checkout wrapper |
| Node native binaries | `aikit-runtime-{platform}` | selected locally by the wrapper |

The current `v0.3.0-alpha.1` tree is a **source-first implementation preview**. Keyless source, binding,
and local package-layout checks run in CI. Use the checkout commands in [Quick start](#quick-start);
no npm, PyPI, or crates.io publication is claimed for this candidate.

### Supported binary targets

| Platform | Python ABI3 wheel | Node native package |
|---|---:|---:|
| Linux x64, glibc >= 2.28 | Yes | Yes |
| Linux ARM64, glibc >= 2.28 | Yes | Yes |
| macOS ARM64 | Yes | Yes |
| macOS x64 | Yes | Yes |
| Windows x64 | Y

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [matakartal](https://github.com/matakartal)
- **Source:** [matakartal/aikit-runtime](https://github.com/matakartal/aikit-runtime)
- **License:** Apache-2.0
- **Homepage:** https://github.com/matakartal/aikit-runtime#readme

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-matakartal-aikit-runtime
- Seller: https://agentstack.voostack.com/s/matakartal
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.