# AgentRuntime

**Repository Path**: yys_cn_ccs/agent-runtime

## Basic Information

- **Project Name**: AgentRuntime
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-06
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AgentRuntime

Engineering-first multi-agent runtime.

Current stage: Phase 50 Conversation Chain Audit - fix, stabilization, and docs-only closure complete.

AgentRuntime runs in mock-model mode by default, so a fresh clone can start without provider API keys.

## Requirements

- Node.js 24 or newer.
- npm for running project scripts.
- Git for Git-aware tools and contribution workflows.

Windows PowerShell note: if script execution policy blocks `npm`, use `npm.cmd`.

## Quick Start

```bash
npm run dev -- "Design an implementation plan for login"
```

The default setup uses mock models and does not require API keys.

Open the local product surfaces after starting the server:

- Operator dashboard: `http://localhost:4317/`
- User chat surface: `http://localhost:4317/chat`

## Workspace

AgentRuntime separates **runtime home** (shipped product files) from **workspace** (your project working directory).

- **runtimeHome**: Where the AgentRuntime product is installed (`src/`, `bin/`, `public/`)
- **workspaceRoot**: Where `.agr/` runtime state is stored

By default, the workspace is `%USERPROFILE%/.agentruntime/default-workspace` on Windows and `~/.agentruntime/default-workspace` on Unix. This keeps the source repository clean of runtime artifacts.

To run against a specific project directory:

```bash
artime server start --workspace /path/to/your/project
# or
set AGENTRUNTIME_WORKSPACE_ROOT=D:\path\to\your\project
artime server start
```

To initialize a new workspace in a specific directory:

```bash
artime init /path/to/your/project
```

The `.agr/` directory should never be committed to version control — it is already listed in `.gitignore`.

## Core Commands

System CLI:

```bash
artime server start
artime server stop
artime server restart
artime server status
artime workflow run "Design an implementation plan for login"
artime workflow list
artime workflow resume <workflow-id>
artime workflow cancel <workflow-id>
artime workflow retry <workflow-id>
artime memory search "workflow persistence"
artime memory add project "Runtime convention" "AgentRuntime uses JSON workflow persistence."
artime audit export .agr/audit/export.json
artime plugin list
artime model test all
artime model health all
artime model long-run
artime council ci --json "Design an implementation plan for login"
artime smoke all
artime doctor --json
```

Register system CLI during development:

```bash
npm link
```

PowerShell note: if execution policy blocks `artime.ps1`, use `artime.cmd` or remove the generated `.ps1` shim so PowerShell resolves the `.cmd`.

NPM fallback:

```bash
npm run artime -- help
npm run artime -- server start
npm run artime -- server stop
npm run artime -- server restart
npm run artime -- server status
npm run artime -- workflow run "Design an implementation plan for login"
npm run artime -- workflow list
npm run artime -- workflow resume <workflow-id>
npm run artime -- workflow cancel <workflow-id>
npm run artime -- workflow retry <workflow-id>
npm run artime -- memory search "workflow persistence"
npm run artime -- memory add project "Runtime convention" "AgentRuntime uses JSON workflow persistence."
npm run artime -- audit export .agr/audit/export.json
npm run artime -- plugin list
npm run artime -- model test all
npm run artime -- model health all
npm run artime -- model long-run
npm run artime -- council ci --json "Design an implementation plan for login"
npm run artime -- smoke all
npm run artime -- doctor --json
```

Canonical npm script groups:

```bash
npm run check
npm run check:package
npm run smoke
npm run smoke:routing
npm run smoke:product-surface
npm run smoke:data-integrity
npm run smoke:runtime-quality
npm run smoke:governance
npm run smoke:acceptance
npm run smoke:provider-hardening
npm run smoke:api
npm run smoke:tool
npm run smoke:doctor
npm run doctor
npm run workflow:list
npm run workflow:resume -- <workflow-id>
npm run workflow:cancel -- <workflow-id>
npm run workflow:retry -- <workflow-id>
npm run memory:add -- project "Runtime convention" "AgentRuntime uses JSON workflow persistence."
npm run memory:search -- "workflow persistence"
```

Legacy aliases such as `api:smoke`, `tool:smoke`, and `council:smoke` remain available for compatibility with historical runbooks and validation records.

## Model Configuration

Copy the env template:

```bash
copy .env.example .env
```

Optional values:

```text
ANTHROPIC_API_KEY=
OPENAI_COMPATIBLE_API_KEY=
OPENAI_COMPATIBLE_BASE_URL=
DEEPSEEK_API_KEY=
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1
MINIMAX_API_KEY=
MINIMAX_BASE_URL=https://api.minimax.io/v1
```

Without API keys, the runtime falls back to mock models. Named compatible model ids such as `deepseek:deepseek-chat` and `minimax:MiniMax-M2.7` let different Council reviewers use different providers in one workflow.

## Security Model

AgentRuntime can inspect files, run allowlisted shell commands, call external model providers, and persist local workflow state. Keep these defaults in mind before running it on sensitive repositories:

- `.env`, `.env.*`, `.agr/`, `.agr.example.env`, logs, and runtime exports are ignored by Git.
- Use `.env.example` or `.env.production.example` as templates; never commit real API keys.
- Keep `SHELL_RUN_ALLOWLIST` narrow. The runtime only executes commands that match the configured allowlist.
- Real providers are optional. Mock models remain the safe default for CI and first-run evaluation.
- Review `SECURITY.md` before exposing the server outside localhost or enabling operator tokens.

## Docs

Start with the docs hub:

- `docs/README.md`

Most-used references:

- Legacy engineering plan: `docs/history/agent-runtime-engineering-plan.md`
- Capability index: `docs/reference/capabilities.md`
- Tool system: `docs/reference/tool-system.md`
- Model routing: `docs/reference/model-routing.md`
- Dashboard / API: `docs/reference/dashboard.md`
- Deployment: `docs/reference/deployment.md`
- Repository layout: `docs/reference/repository-layout.md`
- Validation records: `docs/validation/`
- Release notes: `docs/status/release-notes.md`
- TODO / roadmap closeout: `TODO.md`

## Current Capabilities

- Multi-agent workflow orchestration with planning, execution, verification, repair, and synthesis
- Controlled tool execution for file, shell, git, and runtime operations
- JSON workflow, event, run, and memory persistence with replay and recovery
- Model routing, provider policy, cost tracking, and circuit-breaker hardening
- Local API server, dashboard, and user chat surface
- RBAC, audit, doctor, plugin, and operator tooling
- Real-world validation through Gate 1, Gate 2, and Gate 3

For the full capability inventory, use `docs/reference/capabilities.md`.

## Completed Roadmap

The original implementation roadmap ran through Phase 50 and is now complete.

For the current end state, use:

- `TODO.md`
- `docs/agent-handoff/claude-current-context.md`
- `docs/status/roadmap.md`
- `docs/status/release-notes.md`