@xrkseek/harness 0.4.0-rc.4 → 0.4.1

package/node_modules/@xrkseek/session-telemetry/dist/index.js

@@ -5,7 +5,24 @@ export { opsRecord, recordFromSessionEvent, } from "./record.js";
 export { createMemorySessionTelemetrySink, } from "./memory.js";
 export { createOtlpHttpSessionTelemetrySink, resolveOtlpLogsEndpoint, } from "./otlp-http.js";
 export { wrapStoreForSessionTelemetry, } from "./wrap-store.js";
-export function sessionTelemetryUnavailableMessage(env = process.env) {
+/** Parse a Face `session-telemetry` namespace value (unknown → product or undefined). */
+export function parseSessionTelemetryProduct(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return undefined;
+    const row = raw;
+    const modeRaw = typeof row.mode === "string" ? row.mode.trim().toLowerCase() : "";
+    const mode = modeRaw === "memory" || modeRaw === "otlp" || modeRaw === "off"
+        ? modeRaw
+        : "off";
+    const endpoint = typeof row.endpoint === "string" && row.endpoint.trim()
+        ? row.endpoint.trim()
+        : undefined;
+    return {
+        mode,
+        ...(endpoint ? { endpoint } : {}),
+    };
+}
+export function sessionTelemetryUnavailableMessage(env = process.env, product) {
     const flag = String(env.XRK_TELEMETRY ?? "").trim().toLowerCase();
     if (flag === "0" || flag === "off" || flag === "disabled") {
         return "Session telemetry disabled (XRK_TELEMETRY=0).";
@@ -17,61 +34,105 @@ export function sessionTelemetryUnavailableMessage(env = process.env) {
         return ("XRK_TELEMETRY=1 but no OTLP endpoint. Set XRK_TELEMETRY_OTLP_ENDPOINT " +
             "or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT.");
     }
-    return ("Session telemetry is off. Set XRK_TELEMETRY=memory, or XRK_TELEMETRY=1 " +
-        "with an OTLP logs endpoint. See docs/session-telemetry.md.");
+    if (flag === "" && product) {
+        if (product.mode === "off") {
+            return "Session telemetry disabled (Settings → session-telemetry mode=off).";
+        }
+        if (product.mode === "memory") {
+            return "Session telemetry memory sink (Settings).";
+        }
+        return ("Session telemetry OTLP (Settings) but no endpoint. Set endpoint in " +
+            "Settings or XRK_TELEMETRY_OTLP_ENDPOINT / OTEL_*.");
+    }
+    return ("Session telemetry is off. Set Settings → session-telemetry, or " +
+        "XRK_TELEMETRY=memory / XRK_TELEMETRY=1 with an OTLP logs endpoint. " +
+        "See docs/session-telemetry.md.");
+}
+function otlpHeadersFromEnv(env) {
+    const headersRaw = String(env.OTEL_EXPORTER_OTLP_HEADERS ?? "").trim();
+    const headers = {};
+    if (!headersRaw)
+        return headers;
+    for (const part of headersRaw.split(",")) {
+        const idx = part.indexOf("=");
+        if (idx <= 0)
+            continue;
+        headers[part.slice(0, idx).trim()] = part.slice(idx + 1).trim();
+    }
+    return headers;
+}
+function buildOtlpSink(endpoint, options, env) {
+    const headers = otlpHeadersFromEnv(env);
+    return createOtlpHttpSessionTelemetrySink({
+        endpoint,
+        ...(Object.keys(headers).length ? { headers } : {}),
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
+        ...(options.serviceName ? { serviceName: options.serviceName } : {}),
+    });
 }
 /**
  * Resolve a session-telemetry sink.
  * - Injected `sink` wins.
- * - `XRK_TELEMETRY=0` → disabled.
- * - `XRK_TELEMETRY=memory` → memory sink.
- * - `XRK_TELEMETRY=1` / `otlp` + endpoint → OTLP/HTTP logs.
+ * - Non-empty `XRK_TELEMETRY` → env path (CI bypass over Settings).
+ * - Else Face `product` (`off` / `memory` / `otlp` + endpoint).
  * - Else if a standard OTEL_* endpoint is set → OTLP (opt-in via endpoint alone).
+ * - Else disabled.
  */
 export function createDefaultSessionTelemetryAccess(options = {}) {
     const env = options.env ?? process.env;
-    const unavailableMessage = sessionTelemetryUnavailableMessage(env);
+    const product = options.product;
+    const unavailableMessage = sessionTelemetryUnavailableMessage(env, product);
     if (options.sink) {
         return { sink: options.sink, unavailableMessage };
     }
     const flag = String(env.XRK_TELEMETRY ?? "").trim().toLowerCase();
-    if (flag === "0" || flag === "off" || flag === "disabled") {
+    // CI / shell bypass: any explicit XRK_TELEMETRY wins over Face Settings.
+    if (flag !== "") {
+        if (flag === "0" || flag === "off" || flag === "disabled") {
+            return { unavailableMessage };
+        }
+        if (flag === "memory") {
+            return {
+                sink: createMemorySessionTelemetrySink(),
+                unavailableMessage,
+            };
+        }
+        const endpoint = resolveOtlpLogsEndpoint(env);
+        const wantOtlp = flag === "1" || flag === "otlp" || flag === "otel";
+        if (wantOtlp) {
+            if (!endpoint)
+                return { unavailableMessage };
+            return {
+                sink: buildOtlpSink(endpoint, options, env),
+                unavailableMessage,
+            };
+        }
         return { unavailableMessage };
     }
-    if (flag === "memory") {
+    // Product Settings (Face `session-telemetry`).
+    if (product) {
+        if (product.mode === "off") {
+            return { unavailableMessage };
+        }
+        if (product.mode === "memory") {
+            return {
+                sink: createMemorySessionTelemetrySink(),
+                unavailableMessage,
+            };
+        }
+        const endpoint = product.endpoint?.trim() || resolveOtlpLogsEndpoint(env) || undefined;
+        if (!endpoint)
+            return { unavailableMessage };
         return {
-            sink: createMemorySessionTelemetrySink(),
+            sink: buildOtlpSink(endpoint, options, env),
             unavailableMessage,
         };
     }
+    // Legacy: OTEL endpoint alone still opt-in when no Face product was passed.
     const endpoint = resolveOtlpLogsEndpoint(env);
-    const wantOtlp = flag === "1" ||
-        flag === "otlp" ||
-        flag === "otel" ||
-        (flag === "" && Boolean(endpoint));
-    if (wantOtlp) {
-        if (!endpoint) {
-            return { unavailableMessage };
-        }
-        const headersRaw = String(env.OTEL_EXPORTER_OTLP_HEADERS ?? "").trim();
-        const headers = {};
-        if (headersRaw) {
-            for (const part of headersRaw.split(",")) {
-                const idx = part.indexOf("=");
-                if (idx <= 0)
-                    continue;
-                headers[part.slice(0, idx).trim()] = part.slice(idx + 1).trim();
-            }
-        }
+    if (endpoint) {
         return {
-            sink: createOtlpHttpSessionTelemetrySink({
-                endpoint,
-                ...(Object.keys(headers).length ? { headers } : {}),
-                ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
-                ...(options.serviceName
-                    ? { serviceName: options.serviceName }
-                    : {}),
-            }),
+            sink: buildOtlpSink(endpoint, options, env),
             unavailableMessage,
         };
     }

package/node_modules/@xrkseek/session-telemetry/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GAExB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,qBAAqB,GAKtB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,SAAS,EACT,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gCAAgC,GAEjC,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kCAAkC,EAClC,uBAAuB,GAGxB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,4BAA4B,GAE7B,MAAM,iBAAiB,CAAC;AAczB,MAAM,UAAU,kCAAkC,CAChD,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC1D,OAAO,+CAA+C,CAAC;IACzD,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO,gCAAgC,CAAC;IAC1C,CAAC;IACD,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,MAAM,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QACvD,OAAO,CACL,wEAAwE;YACxE,oEAAoE,CACrE,CAAC;IACJ,CAAC;IACD,OAAO,CACL,yEAAyE;QACzE,4DAA4D,CAC7D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mCAAmC,CACjD,UAAgD,EAAE;IAElD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACvC,MAAM,kBAAkB,GAAG,kCAAkC,CAAC,GAAG,CAAC,CAAC;IACnE,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QACjB,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,kBAAkB,EAAE,CAAC;IACpD,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClE,IAAI,IAAI,KAAK,GAAG,IAAI,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,UAAU,EAAE,CAAC;QAC1D,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAChC,CAAC;IACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;QACtB,OAAO;YACL,IAAI,EAAE,gCAAgC,EAAE;YACxC,kBAAkB;SACnB,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,uBAAuB,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,QAAQ,GACZ,IAAI,KAAK,GAAG;QACZ,IAAI,KAAK,MAAM;QACf,IAAI,KAAK,MAAM;QACf,CAAC,IAAI,KAAK,EAAE,IAAI,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;IACrC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAChC,CAAC;QACD,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACvE,MAAM,OAAO,GAA2B,EAAE,CAAC;QAC3C,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;gBACzC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;gBAC9B,IAAI,GAAG,IAAI,CAAC;oBAAE,SAAS;gBACvB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAClE,CAAC;QACH,CAAC;QACD,OAAO;YACL,IAAI,EAAE,kCAAkC,CAAC;gBACvC,QAAQ;gBACR,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACnD,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC9D,GAAG,CAAC,OAAO,CAAC,WAAW;oBACrB,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE;oBACtC,CAAC,CAAC,EAAE,CAAC;aACR,CAAC;YACF,kBAAkB;SACnB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAChC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/spill/README.md

@@ -0,0 +1,27 @@
+# `@xrkseek/spill`
+
+> **读者**：贡献者 · Host / agent-loop 维护者。
+
+工具结果溢出（spill）的 **locator 契约**、本机存储、与策略层分离。
+
+| 层 | 职责 |
+|----|------|
+| `SpillStore` / `LocalSpillStore` | 落盘、返回不透明 `SpillLocator` + `retrievalHint` |
+| `applySpillPolicy` / `formatSpillNotice` | 何时溢出、inline 预览、模型可见 notice |
+| `parseSpillLocator` | 从 pipeline / loop notice 解析路径（概况 Status 打开 spill） |
+
+默认根目录：`{XRK_HOME}/spill`（工具结果在 `tool-outputs/`）。
+
+---
+
+> **Audience**: Contributors · Host / agent-loop maintainers.
+
+**Locator contract**, local store, and policy layer for oversized tool results — storage ≠ policy.
+
+| Layer | Role |
+|-------|------|
+| `SpillStore` / `LocalSpillStore` | Persist bytes; return opaque `SpillLocator` + `retrievalHint` |
+| `applySpillPolicy` / `formatSpillNotice` | When to spill, inline preview, model-facing notice |
+| `parseSpillLocator` | Parse path from pipeline / loop notices (Status “open spill”) |
+
+Default root: `{XRK_HOME}/spill` (`tool-outputs/` for tool bodies).

package/node_modules/@xrkseek/spill/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@xrkseek/spill` — locator contract, local store, tool-result spill policy.
+ *
+ * Storage ({@link SpillStore} / {@link LocalSpillStore}) and policy
+ * ({@link applySpillPolicy} / notices) are separate packages-of-concern so
+ * Host / agent-loop can swap backends without rewriting notice text.
+ */
+export { SpillLocator, type SpillOwner, type SpillSource, type SaveTextSpill, type SpillRef, type SpillStore, } from "./types.js";
+export { LocalSpillStore, defaultLocalSpillStore, defaultSpillRoot, encodeSpillSegment, resetDefaultLocalSpillStore, type LocalSpillStoreOptions, } from "./local-store.js";
+export { NO_SPILL_TOOLS, DEFAULT_SPILL_INLINE_BYTES, utf8Bytes, utf8Prefix, utf8Suffix, headTail, formatSpillNotice, parseSpillLocator, alreadySavedPath, fitInlineNotice, applySpillPolicy, type ApplySpillPolicyInput, type ApplySpillPolicyResult, } from "./policy.js";
+//# sourceMappingURL=index.d.ts.map

package/node_modules/@xrkseek/spill/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,2BAA2B,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,GAC5B,MAAM,aAAa,CAAC"}

package/node_modules/@xrkseek/spill/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@xrkseek/spill` — locator contract, local store, tool-result spill policy.
+ *
+ * Storage ({@link SpillStore} / {@link LocalSpillStore}) and policy
+ * ({@link applySpillPolicy} / notices) are separate packages-of-concern so
+ * Host / agent-loop can swap backends without rewriting notice text.
+ */
+export { SpillLocator, } from "./types.js";
+export { LocalSpillStore, defaultLocalSpillStore, defaultSpillRoot, encodeSpillSegment, resetDefaultLocalSpillStore, } from "./local-store.js";
+export { NO_SPILL_TOOLS, DEFAULT_SPILL_INLINE_BYTES, utf8Bytes, utf8Prefix, utf8Suffix, headTail, formatSpillNotice, parseSpillLocator, alreadySavedPath, fitInlineNotice, applySpillPolicy, } from "./policy.js";
+//# sourceMappingURL=index.js.map

package/node_modules/@xrkseek/spill/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,YAAY,GAMb,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,2BAA2B,GAE5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,cAAc,EACd,0BAA0B,EAC1B,SAAS,EACT,UAAU,EACV,UAAU,EACV,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GAGjB,MAAM,aAAa,CAAC"}

package/node_modules/@xrkseek/spill/dist/local-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Host-filesystem spill backend under `{XRK_HOME}/spill`.
+ */
+import { type SaveTextSpill, type SpillRef, type SpillStore } from "./types.js";
+export interface LocalSpillStoreOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Override spill root (tests). Default `{XRK_HOME}/spill`. */
+    readonly root?: string;
+    /** Subdir under root for tool results. Default `tool-outputs`. */
+    readonly toolRelativeDir?: string;
+}
+/** Encode one untrusted string as a single safe path segment. */
+export declare function encodeSpillSegment(raw: string): string;
+export declare function defaultSpillRoot(env?: NodeJS.ProcessEnv): string;
+/** Local filesystem {@link SpillStore}. */
+export declare class LocalSpillStore implements SpillStore {
+    private readonly root;
+    private readonly toolRelativeDir;
+    private readonly env;
+    constructor(options?: LocalSpillStoreOptions);
+    /** Absolute spill tree root (Host `hostReadableRoots`). */
+    get spillRoot(): string;
+    saveText(input: SaveTextSpill): Promise<SpillRef>;
+    saveTextSync(input: SaveTextSpill): SpillRef;
+}
+/** Process-wide default local store (lazy; rebinds when XRK_HOME changes). */
+export declare function defaultLocalSpillStore(env?: NodeJS.ProcessEnv): LocalSpillStore;
+/** Test hook: drop the shared singleton. */
+export declare function resetDefaultLocalSpillStore(): void;
+//# sourceMappingURL=local-store.d.ts.map

package/node_modules/@xrkseek/spill/dist/local-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.d.ts","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAKpB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE7E;AAED,2CAA2C;AAC3C,qBAAa,eAAgB,YAAW,UAAU;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoB;gBAE5B,OAAO,GAAE,sBAA2B;IAShD,2DAA2D;IAC3D,IAAI,SAAS,IAAI,MAAM,CAEtB;IAEK,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIvD,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ;CA6B7C;AAKD,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,eAAe,CAOjB;AAED,4CAA4C;AAC5C,wBAAgB,2BAA2B,IAAI,IAAI,CAGlD"}

package/node_modules/@xrkseek/spill/dist/local-store.js

@@ -0,0 +1,73 @@
+/**
+ * Host-filesystem spill backend under `{XRK_HOME}/spill`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { capSpillText, pruneSpillTree, resolveXrkHome, } from "@xrkseek/xrk-home-paths";
+import { SpillLocator, } from "./types.js";
+const DEFAULT_RETRIEVAL = "Retrieve with read_file or grep on that path.";
+/** Encode one untrusted string as a single safe path segment. */
+export function encodeSpillSegment(raw) {
+    if (raw.length === 0)
+        return "_";
+    return raw.replace(/[^\w.-]+/g, "_").slice(0, 120) || "_";
+}
+export function defaultSpillRoot(env = process.env) {
+    return path.join(resolveXrkHome(env), "spill");
+}
+/** Local filesystem {@link SpillStore}. */
+export class LocalSpillStore {
+    root;
+    toolRelativeDir;
+    env;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.root = path.resolve(options.root ?? defaultSpillRoot(this.env));
+        this.toolRelativeDir = (options.toolRelativeDir ?? "tool-outputs").replace(/\\/g, "/");
+    }
+    /** Absolute spill tree root (Host `hostReadableRoots`). */
+    get spillRoot() {
+        return this.root;
+    }
+    async saveText(input) {
+        return this.saveTextSync(input);
+    }
+    saveTextSync(input) {
+        pruneSpillTree(this.root);
+        const dir = input.source.kind === "tool"
+            ? path.join(this.root, this.toolRelativeDir)
+            : path.join(this.root, encodeSpillSegment(input.owner.sessionId));
+        mkdirSync(dir, { recursive: true });
+        const base = encodeSpillSegment(input.suggestedName.replace(/\.[^.]+$/, "") || "spill");
+        const ext = path.extname(input.suggestedName).replace(/[^\w.]/g, "") || ".txt";
+        const name = input.source.kind === "tool"
+            ? `${encodeSpillSegment(input.owner.sessionId)}_${encodeSpillSegment(input.source.callId) || "call"}${ext.startsWith(".") ? ext : `.${ext}`}`
+            : `${base}_${Date.now().toString(36)}${ext.startsWith(".") ? ext : `.${ext}`}`;
+        const file = path.join(dir, name);
+        const body = capSpillText(input.content);
+        writeFileSync(file, body, "utf8");
+        const bytes = Buffer.byteLength(body, "utf8");
+        return {
+            locator: SpillLocator(file),
+            bytes,
+            retrievalHint: DEFAULT_RETRIEVAL,
+        };
+    }
+}
+let shared;
+let sharedHome;
+/** Process-wide default local store (lazy; rebinds when XRK_HOME changes). */
+export function defaultLocalSpillStore(env = process.env) {
+    const home = resolveXrkHome(env);
+    if (!shared || sharedHome !== home) {
+        shared = new LocalSpillStore({ env });
+        sharedHome = home;
+    }
+    return shared;
+}
+/** Test hook: drop the shared singleton. */
+export function resetDefaultLocalSpillStore() {
+    shared = undefined;
+    sharedHome = undefined;
+}
+//# sourceMappingURL=local-store.js.map

package/node_modules/@xrkseek/spill/dist/local-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-store.js","sourceRoot":"","sources":["../src/local-store.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/spill/dist/policy.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tool-result spill policy — decides when/how to spill; storage stays on SpillStore.
+ * Learned from dsh `@deepseek-ai/dsh-spill-policy` (notice · skip tools · head/tail).
+ */
+import type { SpillLocator, SpillRef, SpillStore } from "./types.js";
+/** Tools that must stay inline (avoid read → spill → read loops). */
+export declare const NO_SPILL_TOOLS: Set<string>;
+/** Default inline ceiling (UTF-8 bytes); Face may override. */
+export declare const DEFAULT_SPILL_INLINE_BYTES = 64000;
+export declare function utf8Bytes(text: string): number;
+/** Prefix of `text` with at most `maxBytes` UTF-8 bytes (no mid-sequence cut). */
+export declare function utf8Prefix(text: string, maxBytes: number): string;
+/** Suffix of `text` with at most `maxBytes` UTF-8 bytes. */
+export declare function utf8Suffix(text: string, maxBytes: number): string;
+/** Head/tail preview: half budget each end, omit the middle. */
+export declare function headTail(text: string, budget: number): string;
+/**
+ * Model-facing spill notice (dsh-compatible wording).
+ * Keep stable — Host timeline / UI parse the path after `stored at:`.
+ */
+export declare function formatSpillNotice(args: {
+    readonly omittedBytes: number;
+    readonly ref: SpillRef;
+    /**
+     * When the body was already persisted by pipeline `persist`, skip the
+     * “(omitted ~N bytes…)” prefix so markers stay short.
+     */
+    readonly alreadyPersisted?: boolean;
+}): string;
+/**
+ * Parse a spill locator from pipeline / loop notices.
+ * Prefer an authoritative `savedPath` from the tool pipeline when present.
+ */
+export declare function parseSpillLocator(text: string): SpillLocator | undefined;
+/** @deprecated Prefer {@link parseSpillLocator}. */
+export declare const alreadySavedPath: (text: string) => string | undefined;
+export declare function fitInlineNotice(notice: string, plain: string, maxInline: number): string;
+export interface ApplySpillPolicyInput {
+    readonly sessionId: string;
+    readonly callId: string;
+    readonly toolName: string;
+    readonly plainText: string;
+    /** UTF-8 inline ceiling; omit → {@link DEFAULT_SPILL_INLINE_BYTES}; `0` → no spill. */
+    readonly maxInlineBytes?: number;
+    /** Authoritative full-body path from pipeline `outputPaths`. */
+    readonly savedPath?: string;
+    readonly store: SpillStore;
+}
+export interface ApplySpillPolicyResult {
+    readonly content: string;
+    readonly spilled: boolean;
+    readonly ref?: SpillRef;
+}
+/**
+ * Apply spill policy against a {@link SpillStore}.
+ * Sync when `store.saveTextSync` exists; otherwise throws (agent-loop needs sync).
+ */
+export declare function applySpillPolicy(input: ApplySpillPolicyInput): ApplySpillPolicyResult;
+//# sourceMappingURL=policy.d.ts.map

package/node_modules/@xrkseek/spill/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAGrE,qEAAqE;AACrE,eAAO,MAAM,cAAc,aAA+C,CAAC;AAE3E,+DAA+D;AAC/D,eAAO,MAAM,0BAA0B,QAAS,CAAC;AAEjD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUjE;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC;IACvB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC,GAAG,MAAM,CAUT;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAOxE;AAED,oDAAoD;AACpD,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SACV,CAAC;AAEhD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,gEAAgE;IAChE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC;CACzB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,qBAAqB,GAC3B,sBAAsB,CAyDxB"}

package/node_modules/@xrkseek/spill/dist/policy.js

@@ -0,0 +1,143 @@
+/**
+ * Tool-result spill policy — decides when/how to spill; storage stays on SpillStore.
+ * Learned from dsh `@deepseek-ai/dsh-spill-policy` (notice · skip tools · head/tail).
+ */
+import { SpillLocator as asSpillLocator } from "./types.js";
+/** Tools that must stay inline (avoid read → spill → read loops). */
+export const NO_SPILL_TOOLS = new Set(["read_file", "read", "read_image"]);
+/** Default inline ceiling (UTF-8 bytes); Face may override. */
+export const DEFAULT_SPILL_INLINE_BYTES = 64_000;
+export function utf8Bytes(text) {
+    return Buffer.byteLength(text, "utf8");
+}
+/** Prefix of `text` with at most `maxBytes` UTF-8 bytes (no mid-sequence cut). */
+export function utf8Prefix(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (utf8Bytes(text) <= maxBytes)
+        return text;
+    let end = Math.min(text.length, maxBytes);
+    let out = text.slice(0, end);
+    while (end > 0 && utf8Bytes(out) > maxBytes) {
+        end -= 1;
+        out = text.slice(0, end);
+    }
+    return out;
+}
+/** Suffix of `text` with at most `maxBytes` UTF-8 bytes. */
+export function utf8Suffix(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (utf8Bytes(text) <= maxBytes)
+        return text;
+    let start = Math.max(0, text.length - maxBytes);
+    let out = text.slice(start);
+    while (start < text.length && utf8Bytes(out) > maxBytes) {
+        start += 1;
+        out = text.slice(start);
+    }
+    return out;
+}
+/** Head/tail preview: half budget each end, omit the middle. */
+export function headTail(text, budget) {
+    if (utf8Bytes(text) <= budget)
+        return text;
+    const marker = "\n\n[... middle omitted ...]\n\n";
+    const markerBytes = utf8Bytes(marker);
+    const keep = Math.max(0, budget - markerBytes);
+    const headBytes = Math.ceil(keep / 2);
+    const tailBytes = Math.floor(keep / 2);
+    return `${utf8Prefix(text, headBytes)}${marker}${utf8Suffix(text, tailBytes)}`;
+}
+/**
+ * Model-facing spill notice (dsh-compatible wording).
+ * Keep stable — Host timeline / UI parse the path after `stored at:`.
+ */
+export function formatSpillNotice(args) {
+    const loc = String(args.ref.locator);
+    const hint = args.ref.retrievalHint.trim() || "Retrieve with read_file or grep on that path.";
+    if (args.alreadyPersisted) {
+        return `Full formatted result stored at: ${loc}. ${hint}\n\n`;
+    }
+    return (`(omitted ~${args.omittedBytes} bytes. Full formatted result stored at: ${loc}. ` +
+        `${hint})\n\n`);
+}
+/**
+ * Parse a spill locator from pipeline / loop notices.
+ * Prefer an authoritative `savedPath` from the tool pipeline when present.
+ */
+export function parseSpillLocator(text) {
+    const pipeline = text.match(/full content saved to (.+?)(?: \.\.\.| \.\.\.$|$)/m);
+    const loop = text.match(/Full formatted result stored at: (.+?)\. Retrieve/);
+    const loc = (pipeline?.[1] ?? loop?.[1])?.trim();
+    return loc ? asSpillLocator(loc) : undefined;
+}
+/** @deprecated Prefer {@link parseSpillLocator}. */
+export const alreadySavedPath = (text) => parseSpillLocator(text);
+export function fitInlineNotice(notice, plain, maxInline) {
+    const noticeBytes = utf8Bytes(notice);
+    if (noticeBytes >= maxInline)
+        return utf8Prefix(notice, maxInline);
+    let body = notice + headTail(plain, maxInline - noticeBytes);
+    if (utf8Bytes(body) > maxInline)
+        body = utf8Prefix(body, maxInline);
+    return body;
+}
+/**
+ * Apply spill policy against a {@link SpillStore}.
+ * Sync when `store.saveTextSync` exists; otherwise throws (agent-loop needs sync).
+ */
+export function applySpillPolicy(input) {
+    if (NO_SPILL_TOOLS.has(input.toolName)) {
+        return { content: input.plainText, spilled: false };
+    }
+    const maxInline = input.maxInlineBytes === undefined
+        ? DEFAULT_SPILL_INLINE_BYTES
+        : Math.max(0, Math.floor(input.maxInlineBytes));
+    if (maxInline === 0) {
+        return { content: input.plainText, spilled: false };
+    }
+    const total = utf8Bytes(input.plainText);
+    if (total <= maxInline) {
+        return { content: input.plainText, spilled: false };
+    }
+    const saved = (input.savedPath?.trim() ? input.savedPath.trim() : undefined) ??
+        parseSpillLocator(input.plainText);
+    let ref;
+    let alreadyPersisted = false;
+    if (saved) {
+        alreadyPersisted = true;
+        ref = {
+            locator: asSpillLocator(saved),
+            bytes: total,
+            retrievalHint: "Retrieve with read_file or grep on that path.",
+        };
+    }
+    else {
+        if (typeof input.store.saveTextSync !== "function") {
+            throw new Error("SpillStore.saveTextSync is required for synchronous tool-result spill");
+        }
+        ref = input.store.saveTextSync({
+            owner: { sessionId: input.sessionId },
+            source: {
+                kind: "tool",
+                toolName: input.toolName,
+                callId: input.callId,
+                label: input.toolName,
+            },
+            suggestedName: `${input.callId}.txt`,
+            content: input.plainText,
+        });
+    }
+    const notice = formatSpillNotice({
+        omittedBytes: total - maxInline,
+        ref,
+        alreadyPersisted,
+    });
+    return {
+        content: fitInlineNotice(notice, input.plainText, maxInline),
+        spilled: true,
+        ref,
+    };
+}
+//# sourceMappingURL=policy.js.map

package/node_modules/@xrkseek/spill/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/node_modules/@xrkseek/spill/dist/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Spill storage seam vocabulary (Cordis-free).
+ * Learned from dsh `@deepseek-ai/dsh-spill` types: opaque locator + retrieval hint.
+ */
+/** Opaque model-facing handle for one spilled artifact (often a filesystem path). */
+export type SpillLocator = string & {
+    readonly __brand: "SpillLocator";
+};
+export declare function SpillLocator(locator: string): SpillLocator;
+/** Session that owns the artifact at save time. */
+export interface SpillOwner {
+    readonly sessionId: string;
+}
+/** Producer of a spilled artifact (descriptive only — not access control). */
+export type SpillSource = {
+    readonly kind: "tool";
+    readonly toolName: string;
+    readonly callId: string;
+    readonly label: string;
+} | {
+    readonly kind: "session-reference";
+    readonly sessionId: string;
+    readonly label: string;
+};
+/** One request to persist text to a spill artifact. */
+export interface SaveTextSpill {
+    readonly owner: SpillOwner;
+    readonly source: SpillSource;
+    /** Caller-suggested base name (sanitized to one path segment). */
+    readonly suggestedName: string;
+    /** Full UTF-8 text to persist. */
+    readonly content: string;
+}
+/** Saved spill artifact: locator, bytes, and model-facing retrieval guidance. */
+export interface SpillRef {
+    readonly locator: SpillLocator;
+    readonly bytes: number;
+    readonly retrievalHint: string;
+}
+/** Abstract spill storage — persist full text; return opaque locator + hint. */
+export interface SpillStore {
+    saveText(input: SaveTextSpill): Promise<SpillRef>;
+    /** Sync path for agent-loop (no async turn boundary). */
+    saveTextSync?(input: SaveTextSpill): SpillRef;
+}
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@xrkseek/spill/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qFAAqF;AACrF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;CAAE,CAAC;AAEzE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,CAE1D;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,8EAA8E;AAC9E,MAAM,MAAM,WAAW,GACnB;IACE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEN,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,kEAAkE;IAClE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,gFAAgF;AAChF,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClD,yDAAyD;IACzD,YAAY,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,QAAQ,CAAC;CAC/C"}