@qodeca/xezar 0.13.1 → 0.14.0

package/dist/mcp/ipc.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { mcpProjectOccupiedErrorSchema, mcpSessionExpiredErrorSchema } from '../contract/index.js';
+import { z } from 'zod';
+import { xezarHomeDir } from '../paths.js';
+/**
+ * The IPC leg between `xez mcp` (the bridge) and the running xezar service — D-01
+ * (docs/features/mcp-server/mcp-d01-transport-decision.md) § 1.2–1.5.
+ *
+ * One Unix domain socket per registered project, owned by the service, at
+ * `<xezarHomeDir()>/ipc/<projectId>.sock` (dir 0700, socket 0600). Frames are
+ * newline-delimited JSON, the same framing as the stdio leg. The socket IS the
+ * project binding (§ 1.5): no frame carries a project field, and the service answers
+ * only for the project it opened the socket for.
+ *
+ * Both sides import this file, so the path rule and the frame shapes cannot drift.
+ * They may still come from different installed versions (`npx` vs a global
+ * install), which is what `IPC_PROTOCOL_VERSION` is for.
+ */
+/**
+ * Bumped only when a frame shape changes incompatibly. Carried on every request.
+ *
+ * 2 (#302): a connection is a SESSION. The bridge keeps one connection for its whole life, opens
+ * the session on it with `session/open` (which acquires the project's owner slot, D-02), and every
+ * `health` / `tools/call` needs that live session. A version-1 bridge — one connection per call,
+ * no session — would be refused on every call anyway; the version check refuses it legibly first.
+ */
+export const IPC_PROTOCOL_VERSION = 2;
+/**
+ * Largest frame either leg accepts, in bytes: 32 MiB + 64 KiB. Taken from D-09 B-08
+ * (qodeca/xezar#206, not yet merged at the time of writing) so the bridge does not
+ * invent a second number. A larger frame is refused with an explicit error and
+ * closes nothing else.
+ */
+export const MAX_FRAME_BYTES = 33_619_968;
+/**
+ * How long the bridge waits for the service to answer one request — D-09 B-09
+ * (qodeca/xezar#206): 55 s. On expiry the bridge answers with a readable result;
+ * the service operation is not cancelled. There is no retry (D-01 § 5, D-09 B-16).
+ */
+export const IPC_REQUEST_TIMEOUT_MS = 55_000;
+/**
+ * How long the bridge waits to connect and open its session. Acquisition itself is bounded far
+ * below this (D-02.2: 5 attempts, at most 375 ms of backoff), so only a hung service reaches it.
+ * It is short because `initialize` waits on it, and a client gives up on a server whose handshake
+ * is slow — Codex's documented default startup timeout is 10 s (not re-measured here). On expiry
+ * the handshake still succeeds with no session (N-07) and the next call tries again.
+ */
+export const IPC_SESSION_OPEN_TIMEOUT_MS = 5_000;
+// ---- socket path ---------------------------------------------------------------
+/**
+ * The longest socket path the OS accepts, in bytes. An operating-system constant
+ * (`sun_path`), not a xezar choice: macOS/BSD measured 104 OK and 105 EINVAL
+ * (D-01 E5); Linux reserves 108 bytes including the terminating NUL.
+ */
+function maxSocketPathBytes(platform) {
+    return platform === 'linux' ? 107 : 104;
+}
+/**
+ * Where the service listens for `projectId`, and where the bridge connects. Pure:
+ * both sides compute it from the same registry entry, so they always agree.
+ *
+ * D-01 § 1.4: when `<home>/ipc/<projectId>.sock` is longer than the OS allows, the
+ * first 12 hex characters of SHA-256(project root) replace the id. When even that
+ * is too long (a very long `XEZ_HOME`), there is no socket — the caller degrades.
+ * Windows named pipes are untested and their naming is undecided (D-01 § 10.2), so
+ * Windows is reported as unavailable rather than guessed.
+ */
+export function mcpSocketLocation(project, env = process.env, platform = process.platform) {
+    if (platform === 'win32') {
+        return { kind: 'unavailable', reason: 'the xezar MCP bridge is not supported on Windows yet' };
+    }
+    const dir = mcpSocketDir(env);
+    const limit = maxSocketPathBytes(platform);
+    const primary = join(dir, `${project.id}.sock`);
+    if (Buffer.byteLength(primary) <= limit)
+        return { kind: 'socket', path: primary };
+    const hashed = join(dir, `${createHash('sha256').update(project.root).digest('hex').slice(0, 12)}.sock`);
+    if (Buffer.byteLength(hashed) <= limit)
+        return { kind: 'socket', path: hashed };
+    return {
+        kind: 'unavailable',
+        reason: `the xezar home path is too long for a local socket on this system (limit ${limit} bytes) — point XEZ_HOME at a shorter directory`,
+    };
+}
+/** `<xezarHomeDir()>/ipc` — the only directory the service creates for MCP. */
+export function mcpSocketDir(env = process.env) {
+    return join(xezarHomeDir(env), 'ipc');
+}
+// ---- frames --------------------------------------------------------------------
+/** A tool result exactly as MCP carries it: the text block is authoritative. */
+export const toolResultSchema = z.object({
+    content: z.array(z.object({ type: z.literal('text'), text: z.string() })),
+    structuredContent: z.record(z.string(), z.unknown()).optional(),
+    isError: z.boolean().optional(),
+});
+/** What `health` answers. No account identity and no path — F-12, N-01, F-15. */
+export const healthResultSchema = z.object({
+    ipcVersion: z.number().int(),
+    xezarVersion: z.string().max(64),
+    project: z.object({ id: z.string().max(64), name: z.string().max(200) }),
+});
+export const toolCallParamsSchema = z.object({
+    name: z.string().min(1).max(128),
+    arguments: z.record(z.string(), z.unknown()).optional(),
+});
+/**
+ * Bridge → service. `v` is checked BEFORE the method is looked at, so a service
+ * can refuse a bridge from another protocol version legibly. `bridgeVersion` is the
+ * bridge's xezar version, for diagnostics only.
+ */
+export const ipcRequestSchema = z.object({
+    v: z.number().int(),
+    id: z.number().int().nonnegative(),
+    bridgeVersion: z.string().max(64).optional(),
+    method: z.string().min(1).max(64),
+    params: z.unknown().optional(),
+});
+export const ipcErrorCodeSchema = z.enum([
+    'bad-frame',
+    'version-mismatch',
+    'unknown-method',
+    'invalid-params',
+    'unknown-tool',
+    'internal',
+    /** `session/open` while another session owns the project (D-02 § 4, `-32080`). */
+    'project-occupied',
+    /** A call on a connection whose session does not own the project (D-02 § 4, `-32081`). */
+    'session-expired',
+]);
+/**
+ * The JSON-RPC error the bridge hands the client verbatim for the two ownership refusals. The
+ * contract's schemas are `.strict()`, so nothing about the competing owner can ride along (N-01).
+ */
+export const ownershipRpcErrorSchema = z.union([mcpProjectOccupiedErrorSchema, mcpSessionExpiredErrorSchema]);
+/** What `session/open` answers: this connection's session now owns the project. */
+export const sessionOpenResultSchema = z.object({ owner: z.literal(true) });
+/** Service → bridge. */
+export const ipcResponseSchema = z.discriminatedUnion('ok', [
+    z.object({ v: z.number().int(), id: z.number().int().nullable(), ok: z.literal(true), result: z.unknown() }),
+    z.object({
+        v: z.number().int(),
+        id: z.number().int().nullable(),
+        ok: z.literal(false),
+        error: z.object({ code: ipcErrorCodeSchema, message: z.string().max(2000) }),
+        /** The service's xezar version, so a mismatch message can name both sides. */
+        serviceVersion: z.string().max(64).optional(),
+        /** Only on `project-occupied` / `session-expired`: the D-02 § 4 error the client receives. */
+        rpcError: ownershipRpcErrorSchema.optional(),
+    }),
+]);
+// ---- framing -------------------------------------------------------------------
+/**
+ * Split a byte stream into newline-delimited frames. A frame over `maxBytes` is
+ * reported once through `onOversize` and skipped up to its newline; the stream
+ * keeps working (D-09 B-08: "closes nothing else").
+ */
+export class LineFramer {
+    onFrame;
+    onOversize;
+    maxBytes;
+    chunks = [];
+    size = 0;
+    discarding = false;
+    constructor(onFrame, onOversize, maxBytes = MAX_FRAME_BYTES) {
+        this.onFrame = onFrame;
+        this.onOversize = onOversize;
+        this.maxBytes = maxBytes;
+    }
+    push(chunk) {
+        let start = 0;
+        for (let nl = chunk.indexOf(0x0a, start); nl !== -1; nl = chunk.indexOf(0x0a, start)) {
+            this.append(chunk.subarray(start, nl));
+            this.flushFrame();
+            start = nl + 1;
+        }
+        this.append(chunk.subarray(start));
+    }
+    append(part) {
+        if (this.discarding || part.length === 0)
+            return;
+        if (this.size + part.length > this.maxBytes) {
+            this.chunks = [];
+            this.size = 0;
+            this.discarding = true;
+            this.onOversize();
+            return;
+        }
+        this.chunks.push(part);
+        this.size += part.length;
+    }
+    flushFrame() {
+        const wasDiscarding = this.discarding;
+        const line = Buffer.concat(this.chunks, this.size).toString('utf8').replace(/\r$/, '');
+        this.chunks = [];
+        this.size = 0;
+        this.discarding = false;
+        if (!wasDiscarding && line.trim() !== '')
+            this.onFrame(line);
+    }
+}
+/** One frame on the wire. `JSON.stringify` never emits a raw newline. */
+export function encodeFrame(value) {
+    return `${JSON.stringify(value)}\n`;
+}
+//# sourceMappingURL=ipc.js.map

package/dist/mcp/ipc.js.map

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

package/dist/mcp/leader-delivery.d.ts

@@ -0,0 +1,119 @@
+import type { McpLeaderActionInput, McpLeaderStatus } from '../contract/index.js';
+import type { ProjectOwnership } from '../workspace/project-owner.ts';
+import { type PiLeaderDescriptor, type PiLeaderLink, readPiLeaderDescriptor } from './adapters/pi-link.ts';
+import type { EchoGuard } from './echo-guard.ts';
+import { type DeliveryReceipt, type EventDispatch, type LeaderRecord, type ReactionAdapter } from './event-controller.ts';
+import type { EventJournal } from './event-journal.ts';
+import type { LeaderActResult, ProjectLeaderPort } from './project-leaders.ts';
+/**
+ * Push delivery, connected (#309, Phase 6 of #73). Until this module, `EventController` (#107) and
+ * the reaction adapters (#108–#110) were complete, tested — and constructed by nothing outside their
+ * own tests, so no event ever reached a client. This is the one place the running service builds
+ * the controller, composed once per project by `startMcpService`.
+ *
+ * WHAT IS ON BY DEFAULT. Every MCP session that becomes the project's owner (`session/open`,
+ * D-02.2) gets an event controller at once, with this object as its adapter; the controller ends
+ * when that session's connection closes (D-02.4). No flag, no setting: an owner session always has
+ * a dispatcher following the journal for it.
+ *
+ * WHO IT CAN REACH, AND WHY ONLY THEM. A dispatch must reach a MODEL, and generic MCP notifications
+ * start no turn in Claude Code, Codex, OpenCode or pi (D-05 § 4; #330 run A for pi; each adapter's
+ * evidence record). xezar NEVER starts an agent process for a leader (owner decision on #311): the
+ * person runs their own leader and connects it to xezar over MCP. So an event reaches a model only
+ * through a session the person runs AND tells xezar where to find — `attach`. Two clients can be
+ * told today:
+ *
+ *  - **OpenCode** names an `opencode serve` session by URL and session id (#110).
+ *  - **pi** names nothing, because it cannot: pi's RPC is stdio-only and spawn-only, so a pi the
+ *    person started has no address. The address therefore comes from INSIDE it — xezar's pi leader
+ *    extension opens a socket and announces it in the project's data directory, and `#piTarget()`
+ *    dials that (#330 WP2, `adapters/pi-link.ts`). With no extension running there is no descriptor
+ *    and the attach is refused with pi's own recoverable reason, which is exactly the behaviour that
+ *    existed before the extension did.
+ *
+ * A Claude Code or Codex session in a terminal still has no address at all: for it the controller
+ * keeps the rows in the journal, reports `disconnected`, retries at its heartbeat, and
+ * `status().blocker` says so. Nothing is lost either way — such a leader reads its events with the
+ * `leader_events` tool (#251), and the next session resumes after its last acknowledgement.
+ *
+ * THE ECHO GUARD HOLDS HERE, FOR EVERY CLIENT. The door records each mutation's operation id as the
+ * leader's own before it runs (`EchoGuard.issue`, #106), including the ids it mints for tools that
+ * carry no `operationId`. A `leader` row caused by one of them is dropped before the adapter sees it,
+ * so a client's own guard — which knows only the ids it saw — cannot miss a door-minted one. Only the
+ * echo rule: the guard's `duplicate` rule must NOT be applied, because redelivery after a reconnect
+ * is at-least-once by contract.
+ *
+ * ## Every state this relies on, and who fires each exit
+ *
+ * Controller states (`EventControllerState`), as wired here:
+ *
+ * | State | Exit | Who fires it (on by default) |
+ * | --- | --- | --- |
+ * | inert | — | never entered: this object is always the adapter |
+ * | idle | → dispatching | a journal append, or the 30 s heartbeat tick |
+ * | dispatching | → idle / → recovering | `deliver` resolving / rejecting or timing out (one heartbeat) |
+ * | recovering | → idle / → disconnected | the bounded round itself (5 attempts) |
+ * | disconnected | → dispatching | the heartbeat tick, every 30 s; or `wake()`, which `attach` fires at once |
+ * | any | → ended | the session's connection closing (`sessionClosed`), another session taking the project (`sessionOpened`), the lease lapsing (found at the next tick), or the service closing |
+ *
+ * `disconnected` with nothing attached is the one state that waits on something outside xezar, and
+ * it does not wait on a human alone: the heartbeat retries it for as long as the session owns the
+ * project, at no model cost (N-06). It is the recoverable blocker the requirements ask for.
+ *
+ * Leader states: none → attached (`act` attach); attached → none (`act` stop, or the service
+ * closing). An attached OpenCode session that goes away is the adapter's own recoverable blocker,
+ * reported by `status()`; the controller retries it at the heartbeat. A pi leader that goes away
+ * takes its socket with it, which closes the link and reports the same way.
+ *
+ * What xezar OPENS to reach a leader is released on every one of those exits: `#detach` closes the
+ * adapter and then its `dispose` (pi's socket today), and `close()` goes through `#detach`.
+ *
+ * What reaches a terminal state BECAUSE of this module: its controllers. No process, run, lease,
+ * queue slot or worktree — it starts nothing and stops nothing but its own objects.
+ */
+/** xezar's base role, sent with every event to an attached leader. Per-project customisation is not built yet. */
+export declare const LEADER_ROLE_INSTRUCTION: string;
+export interface LeaderDeliveryOptions {
+    readonly projectId: string;
+    readonly projectRoot: string;
+    readonly journal: EventJournal;
+    readonly ownership: Pick<ProjectOwnership, 'projectId' | 'sessionToken' | 'state'>;
+    /** The door's echo guard. Absent (it could not be built): no row is dropped as an echo. */
+    readonly guard: Pick<EchoGuard, 'isOwn'> | undefined;
+    /**
+     * The leader's acknowledgement record (`LeaderCursors`, #251) — the ONE acknowledgement the
+     * controller resumes by, filters by and reports (#332). Absent: the controller's own.
+     */
+    readonly leaderRecord?: LeaderRecord;
+    readonly warn: (message: string) => void;
+    /** Test seam. Production uses the controller's 30 s. */
+    readonly heartbeatMs?: number;
+    /**
+     * Where this project's state lives, for the pi leader descriptor (`adapters/pi-link.ts`). Absent
+     * it is DERIVED from `projectRoot`, which is what the service already does, so nothing upstream
+     * has to pass it for pi attach to work. A store with a relocated `dataDir` may pass its own.
+     */
+    readonly dataDir?: string;
+    /** Test seams for the pi link, so a case never touches a real socket. Production uses the module. */
+    readonly piLeader?: {
+        read?: (dataDir: string) => ReturnType<typeof readPiLeaderDescriptor>;
+        connect?: (descriptor: PiLeaderDescriptor, opts: {
+            warn?: (message: string) => void;
+        }) => PiLeaderLink;
+    };
+}
+export declare class LeaderDelivery implements ReactionAdapter, ProjectLeaderPort {
+    #private;
+    readonly projectId: string;
+    constructor(opts: LeaderDeliveryOptions);
+    /** `session/open` made `sessionKey` the owner. Never throws into the transport (N-07). */
+    sessionOpened(sessionKey: string): void;
+    /** The session's connection closed (D-02.4): its controller ends. The journal keeps every row. */
+    sessionClosed(sessionKey: string): void;
+    deliver(dispatch: EventDispatch, signal: AbortSignal): Promise<DeliveryReceipt>;
+    heartbeat(signal: AbortSignal): Promise<void>;
+    status(): McpLeaderStatus;
+    act(input: McpLeaderActionInput): Promise<LeaderActResult>;
+    /** The service is stopping: every controller ends and the attached session is let go. */
+    close(): void;
+}