fluffy-context 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fluffy_CX
+
+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,31 +1,30 @@
 # Context Runtime
 
-Context Runtime 是一个面向 AI 编程会话的本地上下文运行时 CLI。它把一次任务的进度、决策、待办、风险、知识和已验证死路保存为可恢复的结构化状态，帮助 Agent 在新会话中快速完成交接，而不是重新阅读大量项目内容。
+`fluffy-context` 是面向 AI 编程会话的本地 Context Runtime CLI。0.3.0 提供可重复、安全调用的任务定位入口、MCP 工具，以及 Claude Code 的阶段性工作流引导，让 Agent 不必自行拼接恢复、共识发现与短期记录。
 
-它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更，Context Runtime 负责 AI 工作状态的版本化保存与恢复。
+它更接近“Context 的 Git”，而不是代码备份工具：Git 仍然负责代码和真实文件变更；Context Runtime 负责 AI 工作状态、已验证共识与交接信息的本地保存和恢复。
 
 ## 适用场景
 
-- 下班前保存当前任务状态，第二天继续工作。
-- 保存完成项、待办、阻塞、决策和风险。
-- 将可复用业务知识独立记录，并在确认后纳入知识库。
-- 记录已经验证不可行的方案，避免新会话重复探索。
-- 通过摘要预算恢复上下文，减少不必要的 Token 消耗。
+- 下班前保存当前任务状态，下一次会话继续工作。
+- 以有界摘要恢复进行中的任务，降低重复阅读和 Token 消耗。
+- 让 Agent 在开始任务时获得已验证 Knowledge、匹配 Deadend 与未吸收 Note。
+- 通过 MCP 或 Claude Code Hooks 降低 Agent 主动调用 Context 工具的决策成本。
+- 记录完成项、待办、阻塞、决策、风险与已验证不可行的方案。
 
 ## 环境要求
 
 - Node.js `>=20.19.0`
-- Git 可选。项目位于 Git 仓库内时，CLI 会记录当前分支和 commit 信息。
+- Git 可选。项目在 Git 仓库内时，CLI 会记录分支与 commit。
 
 ## 安装
 
-发布后可以使用 npm 全局安装：
-
 ```bash
 npm install --global fluffy-context
+ctx --help
 ```
 
-也可以在项目目录中直接运行：
+也可以在项目目录中使用：
 
 ```bash
 npx fluffy-context --help
@@ -33,26 +32,13 @@ npx fluffy-context --help
 
 ## 快速开始
 
-在项目根目录初始化 Context Runtime：
+在项目根目录初始化：
 
 ```bash
 ctx init
 ```
 
-这会创建以下本地文件：
-
-```text
-.context/
-├── manifest.json
-├── index.json
-├── contexts/
-├── locks/
-├── knowledge.json    # 首次使用 learn 后创建
-└── deadends.json     # 首次使用 deadend 后创建
-.contextignored
-```
-
-保存一次工作状态：
+这会创建本地 `.context/` 存储和 `.contextignored` 规则文件。保存阶段性工作：
 
 ```bash
 ctx checkpoint \
@@ -62,181 +48,145 @@ ctx checkpoint \
   --pending "补充异常路径测试,运行集成测试" \
   --decisions "订单状态由服务端状态机统一维护" \
   --risks "第三方回调可能重复到达" \
-  --files "src/order/state-machine.ts,src/order/state-machine.test.ts"
+  --files "src/order/state-machine.ts,src/order-state-machine.test.ts"
 ```
 
-第二天恢复：
+新会话中，Agent 或宿主优先使用：
 
 ```bash
-ctx resume
+ctx orient "订单状态机异常路径" --max-chars 4000
 ```
 
-`resume` 默认返回轻量摘要，同时保留完整详情供按需使用。可以限制摘要字符数：
+`ctx orient` 只读地聚合当前 Context 摘要、与查询匹配的**已验证** Knowledge 和 Deadend，以及当前 Context 尚未吸收的 Note。它不更新 `lastUsedAt`、不创建 Snapshot，也不会记录 usage 噪声。省略查询时可只恢复当前任务和 open Notes：
 
 ```bash
-ctx resume --max-chars 2000
+ctx orient
+ctx orient --context <context-id> --note-limit 10
 ```
 
-## 常用命令
-
-### `ctx init`
+## Agent 工作流
 
-初始化项目的 Context Runtime 存储布局。重复执行是幂等的，不会覆盖已有 Context 或项目忽略规则。
+推荐阶段：
 
-```bash
-ctx init
-ctx init path/to/project
-ctx init --path path/to/project
+```text
+Orient → Plan → Implement → Verify → Handoff
 ```
 
-### `ctx checkpoint`
+1. **Orient**：调用 `ctx orient` 或 MCP `context_orient`，读取有界任务上下文。
+2. **Plan**：在广泛改动前先形成可执行计划。
+3. **Implement**：用 `ctx note add` 记录有价值的观察、决策、阻塞或行动；不要为每条记录创建 Snapshot。
+4. **Verify**：执行适用的构建和测试，并把有意义的失败记录为 Note。
+5. **Handoff**：任务阶段结束时显式运行一次 `ctx checkpoint`，记录完成项、待办、决策和风险；Hook 不会自动 checkpoint。
+
+## 常用命令
 
-保存结构化工作状态。第一次保存创建 baseline，后续有变化时保存 patch；内容没有变化时返回 `no_change`。
+业务命令默认输出格式化 JSON；帮助输出为纯文本。错误写入标准错误并返回非零退出码。`ctx --version` 输出一个 JSON 字符串。
 
 ```bash
-ctx checkpoint \
-  --context <context-id> \
-  --title "修复支付回调" \
-  --progress "已定位签名校验失败原因" \
-  --last-error "测试环境缺少回调凭据" \
-  --completed "复现问题,确认签名字段" \
-  --pending "补充回归测试" \
-  --decisions "保留原始请求体用于验签" \
-  --risks "旧版客户端字段格式不同" \
-  --files "src/payment/webhook.ts"
+ctx init
+ctx checkpoint --title "修复支付回调" --progress "已定位签名校验失败原因"
+ctx resume --max-chars 2000
+ctx orient "支付回调" --knowledge-limit 5 --deadend-limit 3
+ctx note add "测试环境缺少回调凭据" --kind problem --context <context-id>
+ctx activity --context <context-id> --open
+ctx knowledge discover "支付回调"
+ctx knowledge verify <knowledge-id>
+ctx deadend verify <deadend-id>
+ctx status
+ctx doctor
 ```
 
-列表参数使用逗号分隔。`--context` 省略时会创建新的 Context。默认情况下，实际保存之间至少间隔 10 秒；短时间内有变化的保存会返回 `rate_limited`，没有变化则返回 `no_change`。
+### `ctx checkpoint` 和 `ctx resume`
 
-### `ctx resume`
+第一次 checkpoint 创建 baseline，后续变化创建 patch。相同内容返回 `no_change`；短时间内的变化可能返回 `rate_limited`，应在完成更多阶段工作后再保存。`ctx resume` 返回轻量摘要和按需使用的完整 details，并会保留其既有的 `lastUsedAt` 更新语义。
 
-恢复一个 active 或 stable Context。默认优先选择当前分支上最近更新的 Context，并返回 Git 分支/commit 是否发生漂移。
+### `ctx note` 和 `ctx activity`
 
-```bash
-ctx resume
-ctx resume --context <context-id>
-ctx resume --path path/to/project --max-chars 4000
-```
+`ctx note add` 是开发过程中的低成本记录入口，不创建 Snapshot。阶段性 checkpoint 可通过 `--absorb-notes` 吸收当前 Context 的 open Note。`ctx activity` 提供只读的 Note 与 Snapshot 时间线，适合人类查看 Agent 的进度。
 
-### `ctx status`
+### Knowledge 与 Deadend
 
-查看项目是否已初始化以及当前 Context 索引：
+`ctx learn` 和 `ctx deadend` 默认创建 `candidate` 项。普通发现与 `ctx orient` 只使用已验证项目共识；候选项需要通过 `ctx knowledge verify` 或 `ctx deadend verify` 显式确认，或以 `--all` 审查。
 
 ```bash
-ctx status
+ctx learn "订单取消后不能再次进入支付中状态" --scope project
+ctx deadend --attempt "使用共享可变单例保存订单状态" --reason "并发测试出现跨用例状态泄漏"
+ctx knowledge discover "订单取消"
 ```
 
-### `ctx doctor`
+## MCP 集成
 
-检查 Manifest、存储目录、索引、Context 元数据、当前 Snapshot 和索引重建一致性：
+`ctx agent serve` 启动一个 MCP stdio server，暴露一个工具：`context_orient`。该 server 的标准输入和输出均属于 MCP 协议，不能在交互式终端直接使用或混入日志。
 
 ```bash
-ctx doctor
+ctx agent serve
 ```
 
-### `ctx learn`
+`context_orient` 接受可选的 `path`、`contextId`、`query`、`scope`、`maxChars`、`knowledgeLimit`、`deadendLimit` 和 `noteLimit`。它的结果与 `ctx orient` 相同：`ready` 是成功的任务定位结果，初始化但没有可恢复 Context 时返回成功的 `no_context`。输入验证或 Runtime 错误为单次工具错误，不会终止 server。
+
+## Claude Code 集成
 
-记录一条待确认的项目知识。Knowledge 默认是 `candidate`，不会进入普通的已验证知识列表。
+先查看项目是否需要安装集成：
 
 ```bash
-ctx learn "订单取消后不能再次进入支付中状态" \
-  --scope project \
-  --context <context-id> \
-  --snapshot <snapshot-id> \
-  --evidence "src/order/state-machine.ts,订单服务接口约束"
+ctx integrate claude inspect
+ctx integrate claude install
 ```
 
-查看和确认知识：
+`install` 默认只输出预览，不创建或修改文件。确认后才显式写入：
 
 ```bash
-ctx knowledge
-ctx knowledge --all
-ctx knowledge verify <knowledge-id>
+ctx integrate claude install --apply
 ```
 
-不提供 `--context` 时，知识仍可以记录为项目级候选知识；如果提供来源，则对应 Context 和 Snapshot 必须存在。
+安装会以幂等方式合并项目本地配置：
 
-### `ctx deadend`
+- `.claude/settings.json`：`SessionStart` 与 `UserPromptSubmit` Hook，分别调用 `ctx hook claude-code session-start` 和 `ctx hook claude-code user-prompt`。
+- `.mcp.json`：名为 `fluffy-context` 的 stdio MCP server，调用 `ctx agent serve`。
 
-记录一条已尝试但不可行的路径。Deadend 默认是 `candidate`，不会默认注入恢复摘要。
+安装会保留无关的 Hook、权限和 MCP server；遇到无效 JSON、无效相关结构或同名冲突配置会拒绝覆盖。Hook 仅注入有界的 Orient/Plan/Implement/Verify/Handoff 指引，输入损坏、项目未初始化或查询失败时会 fail open，不阻塞 Claude Code 任务，也不会自动创建 checkpoint。
 
-```bash
-ctx deadend \
-  --attempt "使用共享可变单例保存订单状态" \
-  --reason "并发测试出现跨用例状态泄漏" \
-  --scope project \
-  --context <context-id> \
-  --evidence "test/order-state.test.ts"
-```
+## TypeScript Agent API
 
-查看和确认死路：
+使用公开包入口，不要导入内部 `dist/...` 文件：
 
-```bash
-ctx deadends
-ctx deadends --all
-ctx deadend verify <deadend-id>
+```ts
+import { contextOrient, loadContext, saveContext, searchContext } from 'fluffy-context';
+
+const orientation = await contextOrient(process.cwd(), {
+  query: 'payment callback',
+  maxChars: 2400,
+});
 ```
 
-## `.contextignored`
+`fluffy-context/agent` 提供相同的 Agent API。公开类型声明随包发布。Runtime 的存储布局与内部模块不是兼容性承诺。
+
+## `.contextignored` 与安全边界
 
-`ctx init` 会在项目根目录创建 `.contextignored`。它用于配置不应作为上下文关联文件保存的路径，语法接近 `.gitignore`：
+`.contextignored` 语法接近 `.gitignore`，用于排除不应作为关联文件保存的项目路径：
 
 ```gitignore
-# 私有目录
 private/
-
-# 本地生成文件
 *.generated.ts
-
-# 不纳入上下文的临时记录
 notes/draft-*
 ```
 
-内置保护规则始终优先，包括 `.context/`、`.git/`、依赖目录、构建产物、环境变量文件、密钥和常见凭据文件。项目规则不能通过否定规则覆盖这些保护。
-
-## 存储与安全边界
-
-- Snapshot 按 baseline/patch 保存，不会每次复制整个项目文件树。
-- `index.json` 是可重建索引，不是唯一业务数据来源。
-- Context、Knowledge、Deadend 使用独立文件保存。
-- 写入使用临时文件替换，并通过项目级锁避免并发覆盖。
-- 默认只恢复摘要字段；完整结构化内容位于 `details` 中按需读取。
-- CLI 不会读取或保存被内置保护规则排除的文件内容。
-
-## 命令输出
+内置保护规则优先，不能被否定规则绕过：`.context/`、`.git/`、依赖和构建目录、`.env` 文件、密钥、常见 credential/token 文件、绝对路径和 `..` 越界路径都不会被作为 Context 关联文件保存。
 
-CLI 默认向标准输出写入格式化 JSON，适合被脚本、Agent 或 IDE 集成：
-
-```bash
-ctx --help
-ctx --version
-```
-
-错误信息写入标准错误，并以非零退出码结束。
-
-## 开发
-
-安装依赖并运行测试：
+## 开发与发布验证
 
 ```bash
 npm install
-npm test
-```
-
-只构建 TypeScript：
-
-```bash
 npm run build
+npm test
+npm run pack:check
+npm pack --dry-run --json
 ```
 
-本项目核心运行时只依赖 Node.js 内置模块，当前没有运行时第三方依赖。
+运行时依赖 `@modelcontextprotocol/server` 与 `zod` 以提供 MCP 适配；核心 Context 存储仍然保持本地优先。`prepack` 会重新构建发布产物，`prepublishOnly` 在未来手动发布前运行测试；这些命令不会发布 npm 包。
 
 ## 当前范围
 
-当前版本聚焦本地单项目的可靠闭环：
-
-```text
-init → checkpoint → resume
-```
+0.3.0 聚焦单项目、本地优先的可靠闭环和 Agent 采用路径：有界 Orient、显式 checkpoint、确定性 Knowledge/Deadend discovery、MCP `context_orient` 与可选的 Claude Code Hook 集成。
 
-并提供基础的 Knowledge、Deadend、忽略规则、诊断、Snapshot 增量保存、摘要预算和保存限流能力。远程同步、多人协作、复杂语义检索、自动模型总结和 Context merge 不属于当前版本的已实现能力。
+远程同步、多人协作、复杂语义检索、自动模型总结、自动 checkpoint、Context merge，以及更多状态变更型 MCP 工具不属于当前版本范围。

package/dist/src/agent/api.d.ts

@@ -0,0 +1,8 @@
+import type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, CheckpointInput, ContextSearchOptions, ContextSearchResult } from '../runtime/types.js';
+import type { ContextOrientOptions, ContextOrientResult } from './types.js';
+export declare function saveContext(startPath: string | undefined, input: CheckpointInput, options?: {
+    minSaveIntervalMs?: number;
+}): Promise<AgentSaveResult>;
+export declare function loadContext(startPath: string | undefined, options?: AgentLoadOptions): Promise<AgentLoadResult>;
+export declare function contextOrient(startPath: string | undefined, options?: ContextOrientOptions): Promise<ContextOrientResult>;
+export declare function searchContext(startPath: string | undefined, query: string, options?: ContextSearchOptions): Promise<ContextSearchResult>;

package/dist/src/agent/api.js

@@ -0,0 +1,285 @@
+import { readdir } from 'node:fs/promises';
+import { resolveProjectRoot } from '../project/project-resolver.js';
+import { contextsRoot, contextMetadataPath } from '../storage/layout.js';
+import { isRecord, readJson } from '../storage/json-store.js';
+import { checkpoint, rebuildSnapshot, resume } from '../runtime/runtime.js';
+import { discoverDeadends, discoverKnowledge, listDeadends } from '../runtime/knowledge.js';
+import { listNotes } from '../runtime/notes.js';
+function normalized(value) {
+    return value.trim().toLocaleLowerCase();
+}
+function terms(query) {
+    return [...new Set(normalized(query).split(/\s+/).filter(Boolean))];
+}
+function limited(value, budget) {
+    if (budget.remaining <= 0)
+        return '';
+    const result = value.length <= budget.remaining ? value : `${value.slice(0, Math.max(0, budget.remaining - 1))}…`;
+    budget.remaining -= result.length;
+    return result;
+}
+function limitedList(values, budget) {
+    return values.flatMap((value) => {
+        if (budget.remaining <= 0)
+            return [];
+        const result = limited(value, budget);
+        return result ? [result] : [];
+    });
+}
+function textLength(value) {
+    return Array.isArray(value) ? value.reduce((total, item) => total + item.length, 0) : value?.length ?? 0;
+}
+function emptyKnowledge(query) {
+    return { query, total: 0, truncated: false, hits: [], duplicateIds: [], possibleConflicts: [] };
+}
+function emptyDeadends(query) {
+    return { query, total: 0, truncated: false, hits: [] };
+}
+function limitKnowledge(result, budget) {
+    let truncated = false;
+    const hits = [];
+    for (const hit of result.hits) {
+        if (budget.remaining <= 0) {
+            truncated = true;
+            break;
+        }
+        const statement = limited(hit.knowledge.statement, budget);
+        const supportingEvidence = limitedList(hit.knowledge.supportingEvidence, budget);
+        if (statement.length < hit.knowledge.statement.length || supportingEvidence.length < hit.knowledge.supportingEvidence.length)
+            truncated = true;
+        hits.push({ ...hit, knowledge: { ...hit.knowledge, statement, supportingEvidence } });
+    }
+    if (hits.length < result.hits.length)
+        truncated = true;
+    return { result: { ...result, hits, truncated: result.truncated || truncated }, truncated };
+}
+function limitDeadends(result, budget) {
+    let truncated = false;
+    const hits = [];
+    for (const hit of result.hits) {
+        if (budget.remaining <= 0) {
+            truncated = true;
+            break;
+        }
+        const attempt = limited(hit.deadend.attempt, budget);
+        const reason = limited(hit.deadend.reason, budget);
+        const observedEvidence = limitedList(hit.deadend.observedEvidence, budget);
+        if (attempt.length < hit.deadend.attempt.length || reason.length < hit.deadend.reason.length || observedEvidence.length < hit.deadend.observedEvidence.length)
+            truncated = true;
+        hits.push({ ...hit, deadend: { ...hit.deadend, attempt, reason, observedEvidence } });
+    }
+    if (hits.length < result.hits.length)
+        truncated = true;
+    return { result: { ...result, hits, truncated: result.truncated || truncated }, truncated };
+}
+function limitNotes(notes, budget) {
+    const result = [];
+    for (const note of notes) {
+        if (budget.remaining <= 0)
+            return { notes: result, truncated: true };
+        const message = limited(note.message, budget);
+        result.push({ ...note, message });
+        if (message.length < note.message.length)
+            return { notes: result, truncated: true };
+    }
+    return { notes: result, truncated: false };
+}
+function summary(content, maxChars, branchOrCommitDrift = false) {
+    const budget = { remaining: Math.max(0, maxChars) };
+    return {
+        progressSummary: limited(content.progressSummary, budget),
+        lastError: content.lastError === null ? null : limited(content.lastError, budget),
+        completed: limitedList(content.completed, budget),
+        pendingTasks: limitedList(content.pendingTasks, budget),
+        decisions: limitedList(content.decisions, budget),
+        risks: limitedList(content.risks, budget),
+        relatedFiles: limitedList(content.relatedFiles, budget),
+        branchOrCommitDrift,
+    };
+}
+function isContextMetadata(value) {
+    return isRecord(value)
+        && value.schemaVersion === 1
+        && typeof value.id === 'string'
+        && typeof value.title === 'string'
+        && typeof value.projectRoot === 'string'
+        && (typeof value.currentSnapshotId === 'string' || value.currentSnapshotId === null)
+        && ['draft', 'active', 'stable', 'archived', 'deleted'].includes(value.status);
+}
+function matchedContext(context, content, queryTerms) {
+    const values = {
+        title: context.title,
+        progressSummary: content.progressSummary,
+        lastError: content.lastError ?? '',
+        completed: content.completed.join(' '),
+        pendingTasks: content.pendingTasks.join(' '),
+        decisions: content.decisions.join(' '),
+        risks: content.risks.join(' '),
+        relatedFiles: content.relatedFiles.join(' '),
+    };
+    const matchedFields = new Set();
+    const matchedTerms = new Set();
+    let score = 0;
+    for (const term of queryTerms) {
+        for (const [field, value] of Object.entries(values)) {
+            if (normalized(value).includes(term)) {
+                matchedFields.add(field);
+                matchedTerms.add(term);
+                score += field === 'title' ? 5 : 3;
+            }
+        }
+    }
+    return { matchedFields: [...matchedFields], matchedTerms: [...matchedTerms], score };
+}
+export async function saveContext(startPath, input, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    return { projectRoot, result: await checkpoint(projectRoot, input, options) };
+}
+export async function loadContext(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const result = await resume(projectRoot, options.contextId, options.maxChars ?? 4000);
+    const knowledge = options.query === undefined ? null : await discoverKnowledge(projectRoot, options.query, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    const verifiedDeadends = await listDeadends(projectRoot);
+    return {
+        projectRoot,
+        context: result.context,
+        snapshot: result.snapshot,
+        resumeSummary: result.resumeSummary,
+        ...(options.includeDetails ? { details: result.details } : {}),
+        knowledge,
+        verifiedDeadendIds: verifiedDeadends.map((item) => item.deadendId),
+    };
+}
+export async function contextOrient(startPath, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const query = options.query === undefined ? null : options.query.trim();
+    if (query === '')
+        throw new Error('context orient query must not be empty');
+    let loaded;
+    try {
+        loaded = await resume(projectRoot, options.contextId, options.maxChars ?? 4000, { touchLastUsedAt: false });
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'no active context found') {
+            return {
+                status: 'no_context',
+                projectRoot,
+                query,
+                context: null,
+                snapshot: null,
+                resumeSummary: null,
+                knowledge: emptyKnowledge(query ?? ''),
+                deadends: emptyDeadends(query ?? ''),
+                notes: [],
+                truncated: false,
+            };
+        }
+        throw error;
+    }
+    const notes = await listNotes(projectRoot, {
+        contextId: loaded.context.id,
+        openOnly: true,
+        limit: options.noteLimit ?? 20,
+        maxChars: options.maxChars ?? 4000,
+    });
+    const knowledge = query === null
+        ? emptyKnowledge('')
+        : await discoverKnowledge(projectRoot, query, {
+            scope: options.scope,
+            limit: options.knowledgeLimit ?? 10,
+            maxChars: options.maxChars ?? 4000,
+        });
+    const deadends = query === null
+        ? emptyDeadends('')
+        : await discoverDeadends(projectRoot, query, {
+            scope: options.scope,
+            limit: options.deadendLimit ?? 10,
+            maxChars: options.maxChars ?? 4000,
+        });
+    const budget = { remaining: Math.max(0, options.maxChars ?? 4000) };
+    const resumeSummary = {
+        progressSummary: limited(loaded.resumeSummary.progressSummary, budget),
+        lastError: loaded.resumeSummary.lastError === null ? null : limited(loaded.resumeSummary.lastError, budget),
+        completed: limitedList(loaded.resumeSummary.completed, budget),
+        pendingTasks: limitedList(loaded.resumeSummary.pendingTasks, budget),
+        decisions: limitedList(loaded.resumeSummary.decisions, budget),
+        risks: limitedList(loaded.resumeSummary.risks, budget),
+        relatedFiles: limitedList(loaded.resumeSummary.relatedFiles, budget),
+        branchOrCommitDrift: loaded.resumeSummary.branchOrCommitDrift,
+    };
+    const resumeTruncated = textLength(resumeSummary.progressSummary) < textLength(loaded.resumeSummary.progressSummary)
+        || textLength(resumeSummary.lastError) < textLength(loaded.resumeSummary.lastError)
+        || textLength(resumeSummary.completed) < textLength(loaded.resumeSummary.completed)
+        || textLength(resumeSummary.pendingTasks) < textLength(loaded.resumeSummary.pendingTasks)
+        || textLength(resumeSummary.decisions) < textLength(loaded.resumeSummary.decisions)
+        || textLength(resumeSummary.risks) < textLength(loaded.resumeSummary.risks)
+        || textLength(resumeSummary.relatedFiles) < textLength(loaded.resumeSummary.relatedFiles);
+    const limitedKnowledgeResult = limitKnowledge(knowledge, budget);
+    const limitedDeadendResult = limitDeadends(deadends, budget);
+    const limitedNotesResult = limitNotes(notes, budget);
+    return {
+        status: 'ready',
+        projectRoot,
+        query,
+        context: {
+            id: loaded.context.id,
+            title: loaded.context.title,
+            status: loaded.context.status,
+            branch: loaded.context.branch,
+            commit: loaded.context.commit,
+            updatedAt: loaded.context.updatedAt,
+        },
+        snapshot: {
+            snapshotId: loaded.snapshot.snapshotId,
+            mode: loaded.snapshot.mode,
+            createdAt: loaded.snapshot.createdAt,
+            branch: loaded.snapshot.branch,
+            commit: loaded.snapshot.commit,
+        },
+        resumeSummary,
+        knowledge: limitedKnowledgeResult.result,
+        deadends: limitedDeadendResult.result,
+        notes: limitedNotesResult.notes,
+        truncated: resumeTruncated || limitedKnowledgeResult.truncated || limitedDeadendResult.truncated || limitedNotesResult.truncated,
+    };
+}
+export async function searchContext(startPath, query, options = {}) {
+    const projectRoot = await resolveProjectRoot(startPath);
+    const cleanQuery = query.trim();
+    if (!cleanQuery)
+        throw new Error('context search query must not be empty');
+    const queryTerms = terms(cleanQuery);
+    const contextIds = options.contextId ? [options.contextId] : await readdir(contextsRoot(projectRoot));
+    const matches = [];
+    for (const contextId of contextIds) {
+        const context = await readJson(contextMetadataPath(projectRoot, contextId), isContextMetadata);
+        if (!['active', 'stable'].includes(context.status) || !context.currentSnapshotId)
+            continue;
+        const content = await rebuildSnapshot(projectRoot, context.id, context.currentSnapshotId);
+        const match = matchedContext(context, content, queryTerms);
+        if (match.matchedTerms.length === 0)
+            continue;
+        matches.push({
+            context,
+            snapshotId: context.currentSnapshotId,
+            score: match.score,
+            matchedTerms: match.matchedTerms,
+            matchedFields: match.matchedFields,
+            summary: summary(content, options.maxChars ?? 4000),
+        });
+    }
+    matches.sort((left, right) => right.score - left.score || right.context.updatedAt.localeCompare(left.context.updatedAt) || left.context.id.localeCompare(right.context.id));
+    const limit = options.limit ?? 10;
+    const selected = matches.slice(0, limit);
+    const knowledge = await discoverKnowledge(projectRoot, cleanQuery, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    const deadends = await discoverDeadends(projectRoot, cleanQuery, { scope: options.scope, maxChars: options.maxChars ?? 4000 });
+    return {
+        projectRoot,
+        query: cleanQuery,
+        total: matches.length,
+        truncated: matches.length > selected.length,
+        hits: selected,
+        knowledge,
+        verifiedDeadendIds: deadends.hits.map((hit) => hit.deadend.deadendId),
+    };
+}

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

@@ -0,0 +1,3 @@
+export * from './api.js';
+export type { ContextOrientContext, ContextOrientNoContextResult, ContextOrientOptions, ContextOrientReadyResult, ContextOrientResult, ContextOrientSnapshot, } from './types.js';
+export type { AgentLoadOptions, AgentLoadResult, AgentSaveResult, ContextSearchHit, ContextSearchOptions, ContextSearchResult, } from '../runtime/types.js';

package/dist/src/agent/index.js

@@ -0,0 +1 @@
+export * from './api.js';