@sema-agent/core 1.279.0

package/LICENSE

@@ -0,0 +1,104 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             clay (github.com/clayboby)
+Licensed Work:        @sema-agent/core (sema-core)
+                      (formerly published as @sema-ai/core)
+                      The Licensed Work is (c) 2026 clay.
+Additional Use Grant: You may make production use of the Licensed Work for
+                      personal, educational, research, or other
+                      non-commercial purposes. Commercial production use
+                      requires a commercial license from the Licensor.
+Change Date:          2030-07-13
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact the Licensor.
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.
+
+-----------------------------------------------------------------------------
+
+Third-party notices
+
+Versions of this package up to and including 1.277.1 were published under the
+MIT License; those published copies remain governed by the license they were
+distributed under. This package incorporates design and (where noted) prompt
+content adapted from MIT-licensed projects — see NOTICE.md for attributions.

package/NOTICE.md

@@ -0,0 +1,30 @@
+# Third-party design & content attribution
+
+`@sema-agent/core` is licensed under the Business Source License 1.1 (BUSL-1.1; Change License: Apache-2.0, Change Date: 2030-07-13 — see LICENSE). Versions ≤1.277.1 were published under MIT. It incorporates design and (where noted) prompt content
+adapted from the following MIT-licensed projects. All are reused under the MIT License.
+
+## openclaw — https://github.com/openclaw/openclaw (MIT)
+Vendored source: the reusable agent core (`@openclaw/agent-core`) and `@openclaw/llm-core` live under
+`src/vendor/` with minimal modifications; that tree has since been fully rewritten into first-party
+code (design/118 de-vendoring, 2026-07-02). See `docs/vendor-history.md` for the baseline commit
+and the complete modification history.
+
+## CodeWhale (formerly DeepSeek CLI) — https://github.com/Hmbown/CodeWhale (MIT)
+Copyright (c) 2024-2025 DeepSeek CLI Contributors.
+Design adapted (re-implemented in TypeScript, not copied verbatim):
+- `src/core/memory.ts` — the user-memory pattern (persistent notes, a `remember` tool, the
+  `<user_memory>` system-prompt block, size truncation, timestamped bullets) is adapted from
+  CodeWhale's `crates/tui/src/memory.rs`.
+- `src/prompts/default.ts` — the default system prompt distills the *universal* agent disciplines
+  from CodeWhale's `prompts/base.md` "Constitution" (truth, duty of action, verification, tool-use
+  enforcement, hierarchy of authority) and `prompts/memory_guidance.md` (memory = declarative facts).
+  CodeWhale's project branding and coding-/DeepSeek-specific content are not used; the text here is a
+  domain-neutral rewrite.
+- `test/prompt-cache.test.ts` — the offline byte-prefix-cache simulation (multi-turn hit-rate guard)
+  is ported from CodeWhale's `crates/tui/tests/cache_guard.rs`.
+- `src/brain/openai.ts` — parsing prefix-cache-hit tokens from the response usage
+  (`prompt_tokens_details.cached_tokens` / `prompt_cache_hit_tokens`) follows CodeWhale's `client.rs`.
+
+## Anthropic engineering guidance (referenced, not code)
+Context-engineering and memory-tool design follow Anthropic's public engineering writing
+(context engineering, memory tool + context editing, managed agents, multi-agent systems).

package/README.md

@@ -0,0 +1,143 @@
+# @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, team discussions, 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, 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-agents, team discussions, teacher mode |
+| [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.

package/README.zh-CN.md

@@ -0,0 +1,138 @@
+# @sema-agent/core
+
+> **Claude Code 级 agent 引擎,以库的形态交付——模型你自己带。**
+
+`@sema-agent/core` 是一个**无状态、任务化**的 TypeScript/Node AI agent 引擎。LLM 由你提供
+(任意 OpenAI 兼容网关,或 Anthropic Messages API);引擎负责完整的 agent 循环——模型轮次、
+原生工具调用、MCP 服务器、会话记忆、自动上下文压缩、多 agent 委派——并返回机器可读的结果。
+
+```ts
+const res = await runner.runTask({ objective: "...", model: "main" });
+```
+
+## 它是什么 / 不是什么
+
+**它是:**
+
+- **一个库**(`npm install @sema-agent/core`),嵌进你自己的服务、CLI 或产品里。
+  一个 `Runner` 实例、普通函数调用、带类型的事件流。
+- **模型无关。**"大脑"是注入的流式补全函数。内置两类适配器:OpenAI 兼容的
+  `/v1/chat/completions` 端点(vLLM、Ollama、OpenRouter、DeepSeek、OpenAI)与
+  Anthropic Messages API。路由、故障转移、模型角色都是配置项。
+- **设计上无状态。**一个任务自带全套配置(模型、提示词、工具、MCP、skill、限额),
+  跑完返回一个 `TaskResult`。持久化——会话、检查点、长期记忆、workflow 日志——全部
+  藏在存储接口后面,可用文件或 Postgres 落地。
+
+**它不是:**
+
+- 不是聊天应用、CLI 产品或托管服务。没有 UI,也没有必须部署的服务端
+  (可选提供一个可嵌入的 HTTP/SSE 服务器 `createTaskServer`)。
+- 不绑定任何模型厂商。不带 API key、没有默认模型、不回传数据。
+- 不是提示词模板或"链式"框架。它是完整的 agent 运行时:循环、工具挂载、
+  安全闸门、持久化层,一个不少。
+
+## 核心亮点
+
+- **Claude Code 对齐的工具面。**内置 agent 工具集(文件读/写/编辑、支持后台执行的 shell、
+  grep/glob 搜索、子 agent 委派、todo/plan 面……)对齐 Claude Code 的工具契约,
+  并持续用活体探针验证。
+- **持久化检查点与人在环。**任务可以在审批闸、预算上限或显式检查点处挂起,稍后恢复——
+  甚至在另一个进程或机器上——背后是可插拔的 `CheckpointStore`(内存/文件/Postgres)。
+  任务状态语义明确:`completed | blocked | failed | timeout | suspended | needs_review`。
+- **记忆引擎。**带作用域的长期记忆,`MemoryBackend` 可插拔(文件或 Postgres);
+  配合自动压缩,长任务不会撑爆上下文窗口,也不会丢线索。
+- **多 agent。**子 agent 委派、team 讨论、确定性的 `runWorkflow` 编排(带可恢复日志),
+  以及可选启用的 observer agent(旁观并引导正在运行的 agent)。
+- **流式优先。**每个任务发出带类型的 `TaskEvent` 流(推理增量、文本增量、工具生命周期、
+  进度、诊断),经 `createTaskServer` 可直接接 SSE。
+- **内建安全模型。**工具策略的 allow/ask/deny 语义、按 principal 的授权、shell 闸门、
+  可持久化的审批挂起——不是事后补丁。
+- **小而诚实。**运行时依赖只有两个(`typebox`、`@modelcontextprotocol/sdk`)。
+  5400+ 条确定性 vitest 测试完全离线可跑(`npm test`),其中包括一个真实的 stdio MCP 服务器。
+- **源码可得。**BUSL-1.1:个人/教育/研究/非商用生产免费;2030-07-13 自动转 Apache-2.0。
+  见[许可](#许可)。
+
+## 60 秒上手
+
+要求:Node ≥ 20,以及一个 OpenAI 兼容网关(流式 + function calling)。
+
+```bash
+npm install @sema-agent/core
+```
+
+```ts
+import { Runner, createOpenAIBrain, type Model } from "@sema-agent/core";
+
+// 1) 描述模型(指向你自己的网关)
+const model: Model = {
+  id: "qwen-3.5-35b", name: "Qwen3.5-35B",
+  api: "openai-completions", provider: "vllm",
+  baseUrl: "http://localhost:8000/v1",          // 你的网关,结尾不带 /chat/completions
+  reasoning: true, input: ["text", "image"],
+  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+  contextWindow: 262144, maxTokens: 4096,
+};
+
+// 2) 建 Runner(brain = 外部 LLM;models = 你的模型目录)
+const runner = new Runner({
+  brain: createOpenAIBrain(),
+  models: { main: model },
+});
+
+// 3) 跑一个任务
+const res = await runner.runTask({
+  objective: "用三个要点总结 SSE 与 WebSocket 的取舍。",
+  model: "main",
+  sessionId: "chat-42",   // 传同一个 id 即继续对话;不传则开新会话
+});
+
+console.log(res.status);  // "completed" | "blocked" | "failed" | "timeout" | "suspended" | "needs_review"
+console.log(res.result);  // 最终回复文本
+```
+
+接下来:挂工具(`defineTool`、内置 SQL 工具、任务级 MCP)、逐 token 消费事件流、
+或把 Runner 暴露成 HTTP + SSE 服务——[SDK 指南](docs/sdk/README.md)按主题分章覆盖,
+从 [01 – Getting Started](docs/sdk/01-getting-started.md) 读起。
+
+## 文档导航
+
+| 文档 | 内容 |
+|------|------|
+| [SDK 指南(目录)](docs/sdk/README.md) | 完整 SDK 文档入口,按主题分 10 章 |
+| [01 – Getting Started](docs/sdk/01-getting-started.md) | 安装、60 秒集成、核心概念、可运行示例 |
+| [02 – Runner and Tasks](docs/sdk/02-runner-and-tasks.md) | `Runner`、`RunnerDeps`、`TaskSpec`、`TaskResult`、任务状态语义 |
+| [03 – Brains and Models](docs/sdk/03-brains-and-models.md) | Brain 契约、OpenAI/Anthropic 适配器、故障转移、模型角色、推理强度 |
+| [04 – Tools and MCP](docs/sdk/04-tools-and-mcp.md) | `defineTool`、SQL 工具、issue 工具、MCP 集成 |
+| [05 – Streaming and the HTTP Server](docs/sdk/05-streaming-and-http-server.md) | `TaskEvent` 协议、SSE、`createTaskServer` |
+| [06 – Sessions, Memory, and Compaction](docs/sdk/06-sessions-memory-and-compaction.md) | 会话存储、自动压缩、长期记忆后端 |
+| [07 – Multi-Agent](docs/sdk/07-multi-agent.md) | 子 agent、team 讨论、teacher 模式 |
+| [08 – Workflows](docs/sdk/08-workflows.md) | 确定性 `runWorkflow` 编排与可观测性 |
+| [09 – Security and Policies](docs/sdk/09-security-and-policies.md) | 工具策略、审批、shell 闸门、人在环监督 |
+| [10 – Extension Points](docs/sdk/10-extension-points.md) | 自定义 brain、会话存储、执行环境、Postgres 适配器 |
+| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 引擎内部结构 |
+| [docs/TESTING.md](docs/TESTING.md) | 测试体系与运行方式 |
+| [docs/REFERENCES.md](docs/REFERENCES.md) | 设计脉络与外部参考 |
+| [docs/ROADMAP.md](docs/ROADMAP.md) | 项目方向 |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | 如何参与贡献 |
+| [SECURITY.md](SECURITY.md) | 漏洞报告 |
+
+## 本地开发
+
+```bash
+npm install
+npx tsc --noEmit     # 类型检查(应为 0 错误)
+npm test             # vitest:全量确定性套件,离线,无需网关
+npm run smoke        # mock brain 端到端冒烟
+```
+
+需要真实网关的活体示例在 `src/examples/`。
+
+## 许可
+
+[BUSL-1.1](LICENSE)(Business Source License)。
+
+- 个人、教育、研究及非商用生产环境**免费**。
+- **商用生产环境需向许可方取得授权**。
+- **2030-07-13** 自动转为 **Apache-2.0**。
+
+准确条款以 [LICENSE](LICENSE) 文件为准。

package/dist/agents/agent-definition.d.ts

@@ -0,0 +1,3 @@
+import type { AgentDefinition } from "../core/types.js";
+export declare function defineAgent(def: AgentDefinition): AgentDefinition;
+//# sourceMappingURL=agent-definition.d.ts.map

package/dist/agents/agent-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.d.ts","sourceRoot":"","sources":["../../src/agents/agent-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AASxD,wBAAgB,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CASjE"}

package/dist/agents/agent-definition.js

@@ -0,0 +1,9 @@
+export function defineAgent(def) {
+    if (!def.name || !def.name.trim()) {
+        const e = new Error("defineAgent: `name` is required and must be a non-empty string.");
+        e.code = "config.agent.invalid";
+        throw e;
+    }
+    return Object.freeze({ ...def });
+}
+//# sourceMappingURL=agent-definition.js.map

package/dist/agents/agent-definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-definition.js","sourceRoot":"","sources":["../../src/agents/agent-definition.ts"],"names":[],"mappings":"AASA,MAAM,UAAU,WAAW,CAAC,GAAoB;IAC9C,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;QAClC,MAAM,CAAC,GAAG,IAAI,KAAK,CAAC,iEAAiE,CAA8B,CAAC;QACpH,CAAC,CAAC,IAAI,GAAG,sBAAsB,CAAC;QAChC,MAAM,CAAC,CAAC;IACV,CAAC;IAGD,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,GAAG,EAAE,CAAC,CAAC;AACnC,CAAC"}

package/dist/agents/builtin-agents.d.ts

@@ -0,0 +1,9 @@
+import type { AgentDefinition } from "../core/types.js";
+export declare const EXPLORE_WHEN_TO_USE = "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis \u2014 it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.";
+export declare const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches \u2014 when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
+export declare const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
+export declare const EXPLORE_SYSTEM_PROMPT = "You are a file search specialist. You excel at thoroughly navigating and exploring codebases.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYour strengths:\n- Rapidly finding files using glob patterns\n- Searching code and text with powerful regex patterns\n- Reading and analyzing file contents\n\nGuidelines:\n- Use Glob for broad file pattern matching\n- Use Grep for searching file contents with regex\n- Use Read when you know the specific file path you need to read\n- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n- Adapt your search approach based on the thoroughness level specified by the caller\n- Communicate your final report directly as a regular message - do NOT attempt to create files\n\nNOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:\n- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations\n- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files\n\nComplete the user's search request efficiently and report your findings clearly.";
+export declare const PLAN_SYSTEM_PROMPT = "You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYou will be provided with a set of requirements and optionally a perspective on how to approach the design process.\n\n## Your Process\n\n1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.\n\n2. **Explore Thoroughly**:\n   - Read any files provided to you in the initial prompt\n   - Find existing patterns and conventions using Glob, Grep, and Read\n   - Understand the current architecture\n   - Identify similar features as reference\n   - Trace through relevant code paths\n   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n\n3. **Design Solution**:\n   - Create implementation approach based on your assigned perspective\n   - Consider trade-offs and architectural decisions\n   - Follow existing patterns where appropriate\n\n4. **Detail the Plan**:\n   - Provide step-by-step implementation strategy\n   - Identify dependencies and sequencing\n   - Anticipate potential challenges\n\n## Required Output\n\nEnd your response with:\n\n### Critical Files for Implementation\nList 3-5 files most critical for implementing this plan:\n- path/to/file1.ts\n- path/to/file2.ts\n- path/to/file3.ts\n\nREMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.";
+export declare const BUILTIN_READONLY_DENY_TOOLS: (delegationToolName?: string) => string[];
+export declare function builtinAgentDefinitions(delegationToolName?: string): AgentDefinition[];
+//# sourceMappingURL=builtin-agents.d.ts.map

package/dist/agents/builtin-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.d.ts","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAiDxD,eAAO,MAAM,mBAAmB,mnBACikB,CAAC;AAGlmB,eAAO,MAAM,wBAAwB,4ZACiX,CAAC;AAGvZ,eAAO,MAAM,gBAAgB,uOACyM,CAAC;AAGvO,eAAO,MAAM,qBAAqB,64DAgC+C,CAAC;AAGlF,eAAO,MAAM,kBAAkB,wwEAiDkH,CAAC;AASlJ,eAAO,MAAM,2BAA2B,wBAAwB,MAAM,KAAkC,MAAM,EAO7G,CAAC;AASF,wBAAgB,uBAAuB,CAAC,kBAAkB,GAAE,MAAqC,GAAG,eAAe,EAAE,CAkBpH"}

package/dist/agents/builtin-agents.js

@@ -0,0 +1,114 @@
+const DEFAULT_DELEGATION_TOOL_NAME = "Agent";
+export const EXPLORE_WHEN_TO_USE = 'Fast read-only search agent for locating code. Use it to find files by pattern (eg. "src/components/**/*.tsx"), grep for symbols or keywords (eg. "API endpoints"), or answer "where is X defined / which files reference Y." Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis — it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: "quick" for a single targeted lookup, "medium" for moderate exploration, or "very thorough" to search across multiple locations and naming conventions.';
+export const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches — when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
+export const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
+export const EXPLORE_SYSTEM_PROMPT = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use Glob for broad file pattern matching
+- Use Grep for searching file contents with regex
+- Use Read when you know the specific file path you need to read
+- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+- Adapt your search approach based on the thoroughness level specified by the caller
+- Communicate your final report directly as a regular message - do NOT attempt to create files
+
+NOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:
+- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations
+- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files
+
+Complete the user's search request efficiently and report your findings clearly.`;
+export const PLAN_SYSTEM_PROMPT = `You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.
+
+=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===
+This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
+- Creating new files (no Write, touch, or file creation of any kind)
+- Modifying existing files (no Edit operations)
+- Deleting files (no rm or deletion)
+- Moving or copying files (no mv or cp)
+- Creating temporary files anywhere, including /tmp
+- Using redirect operators (>, >>, |) or heredocs to write to files
+- Running ANY commands that change system state
+
+Your role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.
+
+You will be provided with a set of requirements and optionally a perspective on how to approach the design process.
+
+## Your Process
+
+1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.
+
+2. **Explore Thoroughly**:
+   - Read any files provided to you in the initial prompt
+   - Find existing patterns and conventions using Glob, Grep, and Read
+   - Understand the current architecture
+   - Identify similar features as reference
+   - Trace through relevant code paths
+   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)
+   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification
+
+3. **Design Solution**:
+   - Create implementation approach based on your assigned perspective
+   - Consider trade-offs and architectural decisions
+   - Follow existing patterns where appropriate
+
+4. **Detail the Plan**:
+   - Provide step-by-step implementation strategy
+   - Identify dependencies and sequencing
+   - Anticipate potential challenges
+
+## Required Output
+
+End your response with:
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.ts
+- path/to/file2.ts
+- path/to/file3.ts
+
+REMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.`;
+export const BUILTIN_READONLY_DENY_TOOLS = (delegationToolName = DEFAULT_DELEGATION_TOOL_NAME) => [
+    delegationToolName,
+    "Artifact",
+    "ExitPlanMode",
+    "Edit",
+    "Write",
+    "NotebookEdit",
+];
+export function builtinAgentDefinitions(delegationToolName = DEFAULT_DELEGATION_TOOL_NAME) {
+    const denyTools = BUILTIN_READONLY_DENY_TOOLS(delegationToolName);
+    return [
+        {
+            name: "Explore",
+            whenToUse: EXPLORE_WHEN_TO_USE,
+            whenToUseLean: EXPLORE_WHEN_TO_USE_LEAN,
+            denyTools,
+            systemPrompt: EXPLORE_SYSTEM_PROMPT,
+        },
+        {
+            name: "Plan",
+            whenToUse: PLAN_WHEN_TO_USE,
+            denyTools: [...denyTools],
+            systemPrompt: PLAN_SYSTEM_PROMPT,
+        },
+    ];
+}
+//# sourceMappingURL=builtin-agents.js.map

package/dist/agents/builtin-agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-agents.js","sourceRoot":"","sources":["../../src/agents/builtin-agents.ts"],"names":[],"mappings":"AAIA,MAAM,4BAA4B,GAAG,OAAO,CAAC;AA6C7C,MAAM,CAAC,MAAM,mBAAmB,GAC9B,+lBAA+lB,CAAC;AAGlmB,MAAM,CAAC,MAAM,wBAAwB,GACnC,oZAAoZ,CAAC;AAGvZ,MAAM,CAAC,MAAM,gBAAgB,GAC3B,oOAAoO,CAAC;AAGvO,MAAM,CAAC,MAAM,qBAAqB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iFAgC4C,CAAC;AAGlF,MAAM,CAAC,MAAM,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iJAiD+G,CAAC;AASlJ,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,qBAA6B,4BAA4B,EAAY,EAAE,CAAC;IAClH,kBAAkB;IAClB,UAAU;IACV,cAAc;IACd,MAAM;IACN,OAAO;IACP,cAAc;CACf,CAAC;AASF,MAAM,UAAU,uBAAuB,CAAC,qBAA6B,4BAA4B;IAC/F,MAAM,SAAS,GAAG,2BAA2B,CAAC,kBAAkB,CAAC,CAAC;IAClE,OAAO;QACL;YACE,IAAI,EAAE,SAAS;YACf,SAAS,EAAE,mBAAmB;YAC9B,aAAa,EAAE,wBAAwB;YACvC,SAAS;YACT,YAAY,EAAE,qBAAqB;SAEpC;QACD;YACE,IAAI,EAAE,MAAM;YACZ,SAAS,EAAE,gBAAgB;YAC3B,SAAS,EAAE,CAAC,GAAG,SAAS,CAAC;YACzB,YAAY,EAAE,kBAAkB;SACjC;KACF,CAAC;AACJ,CAAC"}

package/dist/agents/cascade.d.ts

@@ -0,0 +1,44 @@
+import type { Runner } from "../core/runner/runtask.js";
+import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
+export type GateVerdict = boolean | {
+    pass: boolean;
+    diagnostics?: string;
+};
+export interface CascadeRung {
+    model: ModelRef;
+    overrides?: Partial<Pick<TaskSpec, "limits" | "degrade" | "systemPrompt">>;
+}
+export interface CascadeConfig {
+    ladder: CascadeRung[];
+    gate?: (result: TaskResult, rung: {
+        index: number;
+        model: ModelRef;
+    }) => GateVerdict | Promise<GateVerdict>;
+    maxEscalations?: number;
+    costCeilingMicroUsd?: number;
+    totalTimeoutMs?: number;
+    onRung?: (info: {
+        index: number;
+        model: ModelRef;
+        passed: boolean;
+        result: TaskResult;
+    }) => void;
+}
+export interface CascadeAttempt {
+    index: number;
+    model: ModelRef;
+    passed: boolean;
+    costMicroUsd: number;
+    status: TaskResult["status"];
+    errorCode?: string;
+    gateError?: string;
+    diagnostics?: string;
+}
+export interface CascadeRunResult extends TaskResult {
+    cascadeOutcome: "passed" | "exhausted";
+    escalated: boolean;
+    finalRung: number;
+    attempts: CascadeAttempt[];
+}
+export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig): Promise<CascadeRunResult>;
+//# sourceMappingURL=cascade.d.ts.map

package/dist/agents/cascade.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cascade.d.ts","sourceRoot":"","sources":["../../src/agents/cascade.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAwBvE,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,WAAW;IAE1B,KAAK,EAAE,QAAQ,CAAC;IAEhB,SAAS,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,cAAc,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,aAAa;IAE5B,MAAM,EAAE,WAAW,EAAE,CAAC;IActB,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAA;KAAE,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAE5G,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAE7B,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,QAAQ,CAAC;QAAC,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;CAClG;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE7B,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAiB,SAAQ,UAAU;IAMlD,cAAc,EAAE,QAAQ,GAAG,WAAW,CAAC;IAEvC,SAAS,EAAE,OAAO,CAAC;IAEnB,SAAS,EAAE,MAAM,CAAC;IAIlB,QAAQ,EAAE,cAAc,EAAE,CAAC;CAC5B;AAoBD,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,QAAQ,EACd,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC,CA6K3B"}