@xrkseek/harness-cli 0.0.11 → 0.1.1

package/node_modules/@xrkseek/xrk-session-reference/README.md

@@ -0,0 +1,50 @@
+# `@xrkseek/xrk-session-reference`
+
+English | [中文](README.zh.md)
+
+`ctx.sessionReferenceResolver` prepares bounded, read-only snapshots of other sessions as sourced model-facing context. It consumes `ctx.sessionQuery` and the backend-independent compact checkpoint marker; SQLite FTS is not required. Hosts that support cross-session mentions may opt into the service.
+
+## Public API
+
+- `listCandidates(agent, query?, limit?)` lists sessions other than `agent.id`, filters case-insensitively by id, cwd, or the latest log-backed title, and ranks same-cwd, cwd-less, then other-cwd records while preserving `listSessions()` creation order within each group. Each selected candidate uses that title as the mention label and falls back to the session id when the title is absent or unreadable; message bodies are not searched. The unary `sessionReferenceResolver/candidates` Remote method serves the same discovery under the configured candidate limit and attaches each candidate's canonical mention, so browser consumers call `ctx.remote.sessionReferenceResolver.candidates` without an API Proxy route.
+- `prepare(agent, content, references, signal?)` preserves first-mention order, deduplicates ids, rejects self-reference and more than the configured distinct-source limit, reads every source in parallel, and returns detached content plus zero or one aggregated, identified `UserMessage` context. The service calls it for canonical mentions in direct user messages after downstream `agent/pre-step` listeners accept the step.
+- `encodeSessionReferenceUri()` and `decodeSessionReferenceUri()` implement `dsh-session:<base64url(JSON.stringify(sessionId))>` so every JavaScript string id round-trips exactly. `formatSessionReferenceMention()` emits `@[label](uri)`, and `parseSessionReferenceText()` replaces Markdown mentions or bare canonical URIs with readable `@label` text while returning structured references. Explicit Markdown mentions reject every malformed URI; bare text is considered a reference only when a non-empty base64url-shaped payload follows the scheme, and a matching noncanonical candidate still fails. Empty or punctuation-only scheme mentions remain ordinary discussion text.
+
+## Snapshot semantics
+
+Preparation calls `ctx.sessionQuery.readSurface()` once per distinct source when the target message reaches `agent/pre-step`. A queued message therefore captures the source state at model-step entry, and the resulting context is immutable after that point. Projection keeps only direct-user `user/message`, assistant text, and `user/message` checkpoints carrying the canonical `dsh-compaction` source marker from the folded current surface. Separately sourced session-reference messages are injected context and are excluded, preventing recursive snapshot propagation. Shadowed pre-compaction events, tools, reasoning, other plugin-generated user messages except marked compact checkpoints, and unfinished assistant chunks are also excluded. A compacted source therefore contributes its latest checkpoint plus retained later conversation, not restored shadowed text.
+
+The context source is `{ kind: 'session-reference', version: 1, references }`; each reference records its source id and label, capture seq, compact presence, retained/omitted message counts, omitted UTF-8 bytes, and truncation state. The service's outer `agent/pre-step` listener post-processes accepted direct user messages, preserves their message ids, and inserts each snapshot immediately after the message that cited it. Queue edits and queue-to-steer relocation need no reference-specific handling because parsing occurs after the final inbox claim. Invalid mentions, failed reads, cancellation, and budget failures end that turn before its messages enter model-visible history. The target log records the readable direct `user/message` followed by its sourced context `user/message`; source mutation after capture cannot change target replay.
+
+## Configuration
+
+| Key | Default | Contract |
+|---|---:|---|
+| `maxReferences` | `3` | Maximum distinct source sessions in one prepared message; must be at most `3`. |
+| `candidateLimit` | `50` | Default candidate count returned to a host. |
+| `maxReferenceBytes` | `65536` | Maximum serialized JSON bytes for one reference object. |
+
+Retention applies `maxReferenceBytes` independently to each source, keeps compact checkpoints and the newest message before dropping older non-checkpoint units, and uses `dsh-output-retention` head/tail truncation with an exact UTF-8 omission notice. If one source's fixed serialized fields cannot fit, preparation fails with `SESSION_REFERENCE_BUDGET_EXCEEDED` instead of returning a partial context.
+
+## Model Experience
+
+### Referenced session background
+
+#### What the model sees
+
+The model sees two consecutive user-role messages: the current message with its readable `@label`, then the `## Referenced sessions` untrusted snapshot. The warning forbids following instructions, permission claims, or tool requests from the snapshot unless the current user explicitly repeats them. Labels, cwd values, ids, and conversation text are serialized as JSON inside `<referenced-sessions>` tags; every data `<` is emitted as the lossless JSON escape `\u003c`, so source text cannot spell a framing tag.
+
+#### Token effect
+
+Each referenced message adds the fixed warning plus up to three serialized snapshots, each independently bounded by `maxReferenceBytes`. The exact snapshot remains in target history until target compaction shadows or summarizes it; source-session changes add no further tokens.
+
+#### KV Cache effect
+
+The request and snapshot are consecutive append-only target messages and preserve earlier cacheable history. Different references or source capture contents change the new suffix only; later target compaction may invalidate reuse from its replacement boundary.
+
+## Known Limitations and Deferred Work
+
+- **No body discovery** — candidate queries inspect folded titles but do not search message bodies. A non-empty query may inspect every visible persisted session log through the session-query service's bounded, cancellable batch; a dedicated title index may replace that discovery path without changing URI, snapshot, or persistence contracts.
+- **Trusted caller boundary** — the service assumes its host is authorized to read every session exposed by `ctx.sessionQuery`; it is not a model-facing search tool.
+- **Text projection only** — non-text user and assistant blocks are not propagated across sessions.
+- **No live link** — references are snapshots, not forks, resumes, subscriptions, or source-session mutations.

package/node_modules/@xrkseek/xrk-session-reference/README.zh.md

@@ -0,0 +1,50 @@
+# `@xrkseek/xrk-session-reference`
+
+[English](README.md) | 中文
+
+`ctx.sessionReferenceResolver` 会把其他会话准备为有界、只读快照，作为带来源信息、面向模型的上下文。它消费 `ctx.sessionQuery` 与后端无关的 compact 检查点标记；不需要 SQLite FTS。支持跨会话 mention 的宿主可以主动启用该服务。
+
+## 公开 API
+
+- `listCandidates(agent, query?, limit?)` 会列出 `agent.id` 之外的会话，按 id、cwd 或以日志为依据的最新标题进行不区分大小写的筛选，再按同 cwd、无 cwd、其他 cwd 记录排序，同时保持每组内的 `listSessions()` 创建顺序。每个已选候选会话都使用该标题作为 mention label；标题不存在或无法读取时回退到会话 id。不搜索消息主体。一元 `sessionReferenceResolver/candidates` Remote 方法在配置的候选上限内提供同一发现能力，并为每个候选附上规范 mention，浏览器消费方直接调用 `ctx.remote.sessionReferenceResolver.candidates`，无需 API Proxy 路由。
+- `prepare(agent, content, references, signal?)` 会保留首次 mention 顺序、对 id 去重，并拒绝自引用或超过已配置不同源上限的情况。它会并行读取所有源，返回与输入脱离的内容，外加零个或一个聚合且带标识的 `UserMessage` 上下文。下游 `agent/pre-step` 监听器接受步骤后，该服务会针对直接用户消息中的规范 mention 调用此方法。
+- `encodeSessionReferenceUri()` 与 `decodeSessionReferenceUri()` 实现 `dsh-session:<base64url(JSON.stringify(sessionId))>`，因此每个 JavaScript 字符串 id 都能精确往返。`formatSessionReferenceMention()` 发出 `@[label](uri)`，`parseSessionReferenceText()` 将 Markdown mention 或裸规范 URI 替换为可读的 `@label` 文本，并返回结构化引用。解析器会拒绝显式 Markdown mention 中任何格式错误的 URI；只当 scheme 后跟非空、符合 base64url 形状的 payload 时，裸文本才被视为引用，匹配但非规范的候选项仍会失败。空 scheme mention 或只含标点符号的 scheme mention 仍是普通讨论文本。
+
+## 快照语义
+
+目标消息到达 `agent/pre-step` 时，准备阶段会对每个不同源调用一次 `ctx.sessionQuery.readSurface()`。因此，queued 消息在进入模型步骤时捕获源状态，此后生成的上下文保持不变。它仅投影折叠后当前表层中的用户直接发出的 `user/message`、assistant 文本，以及 `user/message` 检查点；这类检查点携带规范 `dsh-compaction` 源标记。带独立来源的 session-reference 消息属于注入上下文，会被排除以防止快照递归传播。已遮蔽的压缩（compaction）前事件、工具、推理（reasoning）、除已标记 compact 检查点外的其他插件生成 user 消息，以及未完成的 assistant 分片也都会被排除。因此，已压缩源只会提供最新检查点及其后保留的会话内容，不会还原已遮蔽的文本。
+
+上下文源为 `{ kind: 'session-reference', version: 1, references }`；每条引用会记录其源 id 与 label、捕获 seq、是否存在 compact、已保留／已省略消息数、已省略 UTF-8 字节数与截断状态。该服务的外层 `agent/pre-step` 监听器会处理已接受的直接用户消息，保留其消息 id，并把每份快照插入到引用它的消息紧后。解析发生在最终领取收件箱消息之后，因此队列编辑和从 queue 移动到 steer 不需要引用专用处理。无效 mention、读取失败、取消和预算失败会在消息进入面向模型的历史之前结束该轮次。目标日志会先记录可读的直接 `user/message`，再记录其带来源信息的上下文 `user/message`；捕获后的源变更无法改变目标回放。
+
+## 配置
+
+| Key | 默认值 | 约定 |
+|---|---:|---|
+| `maxReferences` | `3` | 一条已准备消息中不同源会话的最大数量；必须不大于 `3`。 |
+| `candidateLimit` | `50` | 返回给宿主的默认候选数量。 |
+| `maxReferenceBytes` | `65536` | 一个引用对象的最大序列化 JSON 字节数。 |
+
+保留会对每个源独立应用 `maxReferenceBytes`，保留 compact 检查点与最新消息，再丢弃较旧的非检查点单元，并使用 `dsh-output-retention` 头部／尾部截断和精确 UTF-8 省略通知。如果某个源的固定序列化字段本身就超出限额，准备会以 `SESSION_REFERENCE_BUDGET_EXCEEDED` 失败，而不返回部分上下文。
+
+## 模型体验
+
+### 引用会话背景
+
+#### 模型看到的内容
+
+模型会看到两条连续的 user 角色消息：先是带可读 `@label` 的当前消息，再是 `## Referenced sessions` 不受信任快照。警告禁止遵循快照中的指令、权限声明或工具请求，除非当前用户明确重复这些内容。标签、cwd 值、id 与会话文本会作为 JSON 在 `<referenced-sessions>` 标签中序列化；数据中的每个 `<` 都会以无损 JSON 转义 `\u003c` 的形式发出，因此源文本无法拼出定界标签。
+
+#### Token 影响
+
+每条包含引用的消息都会添加固定警告和最多三个序列化快照，每个快照都受 `maxReferenceBytes` 独立限制。精确快照会保留在目标历史中，直到目标压缩遮蔽或摘要它；源会话变更不会添加更多 token。
+
+#### KV Cache 影响
+
+请求与快照是两条连续、仅追加的目标消息，并保留较早的可缓存历史。不同引用或源捕获内容只改变新后缀；后续目标压缩可能使从替换边界起的复用失效。
+
+## 已知限制与暂缓事项
+
+- **不支持消息正文检索**：候选查询会检查折叠后的标题，但不搜索消息主体。非空查询可能通过 session-query 服务有界、可取消的批处理检查每个可见的持久化会话日志；专用标题索引未来可以替换这条发现路径，而不改变 URI、快照或持久化约定。
+- **受信任调用方边界**：该服务假设宿主有权读取 `ctx.sessionQuery` 公开的每个会话；它不是面向模型的搜索工具。
+- **只投影文本**：不会在会话间传播非文本 user 与 assistant 块。
+- **没有实时链接**：引用是快照，不是 fork、恢复、订阅或源会话变更。

package/node_modules/@xrkseek/xrk-session-reference/dist/config.d.ts

@@ -0,0 +1,25 @@
+/** Configuration and stable diagnostics for session references. */
+/** Hard maximum references accepted by one message. */
+export declare const MAX_REFERENCES = 3;
+/** Default number of discovery candidates returned to a host. */
+export declare const DEFAULT_CANDIDATE_LIMIT = 50;
+/** Default UTF-8 budget for one rendered reference JSON object. */
+export declare const DEFAULT_MAX_REFERENCE_BYTES = 65536;
+/** Session-reference service configuration. */
+export interface Config {
+    /** Maximum distinct source sessions referenced by one message, from one to three. */
+    maxReferences?: number;
+    /** Default host candidate-list limit. */
+    candidateLimit?: number;
+    /** Maximum rendered UTF-8 bytes for one source snapshot. */
+    maxReferenceBytes?: number;
+}
+/** Stable failure codes exposed to host adapters. */
+export type SessionReferenceErrorCode = 'SESSION_REFERENCE_INVALID_CONFIG' | 'SESSION_REFERENCE_INVALID_REFERENCE' | 'SESSION_REFERENCE_SELF_REFERENCE' | 'SESSION_REFERENCE_TOO_MANY' | 'SESSION_REFERENCE_READ_FAILED' | 'SESSION_REFERENCE_BUDGET_EXCEEDED' | 'SESSION_REFERENCE_CANCELLED';
+/** Typed session-reference failure suitable for host protocol error mapping. */
+export declare class SessionReferenceError extends Error {
+    readonly code: SessionReferenceErrorCode;
+    /** @param message Human-readable diagnosis. @param code Stable routing code. @param options Optional cause. */
+    constructor(message: string, code: SessionReferenceErrorCode, options?: ErrorOptions);
+}
+//# sourceMappingURL=config.d.ts.map

package/node_modules/@xrkseek/xrk-session-reference/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAEnE,uDAAuD;AACvD,eAAO,MAAM,cAAc,IAAI,CAAA;AAC/B,iEAAiE;AACjE,eAAO,MAAM,uBAAuB,KAAK,CAAA;AACzC,mEAAmE;AACnE,eAAO,MAAM,2BAA2B,QAAS,CAAA;AAEjD,+CAA+C;AAC/C,MAAM,WAAW,MAAM;IACrB,qFAAqF;IACrF,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,4DAA4D;IAC5D,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,qDAAqD;AACrD,MAAM,MAAM,yBAAyB,GACjC,kCAAkC,GAClC,qCAAqC,GACrC,kCAAkC,GAClC,4BAA4B,GAC5B,+BAA+B,GAC/B,mCAAmC,GACnC,6BAA6B,CAAA;AAEjC,gFAAgF;AAChF,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,QAAQ,CAAC,IAAI,EAAE,yBAAyB;IAH1C,+GAA+G;gBAE7G,OAAO,EAAE,MAAM,EACN,IAAI,EAAE,yBAAyB,EACxC,OAAO,CAAC,EAAE,YAAY;CAKzB"}

package/node_modules/@xrkseek/xrk-session-reference/dist/config.js

@@ -0,0 +1,18 @@
+/** Configuration and stable diagnostics for session references. */
+/** Hard maximum references accepted by one message. */
+export const MAX_REFERENCES = 3;
+/** Default number of discovery candidates returned to a host. */
+export const DEFAULT_CANDIDATE_LIMIT = 50;
+/** Default UTF-8 budget for one rendered reference JSON object. */
+export const DEFAULT_MAX_REFERENCE_BYTES = 65_536;
+/** Typed session-reference failure suitable for host protocol error mapping. */
+export class SessionReferenceError extends Error {
+    code;
+    /** @param message Human-readable diagnosis. @param code Stable routing code. @param options Optional cause. */
+    constructor(message, code, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'SessionReferenceError';
+    }
+}
+//# sourceMappingURL=config.js.map

package/node_modules/@xrkseek/xrk-session-reference/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,mEAAmE;AAEnE,uDAAuD;AACvD,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAA;AAC/B,iEAAiE;AACjE,MAAM,CAAC,MAAM,uBAAuB,GAAG,EAAE,CAAA;AACzC,mEAAmE;AACnE,MAAM,CAAC,MAAM,2BAA2B,GAAG,MAAM,CAAA;AAsBjD,gFAAgF;AAChF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAInC;IAHX,+GAA+G;IAC/G,YACE,OAAe,EACN,IAA+B,EACxC,OAAsB;QAEtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAHd,SAAI,GAAJ,IAAI,CAA2B;QAIxC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAA;IACrC,CAAC;CACF"}

package/node_modules/@xrkseek/xrk-session-reference/dist/types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Public session-reference request, candidate, and preparation records.
+ * Face discovery imports stay on type-only subpaths; Cordis prepare lives in
+ * `index.ts` (not wired on XRK Host main path).
+ * @module @xrkseek/xrk-session-reference/types
+ */
+import type { ContentBlock, UserMessage } from '@xrkseek/protocol';
+/** Opaque session id (Face path; Cordis prepare uses branded ids when wired). */
+export type SessionId = string & {
+    readonly __xrkSessionId?: unique symbol;
+};
+/** Brand a raw session id string for URI codec helpers. */
+export declare function SessionId(id: string): SessionId;
+/** Durable source session, cited event seqs, and snapshot facts for prepared cross-session context. */
+export interface SessionReferenceSource {
+    kind: 'session-reference';
+    /** Material lifted out of another session's log (`recall` context form). */
+    form: 'recall';
+    version: 1;
+    references: {
+        sessionId: string;
+        label: string;
+        capturedThroughSeq: number | null;
+        compacted: boolean;
+        originalMessages: number;
+        retainedMessages: number;
+        omittedMessages: number;
+        omittedBytes: number;
+        truncated: boolean;
+        inputIndex: number;
+    }[];
+}
+/** One source session selected by a host. */
+export interface SessionReferenceInput {
+    /** Opaque source session identity. */
+    sessionId: SessionId;
+    /** Optional user-facing mention label. */
+    label?: string;
+}
+/** One host-facing candidate from exact session metadata. */
+export interface SessionReferenceCandidate {
+    /** Opaque source session identity. */
+    sessionId: SessionId;
+    /** Latest log-backed title, falling back to the opaque session id. */
+    label: string;
+    /** Source session working directory, when recorded. */
+    cwd?: string;
+    /** Source session creation time in Unix epoch milliseconds. */
+    createdAt: number;
+}
+/** One discovery candidate carrying its canonical prompt mention. */
+export interface SessionReferenceMentionCandidate extends SessionReferenceCandidate {
+    /** Canonical `@[label](dsh-session:…)` mention serialized into the prompt draft. */
+    mention: string;
+}
+/** Direct message content and optional referenced-session context. */
+export interface PreparedReferencedMessage {
+    /** Readable message content after host mention tokens are removed. */
+    content: ContentBlock[];
+    /** Aggregated untrusted snapshot, absent when the message has no references. */
+    additionalContext?: UserMessage;
+}
+/** Text-only projected conversation item. */
+export interface ReferencedConversationItem {
+    /** Original message role. */
+    role: 'user' | 'assistant';
+    /** Visible text retained from that message. */
+    text: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@xrkseek/xrk-session-reference/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAElE,iFAAiF;AACjF,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAE5E,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS,CAE/C;AAED,uGAAuG;AACvG,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,mBAAmB,CAAA;IACzB,4EAA4E;IAC5E,IAAI,EAAE,QAAQ,CAAA;IACd,OAAO,EAAE,CAAC,CAAA;IACV,UAAU,EAAE;QACV,SAAS,EAAE,MAAM,CAAA;QACjB,KAAK,EAAE,MAAM,CAAA;QACb,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;QACjC,SAAS,EAAE,OAAO,CAAA;QAClB,gBAAgB,EAAE,MAAM,CAAA;QACxB,gBAAgB,EAAE,MAAM,CAAA;QACxB,eAAe,EAAE,MAAM,CAAA;QACvB,YAAY,EAAE,MAAM,CAAA;QACpB,SAAS,EAAE,OAAO,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;KACnB,EAAE,CAAA;CACJ;AAED,6CAA6C;AAC7C,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,SAAS,EAAE,SAAS,CAAA;IACpB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,6DAA6D;AAC7D,MAAM,WAAW,yBAAyB;IACxC,sCAAsC;IACtC,SAAS,EAAE,SAAS,CAAA;IACpB,sEAAsE;IACtE,KAAK,EAAE,MAAM,CAAA;IACb,uDAAuD;IACvD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,+DAA+D;IAC/D,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,qEAAqE;AACrE,MAAM,WAAW,gCAAiC,SAAQ,yBAAyB;IACjF,oFAAoF;IACpF,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,sEAAsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,WAAW,CAAA;CAChC;AAED,6CAA6C;AAC7C,MAAM,WAAW,0BAA0B;IACzC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAA;CACb"}

package/node_modules/@xrkseek/xrk-session-reference/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * Public session-reference request, candidate, and preparation records.
+ * Face discovery imports stay on type-only subpaths; Cordis prepare lives in
+ * `index.ts` (not wired on XRK Host main path).
+ * @module @xrkseek/xrk-session-reference/types
+ */
+/** Brand a raw session id string for URI codec helpers. */
+export function SessionId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/node_modules/@xrkseek/xrk-session-reference/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,2DAA2D;AAC3D,MAAM,UAAU,SAAS,CAAC,EAAU;IAClC,OAAO,EAAe,CAAA;AACxB,CAAC"}

package/node_modules/@xrkseek/xrk-session-reference/dist/uri.d.ts

@@ -0,0 +1,40 @@
+/** Canonical session URI and inline mention encoding. */
+import { type SessionId as SessionIdType } from './types.js';
+import type { SessionReferenceInput } from './types.js';
+/** URI scheme reserved for XRK-Harness session snapshots. */
+export declare const SESSION_REFERENCE_SCHEME = "dsh-session:";
+/**
+ * Encode any JavaScript session-id string as a canonical lossless URI.
+ * @param sessionId - opaque session id to serialize.
+ * @returns canonical `dsh-session:` URI.
+ */
+export declare function encodeSessionReferenceUri(sessionId: SessionIdType): string;
+/**
+ * Decode and canonicalize one session-reference URI.
+ * @param uri - complete canonical URI.
+ * @returns decoded session id.
+ */
+export declare function decodeSessionReferenceUri(uri: string): SessionIdType;
+/**
+ * Render a host-neutral Markdown mention carrying the canonical URI.
+ * @param reference - structured id and optional display label.
+ * @returns escaped `@[label](uri)` mention.
+ */
+export declare function formatSessionReferenceMention(reference: SessionReferenceInput): string;
+/** Result of extracting canonical mentions from plain text. */
+export interface ParsedSessionReferenceText {
+    /** Text with opaque tokens replaced by readable `@label` spans. */
+    text: string;
+    /** Structured references in first-appearance order, before service deduplication. */
+    references: SessionReferenceInput[];
+}
+/**
+ * Extract Markdown mentions and bare canonical URIs from one text value.
+ * Explicit Markdown mentions fail on any malformed URI. Bare text is treated
+ * as a reference only when it has a non-empty base64url-shaped payload, then
+ * still fails if that candidate is not canonical.
+ * @param text - host text to normalize.
+ * @returns readable text and structured references in appearance order.
+ */
+export declare function parseSessionReferenceText(text: string): ParsedSessionReferenceText;
+//# sourceMappingURL=uri.d.ts.map

package/node_modules/@xrkseek/xrk-session-reference/dist/uri.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uri.d.ts","sourceRoot":"","sources":["../src/uri.ts"],"names":[],"mappings":"AAAA,yDAAyD;AAEzD,OAAO,EAAa,KAAK,SAAS,IAAI,aAAa,EAAE,MAAM,YAAY,CAAA;AAEvE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAA;AAEvD,6DAA6D;AAC7D,eAAO,MAAM,wBAAwB,iBAAiB,CAAA;AAEtD;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAG1E;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAepE;AAED;;;;GAIG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,EAAE,qBAAqB,GAAG,MAAM,CAGtF;AAED,+DAA+D;AAC/D,MAAM,WAAW,0BAA0B;IACzC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,qFAAqF;IACrF,UAAU,EAAE,qBAAqB,EAAE,CAAA;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAkBlF"}

package/node_modules/@xrkseek/xrk-session-reference/dist/uri.js

@@ -0,0 +1,81 @@
+/** Canonical session URI and inline mention encoding. */
+import { SessionId } from './types.js';
+import { SessionReferenceError } from './config.js';
+/** URI scheme reserved for XRK-Harness session snapshots. */
+export const SESSION_REFERENCE_SCHEME = 'dsh-session:';
+/**
+ * Encode any JavaScript session-id string as a canonical lossless URI.
+ * @param sessionId - opaque session id to serialize.
+ * @returns canonical `dsh-session:` URI.
+ */
+export function encodeSessionReferenceUri(sessionId) {
+    const payload = Buffer.from(JSON.stringify(sessionId), 'utf8').toString('base64url');
+    return `${SESSION_REFERENCE_SCHEME}${payload}`;
+}
+/**
+ * Decode and canonicalize one session-reference URI.
+ * @param uri - complete canonical URI.
+ * @returns decoded session id.
+ */
+export function decodeSessionReferenceUri(uri) {
+    if (!uri.startsWith(SESSION_REFERENCE_SCHEME)) {
+        throw invalidUri(uri);
+    }
+    const payload = uri.slice(SESSION_REFERENCE_SCHEME.length);
+    if (!/^[A-Za-z0-9_-]+$/.test(payload))
+        throw invalidUri(uri);
+    try {
+        const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        if (typeof parsed !== 'string')
+            throw new TypeError('decoded session id is not a string');
+        const sessionId = SessionId(parsed);
+        if (encodeSessionReferenceUri(sessionId) !== uri)
+            throw new TypeError('URI is not canonical');
+        return sessionId;
+    }
+    catch (error) {
+        throw invalidUri(uri, error);
+    }
+}
+/**
+ * Render a host-neutral Markdown mention carrying the canonical URI.
+ * @param reference - structured id and optional display label.
+ * @returns escaped `@[label](uri)` mention.
+ */
+export function formatSessionReferenceMention(reference) {
+    const label = escapeLabel(reference.label ?? reference.sessionId);
+    return `@[${label}](${encodeSessionReferenceUri(reference.sessionId)})`;
+}
+/**
+ * Extract Markdown mentions and bare canonical URIs from one text value.
+ * Explicit Markdown mentions fail on any malformed URI. Bare text is treated
+ * as a reference only when it has a non-empty base64url-shaped payload, then
+ * still fails if that candidate is not canonical.
+ * @param text - host text to normalize.
+ * @returns readable text and structured references in appearance order.
+ */
+export function parseSessionReferenceText(text) {
+    const references = [];
+    const pattern = /@\[((?:\\.|[^\\\]])*)\]\((dsh-session:[^\s)]*)\)|(dsh-session:[A-Za-z0-9_-]+)/gu;
+    const rendered = text.replace(pattern, (_match, rawLabel, markdownUri, bareUri) => {
+        const uri = markdownUri ?? bareUri;
+        /* v8 ignore next -- the two-alternative regex always captures exactly one URI group. */
+        if (uri === undefined)
+            throw new SessionReferenceError('session reference URI is missing', 'SESSION_REFERENCE_INVALID_REFERENCE');
+        const sessionId = decodeSessionReferenceUri(uri);
+        const label = rawLabel === undefined ? sessionId : unescapeLabel(rawLabel);
+        references.push({ sessionId, label });
+        return `@${label}`;
+    });
+    return { text: rendered, references };
+}
+function escapeLabel(label) {
+    return label.replace(/[\\\]]/gu, match => `\\${match}`);
+}
+function unescapeLabel(label) {
+    return label.replace(/\\(.)/gu, '$1');
+}
+function invalidUri(uri, cause) {
+    return new SessionReferenceError(`invalid session reference URI ${JSON.stringify(uri)}`, 'SESSION_REFERENCE_INVALID_REFERENCE', cause === undefined ? undefined : { cause });
+}
+//# sourceMappingURL=uri.js.map

package/node_modules/@xrkseek/xrk-session-reference/dist/uri.js.map

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

package/node_modules/@xrkseek/xrk-session-reference/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@xrkseek/xrk-session-reference",
+  "description": "Cross-session snapshot references and durable untrusted model context (ctx.sessionReferenceResolver)",
+  "version": "0.1.1-rc.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrkseek/XRK-harness.git",
+    "directory": "packages/context/session-reference"
+  },
+  "type": "module",
+  "exports": {
+    "./types": {
+      "types": "./dist/types.d.ts",
+      "import": "./dist/types.js",
+      "default": "./dist/types.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "default": "./dist/config.js"
+    },
+    "./uri": {
+      "types": "./dist/uri.d.ts",
+      "import": "./dist/uri.js",
+      "default": "./dist/uri.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README.zh.md"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@xrkseek/protocol": "workspace:*"
+  },
+  "private": true
+}

package/node_modules/detect-libc/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.