> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Argent-Native Runtime

> The Argent-native agent runtime and LLM layer replacing the upstream Pi Mono dependency.

## Overview

The Argent-native runtime is ArgentOS's replacement for the upstream Pi Mono agent framework (`@mariozechner/pi-*`). Pi Mono's creator joined OpenAI, making continued dependency on the upstream packages a strategic risk. The Argent runtime provides equivalent functionality with a cleaner architecture, native SIS lesson injection, and a multi-provider LLM layer.

The runtime consists of two complementary layers:

* **argent-agent** (`src/argent-agent/`) -- Agent loop, session management, tool execution, compaction, skills
* **argent-ai** (`src/argent-ai/`) -- LLM provider implementations, model database, streaming, completion

A compatibility bridge (`compat.ts`) enables gradual migration by wrapping Argent providers as Pi-compatible `streamSimple` functions.

## argent-agent: Agent Runtime

### Agent Class

The core turn executor that orchestrates:

1. **Lesson injection** via SIS -- injects relevant lessons into the system prompt
2. **Provider calls** -- streaming or non-streaming LLM invocations
3. **Tool execution** -- processes tool calls from the LLM response
4. **Episode recording** -- captures structured episodes for contemplation
5. **History updates** -- appends turn results to session history

### Session Manager

Append-only JSONL conversation storage with tree structure:

* **Tree-structured entries** -- each entry has `id` and `parentId` for branching support
* **Append-only JSONL** -- durable, crash-safe format
* **Built-in index** -- O(1) entry lookups (Pi rebuilds index on every access)
* **Explicit compaction tracking** -- tracks first-kept-entry for clean compaction
* **Format version 3** -- session header, messages, thinking level changes, model changes

### File Tools

Coding tools factory providing:

* `read_file` -- Read file contents
* `write_file` -- Write file contents
* `edit_file` -- Edit with diff
* `bash` -- Execute shell commands

### Skills

Skills loaded from `.md` files with YAML frontmatter:

```markdown theme={null}
---
name: web-search
description: Search the web for information
tools: [web_search]
---

When asked to search the web, use the web_search tool...
```

## argent-ai: LLM Layer

### Provider Registry

Central registry for LLM providers. Each provider implements the `Provider` interface:

```typescript theme={null}
interface Provider {
  id: string;
  complete(request: TurnRequest): Promise<TurnResponse>;
  stream(request: TurnRequest): AsyncIterable<StreamEvent>;
}
```

### Provider Implementations

Seven providers in `src/argent-ai/providers/`:

| Provider             | Models                     | API                     |
| -------------------- | -------------------------- | ----------------------- |
| **Anthropic**        | Claude Haiku, Sonnet, Opus | Anthropic Messages      |
| **OpenAI**           | GPT-4o, GPT-4, o1          | OpenAI Chat Completions |
| **OpenAI Responses** | GPT-4o with reasoning      | OpenAI Responses API    |
| **Google**           | Gemini Pro, Flash          | Google Generative AI    |
| **xAI**              | Grok                       | OpenAI-compatible       |
| **MiniMax**          | MiniMax-M2.1, M2-her       | OpenAI-compatible       |
| **Z.AI**             | GLM-4.7, GLM-4.7-Flash     | OpenAI-compatible       |

### Models Database

Comprehensive model catalog with pricing, context windows, and capabilities:

```typescript theme={null}
{
  id: "claude-opus-4-20250514",
  api: "anthropic-messages",
  provider: "anthropic",
  baseUrl: "https://api.anthropic.com",
  input: ["text", "image"],
  contextWindow: 200000,
  maxTokens: 16384,
  pricing: { input: 15.0, output: 75.0 },  // per million tokens
  reasoning: true,
  vision: true,
}
```

## Compatibility Bridge

The bridge enables gradual migration from Pi to Argent by wrapping Argent providers as Pi-compatible functions.

### Thinking Level Resolution

| Level             | Behavior               |
| ----------------- | ---------------------- |
| `off`             | Thinking disabled      |
| `minimal` / `low` | Low thinking budget    |
| `medium`          | Medium thinking budget |
| `high` / `xhigh`  | High thinking budget   |

## Feature Flag

The Argent runtime is activated via the `ARGENT_RUNTIME=true` environment variable:

```bash theme={null}
# In gateway LaunchAgent plist
ARGENT_RUNTIME=true
```

When enabled, the gateway routes to `ArgentSessionManager` instead of Pi's session manager.

## SIS Integration

The Argent runtime includes native SIS (Self-Improving System) integration:

* **Lesson Injection** -- Selects relevant lessons and injects them into the system prompt before each turn
* **Lesson Storage** -- Persists lessons extracted from agent episodes
* **Confidence Scoring** -- Scores lesson relevance to the current context

<Tip>
  This closes the SIS feedback loop that was a stub in the Pi runtime -- lessons extracted from episodes are actively injected back into agent prompts.
</Tip>

## Migration Status

| Phase   | Description                                      | Status                   |
| ------- | ------------------------------------------------ | ------------------------ |
| Phase 0 | PG+Redis infrastructure                          | Complete                 |
| Phase 1 | argent-ai providers (6 providers)                | Code complete            |
| Phase 2 | argent-agent runtime (loop, session, tools, SIS) | Code complete            |
| Phase 3 | Integration (`ARGENT_RUNTIME=true` flag)         | **Active in production** |
| Phase 4 | Full Pi removal (\~145 files)                    | Not started              |

<Note>
  The Argent runtime is live in production. Pi code remains in the codebase for fallback but the feature flag routes all traffic through the Argent runtime.
</Note>