@sema-agent/core/README.md

Stateless, task-oriented AI agent core

# @sema-agent/core

> **Claude Code-grade agent engine, as a library — bring your own model.**

`@sema-agent/core` is a stateless, task-oriented AI agent engine for TypeScript/Node. You supply the
LLM (any OpenAI-compatible gateway, or the Anthropic Messages API); the engine runs the entire
agent loop — model turns, native tool calls, MCP servers, session memory, automatic context
compaction, multi-agent delegation — and returns a machine-readable result.

```ts
const res = await runner.runTask({ objective: "...", model: "main" });
```

## What it is / what it is not

**It is:**

- A **library** (`npm install @sema-agent/core`), embedded in your own service, CLI, or product.
  One `Runner` instance, plain function calls, typed events.
- **Model-agnostic.** The "brain" is an injected streaming-completion function. Adapters ship for
  OpenAI-compatible `/v1/chat/completions` endpoints (vLLM, Ollama, OpenRouter, DeepSeek, OpenAI)
  and for the Anthropic Messages API. Routing, failover, and model roles are configuration.
- **Stateless by design.** A task carries its full configuration (model, prompt, tools, MCP,
  skills, limits) and returns a `TaskResult`. Persistence — sessions, checkpoints, long-term
  memory, workflow journals — lives behind storage interfaces you can back with files or Postgres.

**It is not:**

- Not a chat app, CLI product, or hosted service. There is no UI and no server you must run
  (an optional embeddable HTTP/SSE server, `createTaskServer`, is provided).
- Not tied to any model vendor. It ships no API key, no default model, and no phone-home.
- Not a prompt-template or "chain" framework. It is a full agent runtime: the loop, the tool
  harness, the safety gates, and the durability layer.

## Highlights

- **Claude Code-parity tool surface.** The built-in agent toolset (file read/write/edit, shell with
  background execution, grep/glob search, sub-agent delegation, todo/plan surfaces …) tracks the
  behavior of Claude Code's tool contract, continuously verified against live probes.
- **Durable checkpoints and human-in-the-loop.** Tasks can suspend on approval gates, budget
  limits, or explicit checkpoints and resume later — on another process or machine — via a
  pluggable `CheckpointStore` (in-memory, file, Postgres). Task statuses are explicit:
  `completed | blocked | failed | timeout | suspended | needs_review`.
- **Memory engine.** Scoped long-term memory with a pluggable `MemoryBackend`
  (file-backed or Postgres), plus automatic in-context compaction that keeps long runs inside the
  model's context window without losing the thread.
- **Multi-agent.** Sub-agent delegation, deterministic `runWorkflow`
  orchestration with durable journals, and opt-in observer agents that monitor and steer a run.
- **Streaming first.** Every task emits a typed `TaskEvent` stream (reasoning deltas, text deltas,
  tool lifecycle, progress, diagnostics), ready to pipe into SSE via `createTaskServer`.
- **Security model built in.** Tool policies with allow/ask/deny semantics, per-principal
  authorization, shell gating, and durable approval suspension — not bolted on.
- **Small and honest.** Two runtime dependencies (`typebox`, `@modelcontextprotocol/sdk`).
  A deterministic vitest suite of 5,400+ tests runs fully offline (`npm test`), including a real
  stdio MCP server.
- **Source-available.** BUSL-1.1: free for personal, educational, research, and non-commercial
  production use; converts to Apache-2.0 on 2030-07-13. See [License](#license).

## Quick start (60 seconds)

Requirements: Node ≥ 20 and an OpenAI-compatible gateway (streaming + function calling).

```bash
npm install @sema-agent/core
```

```ts
import { Runner, createOpenAIBrain, type Model } from "@sema-agent/core";

// 1) Describe the model (points at YOUR gateway).
const model: Model = {
  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
  api: "openai-completions", provider: "vllm",
  baseUrl: "http://localhost:8000/v1",          // your gateway; no trailing /chat/completions
  reasoning: true, input: ["text", "image"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 262144, maxTokens: 4096,
};

// 2) Build a Runner (brain = the external LLM; models = your catalog).
const runner = new Runner({
  brain: createOpenAIBrain(),
  models: { main: model },
});

// 3) Run a task.
const res = await runner.runTask({
  objective: "Summarize the trade-offs between SSE and WebSockets in three bullet points.",
  model: "main",
  sessionId: "chat-42",   // pass the same id to continue a conversation; omit for a fresh one
});

console.log(res.status);  // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
console.log(res.result);  // final assistant text
```

Add tools (`defineTool`, the built-in SQL tool, or task-scoped MCP servers), stream events
token-by-token (`runTaskStream`: answer text is `text_delta`; thinking is `reasoning_delta` — the
provider-level `thinking_delta` name is not on the task stream, and there is no thinking start / end
frame, so add the deltas up yourself), or expose the runner over HTTP + SSE — the
[SDK guide](docs/sdk/README.md) covers each step, starting with
[01 – Getting Started](docs/sdk/01-getting-started.md).

## Documentation

| Document | What it covers |
|----------|----------------|
| [SDK Guide (index)](docs/sdk/README.md) | Entry point for the full SDK documentation, split into 10 chapters |
| [01 – Getting Started](docs/sdk/01-getting-started.md) | Installation, the 60-second integration, core concepts, runnable examples |
| [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md) | `Runner`, `RunnerDeps`, `TaskSpec`, `TaskResult`, task status semantics |
| [03 – Brains and Models](docs/sdk/03-brains-and-models.md) | Brain contract, OpenAI/Anthropic adapters, failover, model roles, reasoning intensity |
| [04 – Tools and MCP](docs/sdk/04-tools-and-mcp.md) | `defineTool`, the SQL tool, issue-tracker tools, MCP integration |
| [05 – Streaming and the HTTP Server](docs/sdk/05-streaming-and-http-server.md) | The `TaskEvent` protocol, SSE, `createTaskServer` |
| [06 – Sessions, Memory, and Compaction](docs/sdk/06-sessions-memory-and-compaction.md) | Session stores, automatic compaction, long-term memory backends |
| [07 – Multi-Agent](docs/sdk/07-multi-agent.md) | Sub-agent delegation, multi-perspective discussion via sub-agents, cross-session peer messaging |
| [08 – Workflows](docs/sdk/08-workflows.md) | Deterministic `runWorkflow` orchestration and observability |
| [09 – Security and Policies](docs/sdk/09-security-and-policies.md) | Tool policies, approvals, shell gating, human-in-the-loop supervision |
| [10 – Extension Points](docs/sdk/10-extension-points.md) | Custom brains, session stores, execution environments, Postgres adapters |
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | How the engine is put together internally |
| [docs/TESTING.md](docs/TESTING.md) | The test system and how to run it |
| [docs/REFERENCES.md](docs/REFERENCES.md) | Design lineage and external references |
| [docs/ROADMAP.md](docs/ROADMAP.md) | Where the project is heading |
| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute |
| [SECURITY.md](SECURITY.md) | Reporting vulnerabilities |

## Development

```bash
npm install
npx tsc --noEmit     # type-check (expect 0 errors)
npm test             # vitest: full deterministic suite, offline, no gateway needed
npm run smoke        # mock-brain end-to-end smoke
```

Runnable live examples (require a reachable model gateway) live in `src/examples/`.

## License

[BUSL-1.1](LICENSE) (Business Source License).

- **Free** for personal, educational, research, and non-commercial production use.
- **Commercial production use requires a license** from the licensor.
- On **2030-07-13** the license automatically converts to **Apache-2.0**.

See the [LICENSE](LICENSE) file for the exact terms.