dsh-continual-evolve 0.14.1 → 0.15.0

package/lib/extraction-prompt.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The extraction prompt: what deserves a memory, how each type reads, and
+ * the closed proposal format the model must answer in.
+ *
+ * The taxonomy moved here verbatim-in-spirit from the main-session guide
+ * (the 4a1e57d version) when the store became a gated database: the
+ * extraction model is the only writer left that needs the write-quality
+ * rules, so teaching them in the main session would be spent tokens twice.
+ * The model proposes; the store's gates (constraints, secret screen, dedup,
+ * feedback contract) decide — the proposal is never trusted on its own.
+ */
+/** The extraction model's system prompt (Chinese — memory content is Chinese-first). */
+export declare const EXTRACTION_SYSTEM_PROMPT = "\u4F60\u662F\u8BB0\u5FC6\u63D0\u53D6\u4E13\u5458\u3002\u4F60\u7684\u552F\u4E00\u4EFB\u52A1\uFF1A\u4ECE\u4F1A\u8BDD\u8F68\u8FF9\u589E\u91CF\u91CC\u5224\u65AD\u54EA\u4E9B\u4FE1\u606F\u503C\u5F97\u5B58\u5165\u7528\u6237\u7684\u8DE8\u4F1A\u8BDD\u6301\u4E45\u8BB0\u5FC6\uFF0C\u5E76\u63D0\u51FA\u7ED3\u6784\u5316\u63D0\u6848\u3002\u4F60\u4E0D\u6267\u884C\u4EFB\u52A1\u3001\u4E0D\u56DE\u7B54\u7528\u6237\u3001\u4E0D\u89E3\u91CA\u63A8\u7406\u3002\n\n## \u4F55\u65F6\u5199\u5165\u8BB0\u5FC6\n\n<type name=\"user\">\n  <when_to_save>\u5F97\u77E5\u7528\u6237\u7684\u753B\u50CF\u4E0E\u73AF\u5883\u4E8B\u5B9E\uFF1A\u89D2\u8272\u3001\u6280\u672F\u6808\u3001\u7ECF\u9A8C\u6C34\u5E73\u3001\u504F\u597D\uFF0C\u4EE5\u53CA\u673A\u5668\u4E0E\u5DE5\u5177\u94FE\uFF08\u64CD\u4F5C\u7CFB\u7EDF\u3001\u88C5\u4E86\u4EC0\u4E48\u3001\u914D\u7F6E\u5728\u54EA\uFF09\u3002\u4F8B\uFF1A\"\u6211\u5728 Fedora \u4E0A\u5DE5\u4F5C\uFF0C\u65E5\u5E38\u8DD1 dotnet-desktop profile\"\u3002</when_to_save>\n</type>\n\n<type name=\"feedback\">\n  <when_to_save>\u4E24\u7C7B\u4FE1\u53F7\uFF1A\n  \uFF081\uFF09\u7EA0\u6B63\u2014\u2014\u7528\u6237\u8BF4\"\u4E0D\u662F\u8FD9\u6837\"\"\u522B\"\"\u505C\u4E0B\"\u7684\u90A3\u4E00\u8F6E\uFF0C\u5B58\u88AB\u7EA0\u6B63\u7684\u505A\u6CD5\u4E0E\u6B63\u786E\u505A\u6CD5\uFF1B\n  \uFF082\uFF09\u786E\u8BA4\u2014\u2014\u66F4\u5B89\u9759\u4F46\u540C\u6837\u8981\u7D27\uFF1A\u7528\u6237\u63A5\u53D7\u4E86\u4F60\u4E0D\u5BFB\u5E38\u7684\u9009\u62E9\u800C\u65E0\u5F02\u8BAE\uFF0C\u6216\u660E\u786E\u8BF4\"\u5BF9\uFF0C\u5C31\u8FD9\u6837\"\u3002\u53EA\u5B58\u7EA0\u9519\u4F1A\u8BA9\u884C\u4E3A\u8D8A\u6765\u8D8A\u4FDD\u5B88\u3002\n  \u4F8B\uFF1A\"\u6D4B\u8BD5\u522B mock \u6570\u636E\u5E93\uFF0C\u4E0A\u6B21 mock \u8FC7\u4E86\u7EBF\u4E0A\u8FC1\u79FB\u6302\u4E86\"\u2014\u2014\u5B58\u89C4\u5219\u5E76\u5E26\u4E0A\u4E8B\u6545\u539F\u56E0\u3002</when_to_save>\n  <body_structure>\u89C4\u5219\u5148\u884C\uFF0C\u968F\u540E\u5FC5\u5E26\u4E24\u884C\uFF1A**Why:**\uFF08\u7528\u6237\u7ED9\u7684\u7406\u7531\u2014\u2014\u77E5\u9053\u4E3A\u4EC0\u4E48\u624D\u80FD\u5224\u65AD\u8FB9\u7F18\u60C5\u51B5\uFF09\u548C **How to apply:**\uFF08\u4F55\u65F6\u4F55\u5730\u751F\u6548\uFF09\u3002\u7F3A\u8FD9\u4E24\u884C\u7684\u63D0\u6848\u4F1A\u88AB\u673A\u68B0\u62D2\u7EDD\u3002</body_structure>\n</type>\n\n<type name=\"reference\">\n  <when_to_save>\u7528\u6237\u63D0\u5230\u672A\u6765\u4F1A\u7528\u5230\u7684\u8D44\u6E90\u6307\u9488\uFF1AURL\u3001\u4EEA\u8868\u76D8\u3001\u5DE5\u5355\u3001\u672C\u5730\u6570\u636E\u5E93\u3001\u6587\u6863\u4F4D\u7F6E\u3002</when_to_save>\n</type>\n\n**\u8FB9\u754C\u5224\u636E\uFF1A\u6362\u4E00\u4E2A\u4ED3\u5E93\u8FD8\u6709\u7528\u7684\u4FE1\u606F\u624D\u8FDB\u8BB0\u5FC6\u3002**\u51B3\u7B56\u3001\u67B6\u6784\u53D6\u820D\u3001\u8FDB\u884C\u4E2D\u72B6\u6001\u53EA\u5BF9\u5F53\u524D\u4ED3\u5E93\u6709\u4EF7\u503C\u2014\u2014\u5B83\u4EEC\u8D70\u4ED3\u5E93\u7684 ADR/\u6587\u6863\u8DEF\u7EBF\uFF0C\u7EDD\u4E0D\u63D0\u6848\u3002\u80FD\u4ECE\u4EE3\u7801\u3001git \u5386\u53F2\u3001\u4ED3\u5E93\u6587\u4EF6\u91CC\u91CD\u65B0\u63A8\u5BFC\u51FA\u6765\u7684\u4E8B\u5B9E\u4E0D\u5B58\uFF1B\u4E34\u65F6\u4EFB\u52A1\u72B6\u6001\u3001\u4E00\u6B21\u6027\u8C03\u8BD5\u8FC7\u7A0B\u3001\u65E0\u590D\u73B0\u8BC1\u636E\u7684\u95EE\u9898\u4FEE\u590D\u4E0D\u5B58\u3002\u76F8\u5BF9\u65E5\u671F\u4E00\u5F8B\u8F6C\u6210\u7EDD\u5BF9\u65E5\u671F\uFF08\"\u5468\u56DB\"\u2192\"2026-10-08\"\uFF09\u3002\n\n## \u66F4\u65B0\u4F18\u5148\u4E8E\u65B0\u5EFA\n\n\u5DF2\u6709\u8BB0\u5FC6\u7684\u72B6\u6001\u53D8\u4E86\uFF0C\u63D0\u6848 update \u6539\u539F\u6761\u76EE\uFF1B\u65B0\u65E7\u5E76\u5B58\u6BD4\u6CA1\u6709\u8BB0\u5FC6\u66F4\u7CDF\u3002\u8981\u66F4\u65B0\u6216\u5220\u9664\u7684\u6761\u76EE\u4F1A\u8FDE\u540C\u5168\u6587\u7ED9\u4F60\uFF0C\u63D0\u6848\u91CC\u5199\u5B83\u7684 id\u3002\u6CA1\u6709\u503C\u5F97\u6C89\u6DC0\u7684\u4E1C\u897F\u5C31\u660E\u786E\u8BF4 skip\u2014\u2014\u5B81\u7F3A\u52FF\u6EE5\u3002\n\n## \u8F93\u51FA\u683C\u5F0F\n\n\u53EA\u8F93\u51FA\u4E00\u4E2A JSON \u5BF9\u8C61\uFF0C\u4E0D\u8981\u4EE3\u7801\u56F4\u680F\u3001\u4E0D\u8981\u89E3\u91CA\uFF1A\n\n{\"decision\":\"apply\"|\"skip\",\"reason\":\"<\u4E00\u53E5\u8BDD\u4F9D\u636E>\",\"proposals\":[{\"action\":\"create\"|\"update\"|\"delete\",\"id\":\"<kebab-slug\uFF0Cupdate/delete \u5FC5\u586B>\",\"type\":\"user\"|\"feedback\"|\"reference\",\"title\":\"<\u77ED\u6807\u9898>\",\"description\":\"<\u4E00\u53E5\u8BDD\u76F8\u5173\u6027\u94A9\u5B50>\",\"body\":\"<\u6B63\u6587>\",\"sourceSeqs\":\"<\u7528\u6237\u539F\u8BDD\u6240\u5728 seq\uFF0C\u5982 820-831\uFF0C\u53EF\u7701\u7565>\"}]}";
+/** The existing-memory manifest line shown to the model. */
+export declare function manifestLineOf(record: {
+    id: string;
+    type: string;
+    title: string;
+    description: string;
+}): string;
+/** The user-prompt block for one extraction run. */
+export declare function extractionPrompt(input: {
+    increment: string;
+    manifest: string[];
+    candidates: string[];
+    userSeqs: readonly number[];
+}): string;
+/** The parsed model answer before store gating. */
+export interface RawProposal {
+    action: "create" | "update" | "delete";
+    id?: string | undefined;
+    type?: string | undefined;
+    title?: string | undefined;
+    description?: string | undefined;
+    body?: string | undefined;
+    sourceSeqs?: string | undefined;
+}
+export interface ParsedAnswer {
+    decision: "apply" | "skip" | "error";
+    reason: string;
+    proposals: RawProposal[];
+}
+/** Proposals per run cap — bounds the damage a bad model answer can do. */
+export declare const MAX_PROPOSALS_PER_RUN = 8;
+/**
+ * Parse the model's JSON answer. Tolerates code fences; rejects anything
+ * that is not the agreed shape. A genuine "skip" is a model decision the
+ * caller may act on (consume the increment); "error" marks an unparseable
+ * or shape-violating answer, which must never land as a silent success.
+ */
+export declare function parseExtractionAnswer(text: string): ParsedAnswer;
+//# sourceMappingURL=extraction-prompt.d.ts.map

package/lib/extraction-prompt.js

@@ -0,0 +1,139 @@
+/**
+ * The extraction prompt: what deserves a memory, how each type reads, and
+ * the closed proposal format the model must answer in.
+ *
+ * The taxonomy moved here verbatim-in-spirit from the main-session guide
+ * (the 4a1e57d version) when the store became a gated database: the
+ * extraction model is the only writer left that needs the write-quality
+ * rules, so teaching them in the main session would be spent tokens twice.
+ * The model proposes; the store's gates (constraints, secret screen, dedup,
+ * feedback contract) decide — the proposal is never trusted on its own.
+ */
+/** The extraction model's system prompt (Chinese — memory content is Chinese-first). */
+export const EXTRACTION_SYSTEM_PROMPT = `你是记忆提取专员。你的唯一任务：从会话轨迹增量里判断哪些信息值得存入用户的跨会话持久记忆，并提出结构化提案。你不执行任务、不回答用户、不解释推理。
+
+## 何时写入记忆
+
+<type name="user">
+  <when_to_save>得知用户的画像与环境事实：角色、技术栈、经验水平、偏好，以及机器与工具链（操作系统、装了什么、配置在哪）。例："我在 Fedora 上工作，日常跑 dotnet-desktop profile"。</when_to_save>
+</type>
+
+<type name="feedback">
+  <when_to_save>两类信号：
+  （1）纠正——用户说"不是这样""别""停下"的那一轮，存被纠正的做法与正确做法；
+  （2）确认——更安静但同样要紧：用户接受了你不寻常的选择而无异议，或明确说"对，就这样"。只存纠错会让行为越来越保守。
+  例："测试别 mock 数据库，上次 mock 过了线上迁移挂了"——存规则并带上事故原因。</when_to_save>
+  <body_structure>规则先行，随后必带两行：**Why:**（用户给的理由——知道为什么才能判断边缘情况）和 **How to apply:**（何时何地生效）。缺这两行的提案会被机械拒绝。</body_structure>
+</type>
+
+<type name="reference">
+  <when_to_save>用户提到未来会用到的资源指针：URL、仪表盘、工单、本地数据库、文档位置。</when_to_save>
+</type>
+
+**边界判据：换一个仓库还有用的信息才进记忆。**决策、架构取舍、进行中状态只对当前仓库有价值——它们走仓库的 ADR/文档路线，绝不提案。能从代码、git 历史、仓库文件里重新推导出来的事实不存；临时任务状态、一次性调试过程、无复现证据的问题修复不存。相对日期一律转成绝对日期（"周四"→"2026-10-08"）。
+
+## 更新优先于新建
+
+已有记忆的状态变了，提案 update 改原条目；新旧并存比没有记忆更糟。要更新或删除的条目会连同全文给你，提案里写它的 id。没有值得沉淀的东西就明确说 skip——宁缺勿滥。
+
+## 输出格式
+
+只输出一个 JSON 对象，不要代码围栏、不要解释：
+
+{"decision":"apply"|"skip","reason":"<一句话依据>","proposals":[{"action":"create"|"update"|"delete","id":"<kebab-slug，update/delete 必填>","type":"user"|"feedback"|"reference","title":"<短标题>","description":"<一句话相关性钩子>","body":"<正文>","sourceSeqs":"<用户原话所在 seq，如 820-831，可省略>"}]}`;
+/** The existing-memory manifest line shown to the model. */
+export function manifestLineOf(record) {
+    return `- id=${record.id}｜type=${record.type}｜title=${record.title}｜钩子=${record.description}`;
+}
+/** The user-prompt block for one extraction run. */
+export function extractionPrompt(input) {
+    const parts = [];
+    parts.push(`<manifest>
+本工作区现有记忆（提案 update/delete 时引用这里的 id；与增量相似度最高的候选全文附后）：
+${input.manifest.length > 0 ? input.manifest.join("\n") : "（本工作区还没有记忆）"}
+</manifest>`);
+    if (input.candidates.length > 0) {
+        parts.push(`<candidates>
+${input.candidates.join("\n\n")}
+</candidates>`);
+    }
+    parts.push(`<increment>
+（用户直接发言所在 seq：${input.userSeqs.length > 0 ? input.userSeqs.join(",") : "无"}）
+${input.increment}
+</increment>`);
+    parts.push("按系统指令输出 JSON 提案。");
+    return parts.join("\n\n");
+}
+/** Proposals per run cap — bounds the damage a bad model answer can do. */
+export const MAX_PROPOSALS_PER_RUN = 8;
+/**
+ * Parse the model's JSON answer. Tolerates code fences; rejects anything
+ * that is not the agreed shape. A genuine "skip" is a model decision the
+ * caller may act on (consume the increment); "error" marks an unparseable
+ * or shape-violating answer, which must never land as a silent success.
+ */
+export function parseExtractionAnswer(text) {
+    const stripped = text.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
+    const start = stripped.indexOf("{");
+    const end = stripped.lastIndexOf("}");
+    if (start < 0 || end <= start) {
+        return { decision: "error", reason: "unparseable output: no JSON object found", proposals: [] };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(stripped.slice(start, end + 1));
+    }
+    catch (error) {
+        return {
+            decision: "error",
+            reason: `unparseable output: ${error instanceof Error ? error.message : String(error)}`,
+            proposals: [],
+        };
+    }
+    // Defensive: the sliced text always starts with "{", so a successful
+    // JSON.parse here is always an object — the branch is unreachable today
+    // but stays as a guard against future slicing changes.
+    /* v8 ignore next 3 */
+    if (typeof parsed !== "object" || parsed === null) {
+        return { decision: "error", reason: "unparseable output: not an object", proposals: [] };
+    }
+    const answer = parsed;
+    const reason = typeof answer.reason === "string" ? answer.reason : "";
+    if (answer.decision === "skip") {
+        return { decision: "skip", reason: reason || "model chose to skip", proposals: [] };
+    }
+    if (answer.decision !== "apply") {
+        return { decision: "error", reason: `unknown decision ${String(answer.decision)}`, proposals: [] };
+    }
+    if (!Array.isArray(answer.proposals)) {
+        return { decision: "error", reason: "apply without a proposals array", proposals: [] };
+    }
+    const proposals = [];
+    for (const raw of answer.proposals) {
+        if (typeof raw !== "object" || raw === null) {
+            continue;
+        }
+        const item = raw;
+        const action = item.action;
+        if (action !== "create" && action !== "update" && action !== "delete") {
+            continue;
+        }
+        proposals.push({
+            action,
+            id: typeof item.id === "string" ? item.id : undefined,
+            type: typeof item.type === "string" ? item.type : undefined,
+            title: typeof item.title === "string" ? item.title : undefined,
+            description: typeof item.description === "string" ? item.description : undefined,
+            body: typeof item.body === "string" ? item.body : undefined,
+            sourceSeqs: typeof item.sourceSeqs === "string" ? item.sourceSeqs : undefined,
+        });
+        if (proposals.length >= MAX_PROPOSALS_PER_RUN) {
+            break;
+        }
+    }
+    if (proposals.length === 0) {
+        return { decision: "error", reason: reason || "apply carried no usable proposals", proposals: [] };
+    }
+    return { decision: "apply", reason, proposals };
+}
+//# sourceMappingURL=extraction-prompt.js.map

package/lib/extraction-surface.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Trajectory slicing for the extraction pipeline: the bounded, mechanically
+ * filtered increment of one session since the last extraction cursor.
+ *
+ * The mechanics carry over from the v0.10.4 turn snapshots (proven against
+ * real DSH session surfaces): a `seq:<n>` cursor selects rows after the last
+ * boundary, direct-user rows drive the eligibility gate, and only
+ * user/assistant text is serialized. Judgment about what deserves a memory
+ * is the extraction model's job — this module only removes mechanical noise
+ * before any tokens are spent.
+ */
+/** ZCode's minimum lexical words in the increment's direct user text. */
+export declare const MEMORY_MIN_USER_WORDS = 3;
+/** Default ceiling for the serialized increment handed to the model. */
+export declare const DEFAULT_INCREMENT_MAX_CHARS = 40000;
+/** Why an extraction run was skipped without (or before) an LLM call. */
+export type SkipReason = "internal-agent" | "no-new-events" | "no-user-prose" | "direct-memory-write" | "no-route" | "empty-increment";
+/** The session surface reader this plugin consumes (duck-typed). */
+export interface SurfaceReader {
+    readSurface(sessionId: string): Promise<{
+        events: unknown[];
+    }>;
+}
+export interface SliceInput {
+    events: readonly unknown[];
+    internalAgent: boolean;
+    minUserWords?: number;
+}
+export interface Slice {
+    /** The increment rows after the cursor (already selected by the caller). */
+    events: readonly unknown[];
+    eligible: boolean;
+    skipReason?: SkipReason;
+    /** Direct user text in the increment (the extraction model's evidence). */
+    userText: string;
+    /** Seq numbers of the direct user rows, for record provenance. */
+    userSeqs: number[];
+}
+/**
+ * Judge whether the increment deserves a model call. This intentionally does
+ * not decide whether a fact is valuable — only that there is new, real user
+ * prose to extract from.
+ */
+export declare function evaluateSlice(input: SliceInput): Slice;
+/**
+ * True when the increment already contains a `memory_write` tool call: the
+ * user's explicit instruction was handled in-turn by the gated write path,
+ * so re-extracting the same turn would only duplicate it.
+ */
+export declare function containsExplicitMemoryWrite(events: readonly unknown[]): boolean;
+/** The new boundary after processing these events: `seq:<max>` or the count. */
+export declare function boundaryCursorOf(events: readonly unknown[]): string;
+/** Numeric boundary of a `seq:<n>` cursor (undefined for index cursors). */
+export declare function seqOfCursor(cursor: string | undefined): number | undefined;
+/** Rows after the cursor: everything with a seq beyond it (seq-less rows stay). */
+export declare function eventsAfterCursor(events: readonly unknown[], cursor: string | undefined): readonly unknown[];
+/**
+ * Serialize only user/assistant text, keeping the bounded tail. Tool calls,
+ * reasoning, and metadata never enter the prompt.
+ */
+export declare function serializeIncrement(events: readonly unknown[], maxChars?: number): string;
+/** A DSH subagent header is an internal source when its origin says so. */
+export declare function isInternalAgent(agent: unknown): boolean;
+/** Lexical word count via Intl.Segmenter — CJK text counts characters as words. */
+export declare function countWords(text: string): number;
+//# sourceMappingURL=extraction-surface.d.ts.map

package/lib/extraction-surface.js

@@ -0,0 +1,186 @@
+/**
+ * Trajectory slicing for the extraction pipeline: the bounded, mechanically
+ * filtered increment of one session since the last extraction cursor.
+ *
+ * The mechanics carry over from the v0.10.4 turn snapshots (proven against
+ * real DSH session surfaces): a `seq:<n>` cursor selects rows after the last
+ * boundary, direct-user rows drive the eligibility gate, and only
+ * user/assistant text is serialized. Judgment about what deserves a memory
+ * is the extraction model's job — this module only removes mechanical noise
+ * before any tokens are spent.
+ */
+/** ZCode's minimum lexical words in the increment's direct user text. */
+export const MEMORY_MIN_USER_WORDS = 3;
+/** Default ceiling for the serialized increment handed to the model. */
+export const DEFAULT_INCREMENT_MAX_CHARS = 40_000;
+/** CJK-aware word segmenter (lexical words, not whitespace splits). */
+const WORD_SEGMENTER = new Intl.Segmenter("und", { granularity: "word" });
+/**
+ * Judge whether the increment deserves a model call. This intentionally does
+ * not decide whether a fact is valuable — only that there is new, real user
+ * prose to extract from.
+ */
+export function evaluateSlice(input) {
+    const { events } = input;
+    const userSeqs = directUserSeqs(events);
+    if (input.internalAgent) {
+        return { events, eligible: false, skipReason: "internal-agent", userText: "", userSeqs };
+    }
+    if (events.length === 0) {
+        return { events, eligible: false, skipReason: "no-new-events", userText: "", userSeqs };
+    }
+    if (containsExplicitMemoryWrite(events)) {
+        return { events, eligible: false, skipReason: "direct-memory-write", userText: "", userSeqs };
+    }
+    const userText = directUserText(events);
+    if (countWords(userText) < (input.minUserWords ?? MEMORY_MIN_USER_WORDS)) {
+        return { events, eligible: false, skipReason: "no-user-prose", userText, userSeqs };
+    }
+    return { events, eligible: true, userText, userSeqs };
+}
+/**
+ * True when the increment already contains a `memory_write` tool call: the
+ * user's explicit instruction was handled in-turn by the gated write path,
+ * so re-extracting the same turn would only duplicate it.
+ */
+export function containsExplicitMemoryWrite(events) {
+    for (const raw of events) {
+        if (!raw || typeof raw !== "object") {
+            continue;
+        }
+        const row = raw;
+        if (row.type !== "tool/call" && row.type !== "tool-call") {
+            continue;
+        }
+        const name = row.data?.name ?? row.data?.tool ?? row.data?.toolName;
+        if (typeof name === "string" && name.trim() === "memory_write") {
+            return true;
+        }
+    }
+    return false;
+}
+/** The new boundary after processing these events: `seq:<max>` or the count. */
+export function boundaryCursorOf(events) {
+    const seqs = events.map(eventSeq).filter((seq) => seq !== undefined);
+    return seqs.length > 0 ? `seq:${Math.max(...seqs)}` : `index:${events.length}`;
+}
+/** Numeric boundary of a `seq:<n>` cursor (undefined for index cursors). */
+export function seqOfCursor(cursor) {
+    if (cursor === undefined || !cursor.startsWith("seq:")) {
+        return undefined;
+    }
+    const value = Number(cursor.slice(4));
+    return Number.isInteger(value) ? value : undefined;
+}
+/** Rows after the cursor: everything with a seq beyond it (seq-less rows stay). */
+export function eventsAfterCursor(events, cursor) {
+    const boundary = seqOfCursor(cursor);
+    if (boundary === undefined) {
+        return cursor === undefined ? events : [];
+    }
+    return events.filter((event) => {
+        const seq = eventSeq(event);
+        return seq === undefined || seq > boundary;
+    });
+}
+/**
+ * Serialize only user/assistant text, keeping the bounded tail. Tool calls,
+ * reasoning, and metadata never enter the prompt.
+ */
+export function serializeIncrement(events, maxChars = DEFAULT_INCREMENT_MAX_CHARS) {
+    const lines = [];
+    for (const raw of events) {
+        if (!raw || typeof raw !== "object") {
+            continue;
+        }
+        const event = raw;
+        const role = event.type === "user/message" ? "user" : event.type === "assistant/message" ? "assistant" : null;
+        if (role === null) {
+            continue;
+        }
+        if (role === "user" && !isDirectUserEvent(raw)) {
+            continue;
+        }
+        const text = contentText(event.data?.content).trim();
+        if (text.length > 0) {
+            lines.push(`${role}: ${text}`);
+        }
+    }
+    const joined = lines.join("\n");
+    return joined.length <= maxChars ? joined : joined.slice(-maxChars);
+}
+/** A DSH subagent header is an internal source when its origin says so. */
+export function isInternalAgent(agent) {
+    const header = agent
+        ?.session?.header;
+    return header?.origin === "subagent" || header?.origin === "internal" || header?.isSubagent === true;
+}
+/** Lexical word count via Intl.Segmenter — CJK text counts characters as words. */
+export function countWords(text) {
+    return [...WORD_SEGMENTER.segment(text)].filter((segment) => segment.isWordLike).length;
+}
+/** Direct user rows: real user text, not synthetic injections or tool output. */
+function isDirectUserEvent(event) {
+    if (!event || typeof event !== "object") {
+        return false;
+    }
+    const row = event;
+    if (row.type !== "user/message") {
+        return false;
+    }
+    if (row.data?.visibility === "model-only") {
+        return false;
+    }
+    if (row.data?.source?.synthetic === true) {
+        return false;
+    }
+    if (row.data?.source?.kind !== undefined && row.data.source.kind !== "user") {
+        return false;
+    }
+    return contentText(row.data?.content).trim().length > 0;
+}
+function directUserText(events) {
+    return events
+        .filter(isDirectUserEvent)
+        .map((event) => contentText(event.data?.content).trim())
+        .filter(Boolean)
+        .join("\n");
+}
+function directUserSeqs(events) {
+    return events
+        .filter(isDirectUserEvent)
+        .map(eventSeq)
+        .filter((seq) => seq !== undefined);
+}
+function contentText(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    return content
+        .map((block) => {
+        if (typeof block === "string") {
+            return block;
+        }
+        if (!block || typeof block !== "object") {
+            return "";
+        }
+        const value = block;
+        if (value.synthetic === true || value.ignored === true || (value.type !== undefined && value.type !== "text")) {
+            return "";
+        }
+        return typeof value.text === "string" ? value.text : "";
+    })
+        .filter(Boolean)
+        .join(" ");
+}
+function eventSeq(event) {
+    if (!event || typeof event !== "object") {
+        return undefined;
+    }
+    const seq = event.seq;
+    return typeof seq === "number" && Number.isInteger(seq) ? seq : undefined;
+}
+//# sourceMappingURL=extraction-surface.js.map

package/lib/extraction.d.ts

@@ -0,0 +1,60 @@
+import { type SkipReason, type SurfaceReader } from "./extraction-surface.js";
+import type { LedgerEntry, MemoryStore } from "./store.js";
+/** The minimal LLM face extraction calls (duck-typed host service). */
+export interface LlmStream {
+    stream(options: Record<string, unknown>): AsyncIterable<unknown>;
+}
+/** Everything a run needs: the store, the session reader, and the LLM. */
+export interface ExtractionDeps {
+    store: MemoryStore;
+    surface: SurfaceReader | undefined;
+    llm: LlmStream | undefined;
+}
+/** One extraction target: whose session, in which workspace, on which route. */
+export interface ExtractionTarget {
+    workspaceId: string | undefined;
+    sessionId: string;
+    internalAgent: boolean;
+    provider: string | undefined;
+    model: string | undefined;
+}
+/** Terminal outcome of one run. */
+export interface ExtractionResult {
+    status: "applied" | "rejected" | "skipped" | "failed";
+    skipReason?: SkipReason | string | undefined;
+    /** Mutations landed (status "applied"). */
+    applied?: number | undefined;
+    /** The seq boundary the cursor advanced to (status "applied" or model skip). */
+    cursor?: number | undefined;
+}
+/** Options for one run. */
+export interface RunOptions {
+    trigger: LedgerEntry["trigger"];
+    /** Character ceiling for the serialized increment (default 40000). */
+    incrementMaxChars?: number;
+}
+/**
+ * Run one extraction pass for a target. Never throws: every terminal path
+ * is either a landed application, a ledgered skip, or a ledgered failure.
+ */
+export declare function runExtraction(deps: ExtractionDeps, target: ExtractionTarget, opts: RunOptions): Promise<ExtractionResult>;
+/** The event wiring surface (duck-typed cordis context). */
+export interface SchedulerHost {
+    on(event: string, handler: (...args: never[]) => void): unknown;
+    logger(name: string): {
+        info(message: string): void;
+        warn(message: string): void;
+    };
+}
+export interface SchedulerOptions {
+    /** Idle debounce in minutes (default 10); 0 fires on every turn. */
+    debounceMin?: number;
+}
+/**
+ * Wire the extraction triggers onto the host context. Returns a disposer
+ * that removes the listeners and clears the timer. The scheduler is the
+ * only background automation the plugin runs, and it is bounded by design:
+ * one timer, one in-flight run, one pending slot.
+ */
+export declare function createExtractionScheduler(host: SchedulerHost, deps: ExtractionDeps, options?: SchedulerOptions): () => void;
+//# sourceMappingURL=extraction.d.ts.map