fluffy-context 0.2.0 → 0.3.1

package/README.md

@@ -1,31 +1,30 @@
 # Context Runtime
 
-Context Runtime 是一个面向 AI 编程会话的本地上下文运行时 CLI。0.2.0 在可靠 Context 闭环之上增加了无模型、确定性的 Agent API 和 Knowledge Discovery，让 Agent 可以先发现已验证的项目共识，再保存和恢复工作状态，而不是每次重新阅读大量项目内容。
+`fluffy-context` 是面向 AI 编程会话的本地 Context Runtime CLI。0.3.1 提供可重复、安全调用的任务定位入口、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,27 +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 后创建
-└── notes.json        # 首次使用 note add 后创建
-.contextignored
-```
-
-保存一次工作状态：
+这会创建本地 `.context/` 存储和 `.contextignored` 规则文件。保存阶段性工作：
 
 ```bash
 ctx checkpoint \
@@ -63,231 +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
 ```
 
-Agent 集成可以直接调用 `dist/src/agent/api.js` 中的 `saveContext`、`loadContext` 和 `searchContext`，不需要读取 `.context` 文件。推荐工作流是：先 `loadContext` 或 `ctx resume`，再用 `ctx knowledge discover` 或 `searchContext` 查找已验证共识，开发过程中记录 Note，阶段完成后 checkpoint，最后用 `learn` 和 `verify` 沉淀经过确认的知识。`loadContext` 默认不返回完整 details；候选 Knowledge、未验证 Deadend、模型推理、向量检索和远端服务不属于 0.2.0 默认能力。
+## Agent 工作流
 
-查看版本：
+推荐阶段：
 
-```bash
-ctx --version
-```
-
-## 常用命令
-
-所有一级命令都支持独立帮助，帮助输出为面向终端和 Agent 的纯文本，不会读取或修改项目状态：
-
-```bash
-ctx init --help
-ctx checkpoint --help
-ctx resume --help
-ctx knowledge verify --help
-ctx deadend verify --help
+```text
+Orient → Plan → Implement → Verify → Handoff
 ```
 
-业务命令仍然默认输出 JSON；未知选项、缺少选项值和无效位置参数会以非零退出码报告。
+1. **Orient**：调用 `ctx orient` 或 MCP `context_orient`，读取有界任务上下文。
+2. **Plan**：在广泛改动前先形成可执行计划。
+3. **Implement**：用 `ctx note add` 记录有价值的观察、决策、阻塞或行动；不要为每条记录创建 Snapshot。
+4. **Verify**：执行适用的构建和测试，并把有意义的失败记录为 Note。
+5. **Handoff**：任务阶段结束时显式运行一次 `ctx checkpoint`，记录完成项、待办、决策和风险；Hook 不会自动 checkpoint。
 
-### `ctx init`
+## 常用命令
 
-初始化项目的 Context Runtime 存储布局。重复执行是幂等的，不会覆盖已有 Context 或项目忽略规则。
+业务命令默认输出格式化 JSON；帮助输出为纯文本。错误写入标准错误并返回非零退出码。`ctx --version` 输出一个 JSON 字符串。
 
 ```bash
 ctx init
-ctx init path/to/project
-ctx init --path path/to/project
+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
 ```
 
-### `ctx checkpoint`
+### `ctx checkpoint` 和 `ctx resume`
 
-保存结构化工作状态。第一次保存创建 baseline，后续有变化时保存 patch；内容没有变化时返回 `no_change`。
-
-```bash
-ctx checkpoint \
-  --context <context-id> \
-  --title "修复支付回调" \
-  --progress "已定位签名校验失败原因" \
-  --last-error "测试环境缺少回调凭据" \
-  --completed "复现问题,确认签名字段" \
-  --pending "补充回归测试" \
-  --decisions "保留原始请求体用于验签" \
-  --risks "旧版客户端字段格式不同" \
-  --files "src/payment/webhook.ts"
-```
+第一次 checkpoint 创建 baseline，后续变化创建 patch。相同内容返回 `no_change`；短时间内的变化可能返回 `rate_limited`，应在完成更多阶段工作后再保存。`ctx resume` 返回轻量摘要和按需使用的完整 details，并会保留其既有的 `lastUsedAt` 更新语义。
 
-列表参数使用逗号分隔。`--context` 省略时会创建新的 Context。默认情况下，实际保存之间至少间隔 10 秒；短时间内有变化的保存会返回 `rate_limited`，没有变化则返回 `no_change`。使用 `--absorb-notes` 时，只有真正保存了新 Snapshot 才会将当前 Context 下尚未吸收的 Note 标记为已吸收；`no_change` 和 `rate_limited` 不会改变 Note。
+### `ctx note` 和 `ctx activity`
 
-Checkpoint 会在写入前规范化新值：文本首尾空白会被移除，空白 `lastError` 会变成 `null`，列表中的空项会被移除。未提供字段会沿用已有值；显式传入空字符串或空列表会清除对应值。历史 Snapshot 不会被自动改写；`ctx doctor` 只负责报告历史数据损坏。
+`ctx note add` 是开发过程中的低成本记录入口，不创建 Snapshot。阶段性 checkpoint 可通过 `--absorb-notes` 吸收当前 Context 的 open Note。`ctx activity` 提供只读的 Note 与 Snapshot 时间线，适合人类查看 Agent 的进度。
 
-### `ctx resume`
+### Knowledge 与 Deadend
 
-恢复一个 active 或 stable Context。默认优先选择当前分支上最近更新的 Context，并返回 Git 分支/commit 是否发生漂移。
+`ctx learn` 和 `ctx deadend` 默认创建 `candidate` 项。普通发现与 `ctx orient` 只使用已验证项目共识；候选项需要通过 `ctx knowledge verify` 或 `ctx deadend verify` 显式确认，或以 `--all` 审查。
 
 ```bash
-ctx resume
-ctx resume --context <context-id>
-ctx resume --path path/to/project --max-chars 4000
+ctx learn "订单取消后不能再次进入支付中状态" --scope project
+ctx deadend --attempt "使用共享可变单例保存订单状态" --reason "并发测试出现跨用例状态泄漏"
+ctx knowledge discover "订单取消"
 ```
 
-### `ctx status`
+## MCP 集成
 
-查看项目是否已初始化以及当前 Context 索引：
+`ctx agent serve` 启动一个 MCP stdio server，暴露一个工具：`context_orient`。该 server 的标准输入和输出均属于 MCP 协议，不能在交互式终端直接使用或混入日志。
 
 ```bash
-ctx status
+ctx agent serve
 ```
 
-### `ctx doctor`
-
-检查 Manifest、存储目录、索引、Context 元数据、当前 Snapshot 和索引重建一致性：
-
-```bash
-ctx doctor
-```
+`context_orient` 接受可选的 `path`、`contextId`、`query`、`scope`、`maxChars`、`knowledgeLimit`、`deadendLimit` 和 `noteLimit`。它的结果与 `ctx orient` 相同：`ready` 是成功的任务定位结果，初始化但没有可恢复 Context 时返回成功的 `no_context`。输入验证或 Runtime 错误为单次工具错误，不会终止 server。
 
-### `ctx learn`
+## 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 discover "投保人认证"
-ctx knowledge discover "identity verification" --scope project --limit 10 --max-chars 4000
-ctx knowledge verify <knowledge-id>
+ctx integrate claude install --apply
 ```
 
-`discover` 默认只匹配已验证 Knowledge，返回命中的字段、匹配原因、来源 Context/Snapshot 和 supporting evidence。候选项不会参与普通发现；需要审查候选或其它状态时使用 `--all` 或 `--status candidate,verified`。匹配采用确定性的规范化文本和业务别名规则，不依赖模型或向量数据库。
-
-不提供 `--context` 时，知识仍可以记录为项目级候选知识；如果提供来源，则对应 Context 和 Snapshot 必须存在。
+安装会以幂等方式合并项目本地配置：
 
-### `ctx note`
+- `.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`。
 
-`ctx note` 是 Agent 在开发过程中记录短期问题、观察、行动和决策的低成本入口。它不会创建 Context Snapshot，记录会以追加方式保留，后续可由 checkpoint 显式吸收。
+安装会保留无关的 Hook、权限和 MCP server；遇到无效 JSON、无效相关结构或同名冲突配置会拒绝覆盖。Hook 仅注入有界的 Orient/Plan/Implement/Verify/Handoff 指引，输入损坏、项目未初始化或查询失败时会 fail open，不阻塞 Claude Code 任务，也不会自动创建 checkpoint。
 
-```bash
-ctx note add "第三方人脸识别测试凭据缺失" \
-  --kind problem \
-  --context <context-id>
-ctx note add "保留原始请求体后验签恢复" \
-  --kind decision \
-  --status resolved \
-  --context <context-id>
-ctx note list --context <context-id> --open
-```
+## TypeScript Agent API
 
-### `ctx activity`
+使用公开包入口，不要导入内部 `dist/...` 文件：
 
-`ctx activity` 面向人类查看 Agent 的开发活动，返回 Note 和已保存 Snapshot 的时间线。它是只读查询，不会创建额外事件日志。
+```ts
+import { contextOrient, loadContext, saveContext, searchContext } from 'fluffy-context';
 
-```bash
-ctx activity --context <context-id> --since 2026-08-21T00:00:00.000Z
-ctx activity --open --limit 20
+const orientation = await contextOrient(process.cwd(), {
+  query: 'payment callback',
+  maxChars: 2400,
+});
 ```
 
-### `ctx deadend`
+`fluffy-context/agent` 提供相同的 Agent API。公开类型声明随包发布。Runtime 的存储布局与内部模块不是兼容性承诺。
 
-记录一条已尝试但不可行的路径。Deadend 默认是 `candidate`，不会默认注入恢复摘要。
+## `.contextignored` 与安全边界
 
-```bash
-ctx deadend \
-  --attempt "使用共享可变单例保存订单状态" \
-  --reason "并发测试出现跨用例状态泄漏" \
-  --scope project \
-  --context <context-id> \
-  --evidence "test/order-state.test.ts"
-```
-
-查看和确认死路：
-
-```bash
-ctx deadends
-ctx deadends --all
-ctx deadend verify <deadend-id>
-```
-
-## `.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.1 聚焦单项目、本地优先的可靠闭环和 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

@@ -4,6 +4,7 @@ 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();
 }
@@ -25,6 +26,64 @@ function limitedList(values, 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 {
@@ -91,6 +150,99 @@ export async function loadContext(startPath, options = {}) {
         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();

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/types.d.ts

@@ -0,0 +1,50 @@
+import type { ContextStatus, DeadendDiscoveryResult, KnowledgeDiscoveryResult, Note, ResumeSummary, SnapshotMode } from '../runtime/types.js';
+export interface ContextOrientOptions {
+    contextId?: string;
+    query?: string;
+    scope?: string;
+    maxChars?: number;
+    knowledgeLimit?: number;
+    deadendLimit?: number;
+    noteLimit?: number;
+}
+export interface ContextOrientContext {
+    id: string;
+    title: string;
+    status: ContextStatus;
+    branch: string | null;
+    commit: string | null;
+    updatedAt: string;
+}
+export interface ContextOrientSnapshot {
+    snapshotId: string;
+    mode: SnapshotMode;
+    createdAt: string;
+    branch: string | null;
+    commit: string | null;
+}
+export interface ContextOrientReadyResult {
+    status: 'ready';
+    projectRoot: string;
+    query: string | null;
+    context: ContextOrientContext;
+    snapshot: ContextOrientSnapshot;
+    resumeSummary: ResumeSummary;
+    knowledge: KnowledgeDiscoveryResult;
+    deadends: DeadendDiscoveryResult;
+    notes: Note[];
+    truncated: boolean;
+}
+export interface ContextOrientNoContextResult {
+    status: 'no_context';
+    projectRoot: string;
+    query: string | null;
+    context: null;
+    snapshot: null;
+    resumeSummary: null;
+    knowledge: KnowledgeDiscoveryResult;
+    deadends: DeadendDiscoveryResult;
+    notes: Note[];
+    truncated: false;
+}
+export type ContextOrientResult = ContextOrientReadyResult | ContextOrientNoContextResult;

package/dist/src/agent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/capture/context-filter.d.ts

@@ -0,0 +1,7 @@
+interface Rule {
+    pattern: string;
+    negated: boolean;
+}
+export declare function readProjectRules(projectRoot: string): Promise<Rule[]>;
+export declare function filterPaths(projectRoot: string, paths: string[]): Promise<string[]>;
+export {};

package/dist/src/cli/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};