@sema-agent/core 7.54.1 → 7.55.0

package/dist/agents/agent-transcript-tool.js

@@ -7,7 +7,7 @@ import { stepsFromMessages } from "./subagent-steps.js";
 import { agentStateSourceOfRecord, agentStateSummary, formatAgo, readAgentState } from "../core/agent-state.js";
 import { REPORT_FIELD_MAX } from "./subagent.js";
 import { getSessionRetainLedger } from "./retain-ledger.js";
-import { toolFace } from "../core/tool-catalog-entries.js";
+import { mountRuleFace, toolFace } from "../core/tool-catalog-entries.js";
 import { thrownText } from "../core/thrown-value.js";
 export const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
 const AGENT_TRANSCRIPT_DEFAULT_N = 20;
@@ -25,6 +25,7 @@ export function createAgentTranscriptTool(opts) {
     return defineTool({
         name: AGENT_TRANSCRIPT_TOOL_NAME,
         ...toolFace("agent-transcript"),
+        ruleFace: mountRuleFace("agent-transcript"),
         description: `Read the recent tool steps of a background agent you launched (task_id 'a…' from the Agent tool with ` +
             `run_in_background), so you can see precisely where it got to — useful before SendMessage-ing a follow-up, ` +
             `or to inspect a stopped agent's tail. Returns the last N steps (tool, target, outcome); it does not re-run ` +

package/dist/agents/builtin-agents.d.ts

@@ -1,6 +1,6 @@
 import type { AgentDefinition } from "../core/types.js";
 /**
- * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the CC 2.1.198 BUILT-IN `Explore` and
+ * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the BUILT-IN `Explore` and
  * `Plan` agent types, ported to sema's AgentDefinition roster shape.
  *
  * Both definitions, their `whenToUse` lines and their system prompts are ported VERBATIM from the
@@ -13,10 +13,10 @@ import type { AgentDefinition } from "../core/types.js";
  * sema adaptations (deliberate, each recorded):
  *  - De-branding (prompt-sovereignty / SUBAGENT_PROMPT precedent): CC's persona first sentences name the
  *    product ("… for Claude Code, Anthropic's official CLI for Claude." / "… for Claude Code.") — sema
- *    stays provider-neutral, the brand clause is dropped; every other byte is CC-verbatim.
+ *    stays provider-neutral, the brand clause is dropped; every other byte is unchanged.
  *  - Platform arm: CC's `tbm`/`kBm` interpolate per-platform tool guidance (unix Bash vs PowerShell) and
  *    a bash-only search mode (`ww()`). sema children run in a POSIX ExecutionEnv with first-party
- *    Glob/Grep/Read/Bash under CC-identical names — the unix + Glob/Grep arm is baked verbatim
+ *    Glob/Grep/Read/Bash under the reference's names — the unix + Glob/Grep arm is baked in
  *    (Mu="Glob" :149761, Jc="Grep" :224202, Ls="Read", Lo="Bash").
  *  - `model:"inherit"` — sema shape: `model` omitted on an AgentDefinition = inherit the caller's current
  *    model (identical semantics). CC's Explore firstParty opus UPGRADE (`GAe`, 409162-409171: built-in
@@ -27,26 +27,24 @@ import type { AgentDefinition } from "../core/types.js";
  *    conflict domain at port time. Recorded as the F7 residual; the deployment `loadProjectMemory` seam
  *    already receives `isSubagent`/`agentName` and can trim today.
  *  - `disallowedTools` → `denyTools` (sema name), with the DELEGATION-tool entry tracking the deployment's
- *    actual tool name (default "Agent" = CC-verbatim). "Artifact" (mounted on the `RunnerDeps.artifactHost`
+ *    actual tool name (default "Agent"). "Artifact" (mounted on the `RunnerDeps.artifactHost`
  *    seat) and "ExitPlanMode" (present_plan's canonical name) both name first-party sema tools — the deny bites
  *    when the tool is mounted; a deny of an unmounted name is a documented no-op (tool-filter), CC byte parity.
  */
-/** CC 198 `nbm` (pretty.js:409173) — Explore `whenToUse`, verbatim. */
+/** Explore `whenToUse`. */
 export declare const EXPLORE_WHEN_TO_USE = "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis \u2014 it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.";
-/** CC 198 `rbm` (pretty.js:409174) — Explore `whenToUseLean`, verbatim. */
+/** Explore `whenToUseLean`. */
 export declare const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches \u2014 when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
-/** CC 198 Plan `whenToUse` (pretty.js:486945), verbatim (Plan has no lean variant in 198). */
+/** Plan `whenToUse` (Plan has no lean variant). */
 export declare const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
-/** CC 198 `tbm()` (pretty.js:409122-409160) — Explore persona, unix+Glob/Grep arm, first sentence de-branded. */
+/** Explore persona, unix+Glob/Grep arm, first sentence de-branded. */
 export declare const EXPLORE_SYSTEM_PROMPT = "You are a file search specialist. You excel at thoroughly navigating and exploring codebases.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYour strengths:\n- Rapidly finding files using glob patterns\n- Searching code and text with powerful regex patterns\n- Reading and analyzing file contents\n\nGuidelines:\n- Use Glob for broad file pattern matching\n- Use Grep for searching file contents with regex\n- Use Read when you know the specific file path you need to read\n- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n- Adapt your search approach based on the thoroughness level specified by the caller\n- Communicate your final report directly as a regular message - do NOT attempt to create files\n\nNOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:\n- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations\n- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files\n\nComplete the user's search request efficiently and report your findings clearly.";
-/** CC 198 `kBm()` (pretty.js:486874-486930) — Plan persona, unix arm, first sentence de-branded. */
+/** Plan persona, unix arm, first sentence de-branded. */
 export declare const PLAN_SYSTEM_PROMPT = "You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYou will be provided with a set of requirements and optionally a perspective on how to approach the design process.\n\n## Your Process\n\n1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.\n\n2. **Explore Thoroughly**:\n   - Read any files provided to you in the initial prompt\n   - Find existing patterns and conventions using Glob, Grep, and Read\n   - Understand the current architecture\n   - Identify similar features as reference\n   - Trace through relevant code paths\n   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n\n3. **Design Solution**:\n   - Create implementation approach based on your assigned perspective\n   - Consider trade-offs and architectural decisions\n   - Follow existing patterns where appropriate\n\n4. **Detail the Plan**:\n   - Provide step-by-step implementation strategy\n   - Identify dependencies and sequencing\n   - Anticipate potential challenges\n\n## Required Output\n\nEnd your response with:\n\n### Critical Files for Implementation\nList 3-5 files most critical for implementing this plan:\n- path/to/file1.ts\n- path/to/file2.ts\n- path/to/file3.ts\n\nREMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.";
 /**
- * CC 198 `disallowedTools:[is,NR,s0,xa,Ic,FR]` (pretty.js:409189 Explore / :486948 Plan) — the six-tool
- * deny set shared by both read-only built-ins, constants resolved 亲核: is="Agent"(147382),
- * NR="Artifact"(143265), s0="ExitPlanMode"(149770), xa="Edit"(143358), Ic="Write"(143375),
- * NotebookEdit FR(143373). The delegation-tool entry is parameterized on the deployment's actual tool
- * name (default = "Agent", CC-verbatim).
+ * The six-tool deny set shared by both read-only built-ins: Agent, Artifact, ExitPlanMode, Edit, Write, NotebookEdit.
+ * The delegation-tool entry is parameterized on the deployment's actual tool
+ * name (default = "Agent").
  */
 export declare const BUILTIN_READONLY_DENY_TOOLS: (delegationToolName?: string) => string[];
 /**

package/dist/agents/cc-peer-directory.d.ts

@@ -0,0 +1,36 @@
+import { type PeerDirectory, type PeerRegistryDirectoryRefusal } from "./peer-directory.js";
+/** The reference's label for a session that has no name (its listing prints it; a peer is addressed by it). */
+export declare const CC_UNNAMED_SESSION_NAME = "(unnamed session)";
+/** What the liveness judgment asks the operating system. Injectable: a test never spawns `ps`. */
+export interface CcProcessProbe {
+    /** Does a process with this pid exist (signal 0; a process this uid may not signal still exists)? */
+    processExists(pid: number): boolean;
+    /** The process start token the reference writes and compares, or `undefined` when it cannot be read
+     *  (the reference then takes the pid's word). */
+    processStartToken(pid: number): Promise<string | undefined>;
+}
+/** The reference's start token: `ps -o lstart= -p <pid>` under `LC_ALL=C TZ=UTC`, trimmed. An OPAQUE token the
+ *  reference compares for equality — never parsed into a time (the engine's own lock probe asks `etime` for that). */
+export declare function ccProcessStartToken(pid: number): Promise<string | undefined>;
+export declare const defaultCcProcessProbe: CcProcessProbe;
+/** Why one registry file was not read into the listing (closed set; reported, never thrown). */
+export type CcPeerRowSkip = "not_regular" | "foreign_owner" | "group_or_world_writable" | "too_large" | "unreadable" | "not_json" | "no_socket" | "not_live" | "invalid_row";
+/** The registry directory failed its vetting: the listing refuses instead of answering empty. */
+export declare class CcPeerDirectoryError extends Error {
+    readonly code: PeerRegistryDirectoryRefusal;
+    readonly path: string;
+    constructor(code: PeerRegistryDirectoryRefusal, path: string);
+}
+export interface CcPeerDirectoryOptions {
+    /** The reference's registry directory (`ccPeerDefaultLocations().registryDir`). */
+    registryDir: string;
+    /** The scope every row of this registry belongs to (the reference is single-user). Default `"default"`. */
+    scope?: string;
+    probe?: CcProcessProbe;
+    /** One call per skipped file. */
+    onSkip?: (file: string, reason: CcPeerRowSkip, detail?: string) => void;
+    /** Tests: the uid / platform the vetting and the file judgment use. */
+    uid?: number;
+    platform?: NodeJS.Platform;
+}
+export declare function createCcPeerDirectory(opts: CcPeerDirectoryOptions): PeerDirectory;

package/dist/agents/cc-peer-directory.js

@@ -0,0 +1,138 @@
+import { execFile } from "node:child_process";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { normalizePeerName } from "./cross-session-ref.js";
+import { inheritedHostEnv } from "../core/secret-env.js";
+import { CC_PEER_ROW_FILE_RE } from "./cc-peer-wire.js";
+import { judgePeerRecordFile, PEER_PRESENCE_MAX_CHARS, PEER_SESSION_RECORD_SCHEMA_VERSION, readPeerSessionRecord, vetPeerRegistryDirectory, } from "./peer-directory.js";
+export const CC_UNNAMED_SESSION_NAME = "(unnamed session)";
+export function ccProcessStartToken(pid) {
+    if (process.platform === "win32" || !Number.isInteger(pid) || pid <= 0)
+        return Promise.resolve(undefined);
+    return new Promise((resolve) => {
+        execFile("ps", ["-o", "lstart=", "-p", String(pid)], { timeout: 1_000, env: { ...inheritedHostEnv("scrub"), LC_ALL: "C", TZ: "UTC" } }, (err, stdout) => {
+            const token = err === null ? String(stdout).trim() : "";
+            resolve(token === "" ? undefined : token);
+        });
+    });
+}
+export const defaultCcProcessProbe = {
+    processExists(pid) {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (e) {
+            return e.code === "EPERM";
+        }
+    },
+    processStartToken: ccProcessStartToken,
+};
+export class CcPeerDirectoryError extends Error {
+    code;
+    path;
+    constructor(code, path) {
+        super(`the reference agent's session registry is not a directory this engine can trust (${code}: ${path}) — nothing was listed`);
+        this.name = "CcPeerDirectoryError";
+        this.code = code;
+        this.path = path;
+    }
+}
+const FEATURE_RE = /^[a-z0-9_]{1,32}$/;
+const MAX_FEATURES = 16;
+export function createCcPeerDirectory(opts) {
+    const scope = opts.scope ?? "default";
+    const probe = opts.probe ?? defaultCcProcessProbe;
+    const selfUid = opts.uid ?? (typeof process.getuid === "function" ? process.getuid() : undefined);
+    const skip = (file, reason, detail) => {
+        try {
+            opts.onSkip?.(file, reason, detail);
+        }
+        catch {
+        }
+    };
+    const readRow = async (file, pid) => {
+        const path = join(opts.registryDir, file);
+        let text;
+        try {
+            const st = await lstat(path);
+            const judged = judgePeerRecordFile({ uid: st.uid, mode: st.mode, isFile: st.isFile(), size: st.size }, selfUid, opts.platform);
+            if (!judged.ok)
+                return void skip(file, judged.code);
+            text = await readFile(path, "utf8");
+        }
+        catch (e) {
+            return void skip(file, "unreadable", e.code);
+        }
+        let row;
+        try {
+            row = JSON.parse(text);
+        }
+        catch {
+            return void skip(file, "not_json");
+        }
+        if (row === null || typeof row !== "object" || Array.isArray(row))
+            return void skip(file, "invalid_row", "not an object");
+        const r = row;
+        const sockPath = r["messagingSocketPath"];
+        if (typeof sockPath !== "string" || sockPath === "")
+            return void skip(file, "no_socket");
+        if (!probe.processExists(pid))
+            return void skip(file, "not_live", "no such process");
+        const procStart = typeof r["procStart"] === "string" ? r["procStart"] : undefined;
+        if (procStart !== undefined) {
+            const now = await probe.processStartToken(pid);
+            if (now !== undefined && now !== procStart)
+                return void skip(file, "not_live", "the pid belongs to another process now");
+        }
+        const finite = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? v : undefined);
+        const startedAt = finite(r["startedAt"]) ?? 0;
+        const name = typeof r["name"] === "string" && normalizePeerName(r["name"]) !== "" ? r["name"] : CC_UNNAMED_SESSION_NAME;
+        const features = Array.isArray(r["peerFeatures"]) ? r["peerFeatures"].filter((f) => typeof f === "string" && FEATURE_RE.test(f)).slice(0, MAX_FEATURES) : undefined;
+        const tempo = r["tempo"];
+        const agent = typeof r["agent"] === "string" && r["agent"].length <= PEER_PRESENCE_MAX_CHARS ? r["agent"] : undefined;
+        const read = readPeerSessionRecord({
+            schemaVersion: PEER_SESSION_RECORD_SCHEMA_VERSION,
+            sessionId: r["sessionId"],
+            scope,
+            name,
+            pid,
+            ...(typeof r["cwd"] === "string" ? { cwd: r["cwd"] } : {}),
+            startedAt,
+            updatedAt: finite(r["updatedAt"]) ?? startedAt,
+            liveness: "live",
+            ...(tempo === "active" || tempo === "idle" || tempo === "blocked" ? { tempo } : {}),
+            ...(agent !== undefined ? { agent } : {}),
+            ...(typeof r["entrypoint"] === "string" ? { entrypoint: r["entrypoint"] } : {}),
+            ...(typeof r["peerProtocol"] === "number" ? { peerProtocol: r["peerProtocol"] } : {}),
+            ...(features !== undefined ? { peerFeatures: features } : {}),
+            sockPath,
+        });
+        if (!read.ok)
+            return void skip(file, "invalid_row", read.field !== undefined ? `${read.reason}: ${read.field}` : read.reason);
+        return read.record;
+    };
+    return {
+        async listPeerSessions(access) {
+            if (access.scope !== scope)
+                return [];
+            const verdict = await vetPeerRegistryDirectory(opts.registryDir, { ...(selfUid !== undefined ? { uid: selfUid } : {}), ...(opts.platform !== undefined ? { platform: opts.platform } : {}) });
+            if (!verdict.ok)
+                throw new CcPeerDirectoryError(verdict.code, verdict.path);
+            const names = await readdir(opts.registryDir);
+            const rows = [];
+            for (const file of names.sort()) {
+                const m = CC_PEER_ROW_FILE_RE.exec(file);
+                if (m === null)
+                    continue;
+                const pid = Number.parseInt(m[1], 10);
+                if (String(pid) !== m[1] || pid <= 0)
+                    continue;
+                const record = await readRow(file, pid);
+                if (record !== undefined)
+                    rows.push(record);
+            }
+            return rows;
+        },
+    };
+}

package/dist/agents/cc-peer-wire.d.ts

@@ -0,0 +1,105 @@
+import { type CcPeerFrameFields } from "./cross-session-envelope.js";
+/** CC `z8t` — a line longer than this (characters, before its newline) drops the connection. */
+export declare const CC_PEER_LINE_MAX_CHARS = 1048576;
+/** CC `f9n` — a connection with no complete line within this is closed. */
+export declare const CC_PEER_FIRST_LINE_DEADLINE_MS = 30000;
+/** CC's sender socket timeout. */
+export declare const CC_PEER_SEND_TIMEOUT_MS = 5000;
+/** CC `z` — the socket path wall (bytes) of `sun_path`. */
+export declare const CC_PEER_SOCKET_PATH_MAX_BYTES = 103;
+/** CC — the read cap of one key file. */
+export declare const CC_PEER_KEY_FILE_MAX_BYTES = 4096;
+/** CC `$vr` — the registration row's protocol word. */
+export declare const CC_PEER_PROTOCOL = 1;
+/** CC `msgV`. */
+export declare const CC_PEER_MESSAGE_VERSION = 1;
+/** CC `C` — a peer token is 16 random bytes, spelled as 32 lowercase hex. */
+export declare const CC_PEER_TOKEN_RE: RegExp;
+/** CC `xjn` — a published key file: `<pid>.<sha256 of the socket path>.key`. */
+export declare const CC_PEER_KEY_FILE_RE: RegExp;
+/** CC — a registration row file is `<pid>.json`, the pid spelled canonically. */
+export declare const CC_PEER_ROW_FILE_RE: RegExp;
+/** This engine's doorbell action. */
+export declare const CC_PEER_NUDGE_ACTION = "mailbox_nudge";
+/** The hash a key file is named by: sha-256 of the socket's resolved path (CC `Z`). */
+export declare function ccPeerSocketDigest(socketPath: string): string;
+/** The key file name a process publishes for the socket it listens on. */
+export declare function ccPeerKeyFileName(pid: number, socketPath: string): string;
+/** The address a frame names its sender by (CC `aV`): `uds:` + the percent-encoded socket path. */
+export declare function ccPeerAddress(socketPath: string): string;
+/**
+ * Where the reference agent puts its socket and its session registry (CC 2.1.296, `XDG_RUNTIME_DIR` (cli296.js:274840)): the socket at
+ * `${XDG_RUNTIME_DIR || CLAUDE_CODE_TMPDIR || /tmp}/cc-socks/<pid>.sock`, falling back to
+ * `/tmp/cc-socks-<uid>/<pid>.sock` when that path is past the `sun_path` wall; the registry at
+ * `${CLAUDE_CONFIG_DIR || ~/.claude}/sessions`. Pure: the caller hands in the environment it means.
+ */
+export declare function ccPeerDefaultLocations(args: {
+    env: Readonly<Record<string, string | undefined>>;
+    homedir: string;
+    pid: number;
+    uid?: number;
+}): {
+    socketPath: string;
+    registryDir: string;
+};
+/** The auth line (CC `Gbo`). */
+export declare function encodeCcAuthLine(token: string): string;
+/** One message line (CC's sender frame, key order as the reference writes it). `fields` and `body` go
+ *  through the envelope text codec; `from` is the sender's own address. */
+export declare function encodeCcUserLine(args: {
+    fields: CcPeerFrameFields;
+    body: string;
+    from?: string;
+    msgId?: string;
+}): string;
+/** The doorbell line: a control frame that carries nothing — no content, no sender (the record in the box says who). */
+export declare function encodeCcNudgeLine(args?: {
+    msgId?: string;
+}): string;
+/** What one wire line is. `toSession` on a message: absent = unaddressed; `null` = present but not a
+ *  string (never equal to any session id). */
+export type CcPeerLine = {
+    kind: "auth";
+    token: string | undefined;
+} | {
+    kind: "user";
+    content: string;
+    from?: string;
+    toSession?: string | null;
+    attachments: boolean;
+} | {
+    kind: "nudge";
+} | {
+    kind: "unhandled";
+    type: string;
+    action?: string;
+} | {
+    kind: "malformed";
+    why: string;
+};
+/** The ONE reader of an untyped wire value (a parsed JSON line). */
+export declare function readCcPeerLine(value: unknown): CcPeerLine;
+/** Parse one line of text; a line that is not JSON is `malformed`. */
+export declare function parseCcPeerLine(line: string): CcPeerLine;
+/** The facts a session of this engine publishes in the reference agent's registry. */
+export interface CcRegistrationFacts {
+    pid: number;
+    sessionId: string;
+    socketPath: string;
+    startedAt: number;
+    updatedAt: number;
+    cwd?: string;
+    name?: string;
+    entrypoint?: string;
+    /** The process start token the reference reads (`ps -o lstart=`, C locale, UTC). Absent = the reference
+     *  judges the row by its pid alone. */
+    procStart?: string;
+    /** The identity of the mailbox store this session drains (`MailboxStore.identity`). Absent = the store cannot
+     *  say, and the row then carries no capability bit: every sender reaches this session over its socket. */
+    storeIdentity?: string;
+}
+/** The registration row this engine writes into the reference agent's registry (`<pid>.json`): the
+ *  reference's field names, the protocol word, and the capability broadcast — `peerFeatures` carries the one
+ *  bit naming the store this session drains ({@link semaMailboxFeature}) and nothing else (this engine takes
+ *  none of the reference's socket features: idle subscriptions and artifact yields travel through the box). */
+export declare function ccRegistrationRow(facts: CcRegistrationFacts): Record<string, unknown>;

package/dist/agents/cc-peer-wire.js

@@ -0,0 +1,98 @@
+import { createHash, randomUUID } from "node:crypto";
+import { join, resolve as resolvePath } from "node:path";
+import { encodeCcPeerFrame, encodePeerAddress } from "./cross-session-envelope.js";
+import { semaMailboxFeature } from "./peer-directory.js";
+export const CC_PEER_LINE_MAX_CHARS = 1_048_576;
+export const CC_PEER_FIRST_LINE_DEADLINE_MS = 30_000;
+export const CC_PEER_SEND_TIMEOUT_MS = 5_000;
+export const CC_PEER_SOCKET_PATH_MAX_BYTES = 103;
+export const CC_PEER_KEY_FILE_MAX_BYTES = 4_096;
+export const CC_PEER_PROTOCOL = 1;
+export const CC_PEER_MESSAGE_VERSION = 1;
+export const CC_PEER_TOKEN_RE = /^[0-9a-f]{32}$/;
+export const CC_PEER_KEY_FILE_RE = /^(\d+)\.([0-9a-f]{64})\.key$/;
+export const CC_PEER_ROW_FILE_RE = /^(\d+)\.json$/;
+export const CC_PEER_NUDGE_ACTION = "mailbox_nudge";
+export function ccPeerSocketDigest(socketPath) {
+    return createHash("sha256").update(resolvePath(socketPath)).digest("hex");
+}
+export function ccPeerKeyFileName(pid, socketPath) {
+    return `${pid}.${ccPeerSocketDigest(socketPath)}.key`;
+}
+export function ccPeerAddress(socketPath) {
+    return encodePeerAddress(`uds:${socketPath}`);
+}
+export function ccPeerDefaultLocations(args) {
+    const base = args.env["XDG_RUNTIME_DIR"] || args.env["CLAUDE_CODE_TMPDIR"] || "/tmp";
+    const primary = resolvePath(base, "cc-socks", `${args.pid}.sock`);
+    const socketPath = Buffer.byteLength(primary) <= CC_PEER_SOCKET_PATH_MAX_BYTES ? primary : join("/tmp", `cc-socks-${args.uid ?? 0}`, `${args.pid}.sock`);
+    const registryDir = resolvePath(args.env["CLAUDE_CONFIG_DIR"] || join(args.homedir, ".claude"), "sessions");
+    return { socketPath, registryDir };
+}
+export function encodeCcAuthLine(token) {
+    return `${JSON.stringify({ type: "auth", token })}\n`;
+}
+export function encodeCcUserLine(args) {
+    const content = encodeCcPeerFrame(args.fields, args.body);
+    return `${JSON.stringify({ msgV: CC_PEER_MESSAGE_VERSION, msg_id: args.msgId ?? randomUUID(), type: "user", message: { role: "user", content }, priority: "next", ...(args.from !== undefined ? { from: args.from } : {}) })}\n`;
+}
+export function encodeCcNudgeLine(args = {}) {
+    return `${JSON.stringify({ type: "control", action: CC_PEER_NUDGE_ACTION, msgV: CC_PEER_MESSAGE_VERSION, msg_id: args.msgId ?? randomUUID() })}\n`;
+}
+export function readCcPeerLine(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return { kind: "malformed", why: "not an object" };
+    const v = value;
+    const type = v["type"];
+    if (typeof type !== "string")
+        return { kind: "malformed", why: "no type" };
+    if (type === "auth")
+        return { kind: "auth", token: typeof v["token"] === "string" ? v["token"] : undefined };
+    if (type === "user") {
+        const message = v["message"];
+        const content = message !== null && typeof message === "object" && !Array.isArray(message) ? message["content"] : undefined;
+        if (typeof content !== "string" || content.length === 0)
+            return { kind: "malformed", why: "user frame without text content" };
+        const rawTo = v["session_id"];
+        return {
+            kind: "user",
+            content,
+            ...(typeof v["from"] === "string" ? { from: v["from"] } : {}),
+            ...(rawTo !== undefined ? { toSession: typeof rawTo === "string" ? rawTo : null } : {}),
+            attachments: v["file_attachments"] !== undefined,
+        };
+    }
+    if (type === "control") {
+        const action = v["action"];
+        if (action === CC_PEER_NUDGE_ACTION)
+            return { kind: "nudge" };
+        return { kind: "unhandled", type, ...(typeof action === "string" ? { action } : {}) };
+    }
+    return { kind: "unhandled", type };
+}
+export function parseCcPeerLine(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return { kind: "malformed", why: "not JSON" };
+    }
+    return readCcPeerLine(value);
+}
+export function ccRegistrationRow(facts) {
+    return {
+        pid: facts.pid,
+        sessionId: facts.sessionId,
+        ...(facts.cwd !== undefined ? { cwd: facts.cwd } : {}),
+        startedAt: facts.startedAt,
+        ...(facts.procStart !== undefined ? { procStart: facts.procStart } : {}),
+        kind: "interactive",
+        ...(facts.entrypoint !== undefined ? { entrypoint: facts.entrypoint } : {}),
+        peerProtocol: CC_PEER_PROTOCOL,
+        peerFeatures: facts.storeIdentity !== undefined && facts.storeIdentity !== "" ? [semaMailboxFeature(facts.storeIdentity)] : [],
+        messagingSocketPath: facts.socketPath,
+        ...(facts.name !== undefined ? { name: facts.name } : {}),
+        updatedAt: facts.updatedAt,
+    };
+}

package/dist/agents/cc-uds-peer-channel.d.ts

@@ -0,0 +1,40 @@
+import type { MailboxStore } from "../core/mailbox-store.js";
+import type { PeerChannel } from "../core/peer-channel.js";
+import { type PeerLaneConfig } from "./peer-admission.js";
+import { type PeerRegistryDirectoryRefusal } from "./peer-directory.js";
+import { type CcProcessProbe } from "./cc-peer-directory.js";
+/** Why `listen` refused to bind (closed set): one of the directory-vetting codes, or one of these. */
+export type CcPeerChannelRefusal = PeerRegistryDirectoryRefusal | "unsupported_platform" | "socket_path_too_long" | "address_in_use" | "already_listening" | "publish_failed";
+export declare class CcPeerChannelError extends Error {
+    readonly code: CcPeerChannelRefusal;
+    readonly path?: string;
+    constructor(code: CcPeerChannelRefusal, message: string, path?: string);
+}
+export interface CcUdsPeerChannelOptions {
+    /** The store this session's box lives in (inbound frames are appended here). */
+    mailbox: MailboxStore;
+    /** Where `listen` binds (`ccPeerDefaultLocations().socketPath` puts it beside the reference's own). */
+    socketPath: string;
+    /** The reference's session registry (`ccPeerDefaultLocations().registryDir`): `listen` publishes this
+     *  session's key file and row there; `dial` / `nudge` read a peer's key there. */
+    registryDir: string;
+    /** The peer lane's knob table (`RunnerDeps.peerLane`): `maxQueuedPeerMessages` bounds inbound appends. */
+    lane?: Partial<PeerLaneConfig>;
+    /** What this session's registry row says about it beyond its ids. */
+    registration?: {
+        name?: string;
+        cwd?: string;
+        startedAt?: number;
+        entrypoint?: string;
+    };
+    /** Tests: this process's pid, the start-token reader, the clocks and walls, the uid / platform. */
+    pid?: number;
+    probe?: Pick<CcProcessProbe, "processStartToken" | "processExists">;
+    now?: () => number;
+    firstLineDeadlineMs?: number;
+    sendTimeoutMs?: number;
+    nudgeTimeoutMs?: number;
+    uid?: number;
+    platform?: NodeJS.Platform;
+}
+export declare function createCcUdsPeerChannel(opts: CcUdsPeerChannelOptions): PeerChannel;