sakura-agent 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Vist233
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# Sakura
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**Sakura is an embeddable TypeScript SDK for building coding agents with resumable sessions and configurable tool execution.**
+
+Sakura grew out of a need to run an agent as part of an application and control its models, sessions, and tools from code. The `sakura` CLI uses the same SDK for terminal and script workflows.
+
+## Run the examples
+
+Use Node.js 26 and npm.
+
+Install a published version with `npm install sakura-agent`. The commands below run the examples from source.
+
+```sh
+git clone https://github.com/Vist233/Sakura.git
+cd Sakura
+npm ci
+npm run example
+npm run example:tools
+```
+
+The examples use a scripted model by default. Set `DEEPSEEK_API_KEY` to run them with DeepSeek. The [tool example](examples/tools.ts) registers a function and shows the agent calling it.
+
+## Create an agent and add tools
+
+Import from `sakura-agent` in an installed package. In this repository, the same API is available from `sdk/index.ts`. The following example expects `DEEPSEEK_API_KEY` in the environment.
+
+```ts
+import { compatPresets, corePlugins, createAgent, limitsPlugin } from "sakura-agent";
+import type { Plugin } from "sakura-agent";
+
+const apiKey = process.env.DEEPSEEK_API_KEY;
+if (!apiKey) throw new Error("Set DEEPSEEK_API_KEY.");
+
+const projectTools: Plugin = {
+  name: "project-tools",
+  setup(api) {
+    api.registerTool({
+      name: "project_status",
+      description: "Return the status of the sample project.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      effect: "read",
+      async execute() {
+        return { content: [{ type: "text", text: "Build passed." }] };
+      },
+    });
+  },
+};
+
+const agent = await createAgent({
+  model: {
+    baseUrl: "https://api.deepseek.com",
+    apiKey,
+    model: "deepseek-flash",
+    contextWindow: 128_000,
+    compat: compatPresets.deepseek,
+  },
+  cwd: process.cwd(),
+  tools: ["read"],
+  plugins: [
+    ...corePlugins().filter((plugin) => plugin.name !== "limits"),
+    limitsPlugin({ maxTurns: 8 }),
+    projectTools,
+  ],
+  sessionFile: ".sakura/session.jsonl",
+  maxTokens: 1_024,
+});
+
+try {
+  const run = agent.run("Call project_status and tell me the result.");
+  for await (const event of run.events) {
+    if (event.type === "tool_start") console.log(event.call.name);
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      for (const part of event.message.content) if (part.type === "text") console.log(part.text);
+    }
+  }
+  console.log(await run.result);
+} finally {
+  await agent.close();
+}
+```
+
+| Configuration | What it controls |
+| --- | --- |
+| `model` | Provider URL, API key, model name, and context window. You can also pass an `LlmClient`. |
+| `tools` | Selects built-in tools from `read`, `write`, `edit`, and `bash`. Pass `[]` to disable them. |
+| `plugins` | Registers custom tools or adds behavior. This list replaces the defaults, so include the desired `corePlugins()`. Validate tool arguments in `execute()`. |
+| `mcp` | Starts stdio MCP servers and exposes their tools to the agent. |
+| `cwd`, `environment` | Choose the tool working directory or supply a custom execution environment. |
+| `sessionFile` | Saves the session as JSONL. To resume, create an agent with the same file and call `agent.run()` without a prompt. |
+| `maxTokens`, `limitsPlugin()` | Set a per-request output limit and session or run budgets. |
+
+For an existing stdio MCP server, add this property to the same configuration. Use your own server command and arguments. Check `agent.mcp` for startup status.
+
+```ts
+mcp: {
+  servers: {
+    project: { command: "node", args: ["./your-mcp-server.mjs"] },
+  },
+  expose: "direct",
+}
+```
+
+## Use the CLI
+
+From source, run `npm run build` and use `node dist/sdk/cli.js` in place of `sakura`. An installed package provides the `sakura` executable. Set `DEEPSEEK_API_KEY` or `SAKURA_API_KEY` first.
+
+```sh
+sakura run "Read README.md and summarize it" --tools read --session .sakura/demo.jsonl
+sakura resume --tools read --session .sakura/demo.jsonl
+sakura --help
+```
+
+Add `--json` for JSON lines or use `--cwd`, `--base-url`, `--model`, and `--context-window` to configure the run. The CLI starts with no built-in tools unless you select them.
+
+## Choose where tools run
+
+The SDK manages the agent loop, model requests, and session state. The execution environment handles files and shell commands. Use `createLocalEnvironment()` for local execution or `createRemoteEnvironment({ cwd, run })` with a runner you provide. For example, a local application can manage sessions while a Linux worker runs builds with its own dependencies.
+
+The default local environment uses the calling process's permissions. `cwd` selects a working directory. Use an isolated runner for untrusted workloads. Session files and JSON event logs can contain sensitive content. Review and redaction are opt-in, and a separate reviewer client needs its own redaction wrapper.
+
+## Validation
+
+The public CI runs offline checks on Linux and macOS. In a separate local evaluation with DeepSeek Flash, Sakura passed 10 Lean proof checks and 20 append-log checks. Across both tasks it passed 96 background checks. The evaluation used an external isolation layer and resumed from checkpoints after transport failures.
+
+```sh
+npm run check
+```
+
+## License
+
+[MIT](LICENSE) · [Third-party notices](THIRD_PARTY_NOTICES.md) · [Previous Python source](https://github.com/Vist233/Sakura/tree/3e9b52cca7ff9e69fc6fc5d4b865b5e44ac338dd)

package/README.zh-CN.md

@@ -0,0 +1,133 @@
+# Sakura
+
+[English](README.md) · [简体中文](README.zh-CN.md)
+
+**Sakura 是一个可嵌入应用的 TypeScript SDK，用于构建支持会话恢复和可配置工具执行的编程 Agent。**
+
+Sakura 源于一个实际需求：让 Agent 在自己的应用里运行，从代码控制模型、会话和工具。`sakura` CLI 使用同一套 SDK，可在终端或脚本里调用。
+
+## 运行示例
+
+使用 Node.js 26 和 npm。
+
+已发布的版本可用 `npm install sakura-agent` 安装。下面的命令从源码运行示例。
+
+```sh
+git clone https://github.com/Vist233/Sakura.git
+cd Sakura
+npm ci
+npm run example
+npm run example:tools
+```
+
+示例默认使用脚本模型。设置 `DEEPSEEK_API_KEY` 后可用 DeepSeek 运行。[工具示例](examples/tools.ts) 会注册一个函数，并显示 Agent 对它的调用。
+
+## 创建 Agent 并添加工具
+
+安装包后从 `sakura-agent` 导入。本仓库中的相同接口位于 `sdk/index.ts`。下面的示例使用环境变量 `DEEPSEEK_API_KEY`。
+
+```ts
+import { compatPresets, corePlugins, createAgent, limitsPlugin } from "sakura-agent";
+import type { Plugin } from "sakura-agent";
+
+const apiKey = process.env.DEEPSEEK_API_KEY;
+if (!apiKey) throw new Error("Set DEEPSEEK_API_KEY.");
+
+const projectTools: Plugin = {
+  name: "project-tools",
+  setup(api) {
+    api.registerTool({
+      name: "project_status",
+      description: "Return the status of the sample project.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      effect: "read",
+      async execute() {
+        return { content: [{ type: "text", text: "Build passed." }] };
+      },
+    });
+  },
+};
+
+const agent = await createAgent({
+  model: {
+    baseUrl: "https://api.deepseek.com",
+    apiKey,
+    model: "deepseek-flash",
+    contextWindow: 128_000,
+    compat: compatPresets.deepseek,
+  },
+  cwd: process.cwd(),
+  tools: ["read"],
+  plugins: [
+    ...corePlugins().filter((plugin) => plugin.name !== "limits"),
+    limitsPlugin({ maxTurns: 8 }),
+    projectTools,
+  ],
+  sessionFile: ".sakura/session.jsonl",
+  maxTokens: 1_024,
+});
+
+try {
+  const run = agent.run("Call project_status and tell me the result.");
+  for await (const event of run.events) {
+    if (event.type === "tool_start") console.log(event.call.name);
+    if (event.type === "message_end" && event.message.role === "assistant") {
+      for (const part of event.message.content) if (part.type === "text") console.log(part.text);
+    }
+  }
+  console.log(await run.result);
+} finally {
+  await agent.close();
+}
+```
+
+| 配置 | 作用 |
+| --- | --- |
+| `model` | 设置服务地址、密钥、模型名和上下文窗口，也可传入 `LlmClient`。 |
+| `tools` | 从 `read`、`write`、`edit`、`bash` 中选择内置工具。传入 `[]` 可关闭。 |
+| `plugins` | 注册自定义工具或添加行为。这份列表会替换默认配置，需要的默认插件可从 `corePlugins()` 加回。在 `execute()` 中校验工具参数。 |
+| `mcp` | 启动 stdio MCP 服务，并向 Agent 暴露工具。 |
+| `cwd`、`environment` | 选择工具的工作目录，或提供自定义执行环境。 |
+| `sessionFile` | 把会话保存为 JSONL。恢复时用同一个文件创建 Agent，再调用无参数的 `agent.run()`。 |
+| `maxTokens`、`limitsPlugin()` | 设置单次请求的输出上限，以及会话或运行预算。 |
+
+接入已有 stdio MCP 服务时，把下面的属性加入同一份配置。换成实际的启动命令和参数，再通过 `agent.mcp` 检查启动状态。
+
+```ts
+mcp: {
+  servers: {
+    project: { command: "node", args: ["./your-mcp-server.mjs"] },
+  },
+  expose: "direct",
+}
+```
+
+## 使用 CLI
+
+从源码运行时，先执行 `npm run build`，再用 `node dist/sdk/cli.js` 代替 `sakura`。安装包提供 `sakura` 命令。先设置 `DEEPSEEK_API_KEY` 或 `SAKURA_API_KEY`。
+
+```sh
+sakura run "Read README.md and summarize it" --tools read --session .sakura/demo.jsonl
+sakura resume --tools read --session .sakura/demo.jsonl
+sakura --help
+```
+
+加 `--json` 可按行输出 JSON。用 `--cwd`、`--base-url`、`--model`、`--context-window` 配置运行。CLI 默认不开放内置工具，使用时按需选择。
+
+## 选择工具执行位置
+
+SDK 管理 Agent 循环、模型请求和会话状态。执行环境负责文件与 shell。用 `createLocalEnvironment()` 在本地执行，或给 `createRemoteEnvironment({ cwd, run })` 传入自己的执行器。例如，本地应用可以管理会话，把构建交给装好依赖的 Linux 工作环境。
+
+默认本地环境沿用进程权限。`cwd` 用于选择工作目录。不受信任的任务应使用隔离执行器。会话文件和 JSON 事件日志可能包含敏感内容。审核与脱敏按需启用，独立的审核客户端需要单独包装脱敏。
+
+## 验证
+
+公开 CI 在 Linux 和 macOS 跑离线检查。在一轮独立的本地 DeepSeek Flash 评测中，Sakura 通过了 10 项 Lean 证明检查和 20 项追加日志检查，两项任务合计通过 96 次后台校验。评测使用外部隔离，传输故障后从检查点续跑。
+
+```sh
+npm run check
+```
+
+## 许可
+
+[MIT](LICENSE) · [第三方许可](THIRD_PARTY_NOTICES.md) · [旧 Python 源码](https://github.com/Vist233/Sakura/tree/3e9b52cca7ff9e69fc6fc5d4b865b5e44ac338dd)

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,63 @@
+# Third-party notices
+
+This file registers every piece of third-party code that is copied, ported, or
+vendored into this repository. Entries under "Copied or ported" are the authoritative list; the
+"Planned sources" table lists upstream projects we may still borrow from.
+
+Rule: borrowing a design idea does not need an entry. Copying or porting code
+(including translating it to another language) does. Each ported file must carry
+a header comment naming its source, and a check script must fail the build when a
+ported file has no header (planned for milestone M0).
+
+## Copied or ported
+
+### packages/plugins/tools/src/edit-match.ts
+- Source: Pi (`pi-mono`), path `packages/coding-agent/src/core/tools/edit-diff.ts`, source snapshot dated 2026-10-04 (npm 1.5.0 was current at the time)
+- Licence: MIT
+- Copyright: Copyright (c) 2025 Mario Zechner
+- Changes: removed the diff-rendering helpers and the file-system and `diff` package imports; restructured into one `applyEdits` function; kept the fuzzy matching, line-ending handling, overlap detection, line-preserving replacement and the error messages
+- Licence text: `licenses/pi-mono-MIT.txt`
+
+### packages/plugins/tools/src/builtin/{read,write,edit,bash}.ts (tool descriptions)
+- Source: Pi (`pi-mono`), `packages/coding-agent/src/core/tools/{read,write,edit,bash}.ts` (description texts); the implementations are written fresh
+- Licence: MIT
+- Copyright: Copyright (c) 2025 Mario Zechner
+- Changes: shortened and reworded for our tool contracts (timeouts, non-interactive commands)
+- Licence text: `licenses/pi-mono-MIT.txt`
+
+### packages/agent/src/system-prompt.ts (rule texts)
+- Source: Pi (`pi-mono`) `packages/coding-agent/src/core/system-prompt.ts` and tool prompt snippets (structure and some rules); OpenAI Codex `codex-rs/protocol/src/prompts/base_instructions/default.md` (task-execution, validation and final-message principles)
+- Licence: Pi MIT; Codex Apache-2.0
+- Copyright: Copyright (c) 2025 Mario Zechner (Pi); OpenAI (Codex)
+- Changes: principles condensed and reworded into 11 general rules plus per-tool rules; no text copied verbatim from Codex; Pi's section layout (preamble, tools, rules, environment) followed
+- Licence text: `licenses/pi-mono-MIT.txt`, `licenses/codex-Apache-2.0.txt`
+
+### packages/plugins/redaction/src/rules.gen.ts (generated)
+- Source: gitleaks (`gitleaks/gitleaks`), `config/gitleaks.toml`, source snapshot dated 2026-11-06. The public workspace includes the generated rule table.
+- Licence: MIT
+- Copyright: Copyright (c) 2019 Zachary Rice
+- Changes: converted by `scripts/gen-secret-rules.py` into TypeScript data (regular expressions translated to JavaScript, 22 of 221 rules skipped because they do not translate; allowlists not used)
+- Licence text: `licenses/gitleaks-MIT.txt`
+
+## Planned sources (not yet copied)
+
+| Source | Licence | Upstream | Intended use | Status |
+|---|---|---|---|---|
+| Pi (`pi-mono`) | MIT, copyright Mario Zechner | `earendil-works/pi` | Edit-tool matching and the read/write/edit/bash tool descriptions are now ported (see below); system-prompt structure may follow; mcp client and codemode ideas | partly copied (see below) |
+| Magpie | MIT | `yetone/magpie` | Design reference for redaction (stable placeholders, streaming restore, fail closed). Not a code port any more (decision: only the essence) | not copied |
+| gitleaks | MIT (Zachary Rice) | `gitleaks/gitleaks` | Rule table converted for the redaction plugin (see above) | copied (see above) |
+| Codex | Apache-2.0 | `openai/codex` | Design reference (guardian reviewer, goal, compaction); base-instructions principles adapted into our system prompt (`protocol/src/prompts/base_instructions/default.md`), with changes noted. Other prompt texts are written fresh; if any text or code is copied, add an entry and keep the Apache-2.0 notice | not copied |
+| A2A | Apache-2.0 | `a2aproject/A2A` | Possible future protocol reference | not copied |
+| `quickjs-emscripten` | MIT (Fabrice Bellard's QuickJS, Jake Teton-Landis's bindings; checked on npm, all 7 installed packages report MIT) | npm | Runtime dependency of `packages/plugins/toolset` (codemode sandbox). Not copied, only installed. `quickjs-wasi` was the other candidate (also MIT), not used | dependency |
+| Mastra | not verified (GitHub reports NOASSERTION) | `mastra-ai/mastra` | Design reference only. **Do not copy code until the licence is read.** | not copied |
+
+## Entry format (use when code is actually copied or ported)
+
+```
+### <file or component in this repo>
+- Source: <repository URL>, path <path>, commit <hash>
+- Licence: <SPDX id>
+- Copyright: <holder, year>
+- Changes: <what was changed or translated>
+- Licence text: <path to the full licence text kept in this repository>
+```

package/dist/packages/agent/src/compose.d.ts

@@ -0,0 +1,25 @@
+import type { Plugin } from "../../kernel/src/index.js";
+/** A plugin that may say what it needs and what it offers. The kernel ignores the two extra fields. */
+export interface Composable extends Plugin {
+    /** Names (of plugins or of capabilities that plugins provide) that must be installed before this one. */
+    requires?: string[];
+    /** Capability names this plugin offers besides its own name, so others can depend on "what" rather than "who". */
+    provides?: string[];
+    /** Set by bundle(): lets compose() see through the bundle to the plugins inside it. */
+    children?: Plugin[];
+}
+/**
+ * One plugin made of several: installing it installs them all, in the order given. All three entry points are passed on
+ * (setup, prepare, afterCompaction); passing on only setup would silently drop the other two. Bundles may contain bundles.
+ * Give a bundle to createAgent (or to compose) and a plugin that is in two bundles is installed once.
+ */
+export declare function bundle(name: string, children: Plugin[]): Composable;
+export declare class CompositionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Turns a list of plugins that may contain and depend on each other into the flat, ordered list the kernel wants: bundles opened up,
+ * each plugin once, every plugin after the ones it requires. Throws before anything runs when a requirement is missing, the requirements
+ * form a cycle, or two different plugins share a name. Plugins keep the order they were listed in unless a requirement says otherwise.
+ */
+export declare function compose(listed: Plugin[]): Plugin[];

package/dist/packages/agent/src/compose.js

@@ -0,0 +1,91 @@
+const unique = (items) => [...new Set(items)];
+/**
+ * One plugin made of several: installing it installs them all, in the order given. All three entry points are passed on
+ * (setup, prepare, afterCompaction); passing on only setup would silently drop the other two. Bundles may contain bundles.
+ * Give a bundle to createAgent (or to compose) and a plugin that is in two bundles is installed once.
+ */
+export function bundle(name, children) {
+    const compensates = children.flatMap((child) => (child.compensates ? [child.compensates] : []));
+    const withPrepare = children.filter((child) => child.prepare);
+    const withAfter = children.filter((child) => child.afterCompaction);
+    return {
+        name,
+        children,
+        ...(compensates.length > 0 ? { compensates: compensates.join("; ") } : {}),
+        requires: unique(children.flatMap((child) => child.requires ?? [])),
+        provides: unique(children.flatMap((child) => [child.name, ...(child.provides ?? [])])),
+        setup(api) {
+            for (const child of children)
+                child.setup(api);
+        },
+        ...(withPrepare.length > 0
+            ? {
+                async prepare(context) {
+                    for (const child of withPrepare)
+                        await child.prepare?.(context);
+                },
+            }
+            : {}),
+        ...(withAfter.length > 0
+            ? {
+                async afterCompaction(context) {
+                    for (const child of withAfter)
+                        await child.afterCompaction?.(context);
+                },
+            }
+            : {}),
+    };
+}
+export class CompositionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CompositionError";
+    }
+}
+/**
+ * Turns a list of plugins that may contain and depend on each other into the flat, ordered list the kernel wants: bundles opened up,
+ * each plugin once, every plugin after the ones it requires. Throws before anything runs when a requirement is missing, the requirements
+ * form a cycle, or two different plugins share a name. Plugins keep the order they were listed in unless a requirement says otherwise.
+ */
+export function compose(listed) {
+    const providers = new Map(); // capability -> names of the plugins that offer it
+    const byName = new Map();
+    const open = (plugin, groups) => {
+        if (plugin.children) {
+            for (const child of plugin.children)
+                open(child, [...groups, plugin.name]);
+            return;
+        }
+        const known = byName.get(plugin.name);
+        if (known && known !== plugin)
+            throw new CompositionError(`two different plugins are named '${plugin.name}'`);
+        byName.set(plugin.name, plugin);
+        for (const capability of [plugin.name, ...(plugin.provides ?? []), ...groups])
+            providers.set(capability, (providers.get(capability) ?? new Set()).add(plugin.name));
+    };
+    for (const plugin of listed)
+        open(plugin, []);
+    const ordered = [];
+    const state = new Map();
+    const visit = (name, path) => {
+        if (state.get(name) === "done")
+            return;
+        if (state.get(name) === "visiting")
+            throw new CompositionError(`dependency cycle: ${[...path, name].join(" -> ")}`);
+        state.set(name, "visiting");
+        const plugin = byName.get(name);
+        for (const need of plugin.requires ?? []) {
+            const offered = providers.get(need);
+            if (!offered)
+                throw new CompositionError(`plugin '${name}' requires '${need}', which nothing provides`);
+            for (const provider of offered)
+                if (provider !== name)
+                    visit(provider, [...path, name]);
+        }
+        state.set(name, "done");
+        ordered.push(plugin);
+    };
+    for (const name of byName.keys())
+        visit(name, []);
+    return ordered;
+}

package/dist/packages/agent/src/index.d.ts

@@ -0,0 +1,92 @@
+import type { ChatCompat } from "../../llm/src/index.js";
+import type { CompactionConfig, Environment, LlmClient, Plugin, Prompts, RunHandle, ThinkingLevel, UserInput } from "../../kernel/src/index.js";
+import type { AgentDefinition } from "../../plugins/agents/src/index.js";
+import type { McpServerConfig, McpServerStatus } from "../../plugins/toolset/src/index.js";
+import type { RewindableLog } from "../../session/src/index.js";
+export interface ModelConfig {
+    /** Base URL without /chat/completions, for example https://api.deepseek.com */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    contextWindow: number;
+    compat?: Partial<ChatCompat>;
+    headers?: Record<string, string>;
+}
+export interface AgentConfig {
+    /** A provider to talk to, or a ready-made client (for tests). */
+    model: ModelConfig | LlmClient;
+    cwd?: string;
+    tools?: Array<"read" | "write" | "edit" | "bash">;
+    /** After this many milliseconds a running shell command is moved to the background (default 120000). */
+    bashSoftTimeoutMs?: number;
+    /** How long a command the model starts with `background: true` is watched before it is left to run (default 1000), so that one that fails at once is reported as failed. */
+    bashBackgroundGraceMs?: number;
+    /** Defaults to corePlugins(). Safety plugins (review, redaction, sandbox, sub-agents) are never in the default set. May contain bundles and plugins that say what they require; see compose(). */
+    plugins?: Plugin[];
+    /** Replaces the generated system prompt. */
+    system?: string;
+    /** Write the conversation to this JSONL file; without it the conversation lives in memory only. */
+    sessionFile?: string;
+    thinking?: ThinkingLevel;
+    maxTokens?: number;
+    goal?: {
+        objective: string;
+        verify?: string;
+    };
+    compaction?: false | Partial<CompactionConfig>;
+    prompts?: Partial<Prompts>;
+    environment?: Environment;
+    now?: () => number;
+    /**
+     * Wakes the agent by itself. When background work ends (a command moved to the background, a background sub-agent) and no run is going,
+     * a run is started so the agent hears about it; `onRun` receives each such run (to show its events). While work is still pending and the agent
+     * is quiet, it is woken once after `cacheCheckMs` (default 4 minutes, a little under the prompt cache lifetime) to check, and then left alone until something ends.
+     */
+    wake?: {
+        onRun(handle: RunHandle): void;
+        cacheCheckMs?: number;
+    };
+    /**
+     * MCP servers, started once when the agent is created (a server that fails is left out and shows in `agent.mcp`). Their tools are named mcp__<server>__<tool>.
+     * `expose`: "direct" declares every tool to the model; "search" lists only tool_search and tool_call; "codemode" lists only run_code, where read-only
+     * tools can be called from a script. The default is "direct" up to 10 tools and "search" above.
+     */
+    mcp?: {
+        servers: Record<string, McpServerConfig>;
+        expose?: "direct" | "search" | "codemode";
+        timeoutMs?: number;
+    };
+    /** Turns on sub-agents (delegate, agent_view, agent_stop). Off unless this is given. */
+    subAgents?: {
+        agents?: AgentDefinition[];
+        maxRegistered?: number;
+        maxRunning?: number;
+        /**
+         * Plugins (by name) that sub-agents do not get. Every other plugin of the agent is shared with its sub-agents, so review and redaction
+         * cannot be bypassed by delegating. Default: agents (no nesting), limits (a sub-agent has its own turn limit), context and tools (a sub-agent starts fresh).
+         */
+        notInherited?: string[];
+        /** Models by name, for sub-agent definitions that name one (`AgentDefinition.model`). A definition whose model is not in the table uses the parent's model. */
+        models?: Record<string, ModelConfig | LlmClient>;
+    };
+}
+export interface Agent {
+    /** Starts, resumes or follows up. See Kernel.run. */
+    run(input?: UserInput): RunHandle;
+    queue(text: string): void;
+    steer(text: string): void;
+    cancel(): void;
+    log: RewindableLog;
+    /** Goes back to an earlier point of the conversation (an entry id from `log.branch()`, or null for the very start); what is said next starts a new branch. */
+    rewindTo(entryId: string | null): void;
+    /** How each MCP server did when the agent was created (for the person running it; the model is not told). Empty without `mcp`. */
+    mcp: Record<string, McpServerStatus>;
+    /** Releases the session file lock. */
+    close(): Promise<void>;
+}
+/** The plugins every agent gets unless the caller passes its own list: project instructions (AGENTS.md), long tool output saved to files, resilience (replies that were cut off or came back empty are asked again), and limits (unlimited until configured). */
+export declare function corePlugins(): Plugin[];
+export declare function createAgent(config: AgentConfig): Promise<Agent>;
+export { buildSystemPrompt } from "./system-prompt.js";
+export { bundle, compose, CompositionError } from "./compose.js";
+export type { Composable } from "./compose.js";