@qodeca/xezar 0.13.0 → 0.14.0

package/dist/contract/mcp-api-reference.d.ts

@@ -0,0 +1,174 @@
+import { z } from 'zod';
+/**
+ * #284 — the MCP API reference the cockpit browses (`GET /api/v1/mcp/reference`), spec
+ * `docs/features/mcp-api-reference/mcp-api-reference-spec.md` § 11.
+ *
+ * READ-ONLY BY DESIGN. Nothing in this shape can run a tool, and nothing may be added that
+ * prepares one: executing a tool from the cockpit would make it a second leader on the project
+ * and forge the server-derived audit origin (spec § 13).
+ */
+/** The four hints MCP defines. A hint the tool omits is ABSENT, never defaulted here. */
+export declare const mcpToolAnnotationsSchema: z.ZodObject<{
+    readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+    destructiveHint: z.ZodOptional<z.ZodBoolean>;
+    idempotentHint: z.ZodOptional<z.ZodBoolean>;
+    openWorldHint: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type McpToolAnnotations = z.infer<typeof mcpToolAnnotationsSchema>;
+/**
+ * One tool exactly as `tools/list` sends it — `toolListing()` in `packages/xezar/src/mcp/tool.ts`,
+ * key for key. Strict, so a key the wire gains that this contract does not describe fails loudly
+ * instead of being silently stripped from the page.
+ *
+ * `inputSchema` is JSON Schema and stays an opaque JSON object: describing JSON Schema in zod would
+ * be a second definition that can drift (spec § 11).
+ */
+export declare const mcpToolListingSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodString;
+    inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    annotations: z.ZodOptional<z.ZodObject<{
+        readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+        destructiveHint: z.ZodOptional<z.ZodBoolean>;
+        idempotentHint: z.ZodOptional<z.ZodBoolean>;
+        openWorldHint: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type McpToolListing = z.infer<typeof mcpToolListingSchema>;
+/** An action the tool's schema accepts only to answer with a refusal that names its boundary. */
+export declare const mcpRefusedActionSchema: z.ZodObject<{
+    tool: z.ZodString;
+    action: z.ZodString;
+    boundary: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type McpRefusedAction = z.infer<typeof mcpRefusedActionSchema>;
+/** A listed argument that is never accepted: shown as a refusal, never as an optional input. */
+export declare const mcpRefusedArgumentSchema: z.ZodObject<{
+    tool: z.ZodString;
+    argument: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type McpRefusedArgument = z.infer<typeof mcpRefusedArgumentSchema>;
+/**
+ * How a tool takes one of the two MCP-only guards (`expectedVersion`, `operationId`) — #301.
+ *
+ * DERIVED, never declared: the server validates each performing action through the tool's OWN input
+ * schema without the guard and records the actions that validation refuses. A flat listing cannot
+ * say this (the guard is optional at its top level even where every changing action needs it), and
+ * a sentence written next to the listing is how the page once told a reviewer something false.
+ *
+ * `everyCall` is true when no call is accepted without it. `requiredBy` names the actions that need
+ * it; it is empty for a tool with no actions, which only `everyCall` describes.
+ */
+export declare const mcpGuardSchema: z.ZodObject<{
+    tool: z.ZodString;
+    argument: z.ZodString;
+    everyCall: z.ZodBoolean;
+    requiredBy: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type McpGuard = z.infer<typeof mcpGuardSchema>;
+/** Something the server deliberately does not expose, and the requirements that forbid it. */
+export declare const mcpNotExposedSchema: z.ZodObject<{
+    what: z.ZodString;
+    detail: z.ZodString;
+    forbiddenBy: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type McpNotExposed = z.infer<typeof mcpNotExposedSchema>;
+export declare const mcpApiReferenceAvailableSchema: z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    xezarVersion: z.ZodString;
+    protocolVersions: z.ZodArray<z.ZodString>;
+    capabilities: z.ZodObject<{
+        tools: z.ZodObject<{
+            listChanged: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        annotations: z.ZodOptional<z.ZodObject<{
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    refusedActions: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        action: z.ZodString;
+        boundary: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    refusedArguments: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        argument: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    guards: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        argument: z.ZodString;
+        everyCall: z.ZodBoolean;
+        requiredBy: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    notExposed: z.ZodArray<z.ZodObject<{
+        what: z.ZodString;
+        detail: z.ZodString;
+        forbiddenBy: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * The route's answer. `available: false` carries one plain reason and is still a 200: the MCP
+ * module failing to load must never break the cockpit (N-07).
+ */
+export declare const mcpApiReferenceSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    available: z.ZodLiteral<true>;
+    xezarVersion: z.ZodString;
+    protocolVersions: z.ZodArray<z.ZodString>;
+    capabilities: z.ZodObject<{
+        tools: z.ZodObject<{
+            listChanged: z.ZodBoolean;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodString;
+        inputSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        annotations: z.ZodOptional<z.ZodObject<{
+            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
+            destructiveHint: z.ZodOptional<z.ZodBoolean>;
+            idempotentHint: z.ZodOptional<z.ZodBoolean>;
+            openWorldHint: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    refusedActions: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        action: z.ZodString;
+        boundary: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    refusedArguments: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        argument: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>;
+    guards: z.ZodArray<z.ZodObject<{
+        tool: z.ZodString;
+        argument: z.ZodString;
+        everyCall: z.ZodBoolean;
+        requiredBy: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+    notExposed: z.ZodArray<z.ZodObject<{
+        what: z.ZodString;
+        detail: z.ZodString;
+        forbiddenBy: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    available: z.ZodLiteral<false>;
+    reason: z.ZodString;
+}, z.core.$strip>], "available">;
+export type McpApiReference = z.infer<typeof mcpApiReferenceSchema>;

package/dist/contract/mcp-audit.d.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+/**
+ * The MCP / cockpit audit record (#102) — decision D-06 § 10, requirement N-04.
+ *
+ * One line of `<project>/.local/xezar/mcp-audit.ndjson` is one `AuditEntry`. The shape is the
+ * § 10.2 field list and nothing else, and every field is an enum member, a digest or a
+ * charset-bounded identifier: there is **no free-text field at all**, so no prompt, message, diff,
+ * command output, path, email address, token or connection value has anywhere to land (§ 10.3,
+ * F-15, F-12). That is the construction D-06 chose over relying on the best-effort run-event
+ * scrubber; the service's writer adds a value check on top, it does not replace this.
+ *
+ * MUST vs SHOULD, as D-06 § 10.2 splits them and as this schema preserves them — N-04 itself only
+ * says history *should* identify these things, so nothing here upgrades a SHOULD:
+ *   - MUST: `projectId` (from the trusted connection binding, never a parameter) and `origin`
+ *     (server-derived from the door the request came through, never client-supplied — § 10.4).
+ *   - MUST NOT: any secret, free text, absolute path or other project's identifier (§ 10.3).
+ *   - SHOULD: every other field. They are required on the wire only where the writer can always
+ *     supply them (`ts`, `action`, `outcome`); the rest are optional and absent when unknown.
+ * Audit RETENTION and the audit IDENTITY MODEL stay OPEN (N-04, D-06 § 10.5, D-09 U-2); nothing
+ * in this file implies either.
+ *
+ * An entry is a record of a decision, never an input to one (§ 10.4 rule 3): no field here grants
+ * anything, and no reader may consult an entry in place of a permission check.
+ */
+/**
+ * Where an operation came from — written by the server, never read from the request (§ 10.4).
+ *
+ * **`mcp` is the only member emitted today; `ui`, `automation` and `cli` are RESERVED.** Production
+ * opens exactly one channel, `new AuditTrail({ projectId, dataDir }, { warn }).channel('mcp')`
+ * (`packages/xezar/src/mcp/index.ts:254`, the only non-test construction site at `87d9f0d` on
+ * 2026-09-12). The cockpit's HTTP routes, the automation scheduler and headless `xezar run` record
+ * nothing, so `<project>/.local/xezar/mcp-audit.ndjson` holds the leader's operations and no
+ * human's. Reading this enum as "four kinds of entry are written" is the mistake it exists to stop
+ * (#266).
+ *
+ * The enum is deliberately NOT narrowed to the one live member: the four are the intended eventual
+ * set, removing one would be a contract break, and the reserved members carry the shape the other
+ * doors will need (see `ownerGeneration` and `operationKey` below, which are already documented as
+ * absent for non-MCP origins). Wiring those three doors is
+ * [#364](https://github.com/qodeca/xezar/issues/364); D-06 § 10.6 records why it is not 0.14.0 work.
+ */
+export declare const auditOriginSchema: z.ZodEnum<{
+    automation: "automation";
+    cli: "cli";
+    mcp: "mcp";
+    ui: "ui";
+}>;
+export type AuditOrigin = z.infer<typeof auditOriginSchema>;
+/** D-06 § 9.2's outcome vocabulary. `in-progress` is derived at lookup time and never stored. */
+export declare const auditOutcomeSchema: z.ZodEnum<{
+    "not-applied": "not-applied";
+    ok: "ok";
+    rejected: "rejected";
+    unverified: "unverified";
+}>;
+export type AuditOutcome = z.infer<typeof auditOutcomeSchema>;
+/** A dotted action id such as `runs.create` or `runs.archive`. */
+export declare const AUDIT_ACTION_RE: RegExp;
+/** A resource kind (`run`, `group`, `config`, `workflow`, `automation`, `worktree`, …). */
+export declare const AUDIT_RESOURCE_KIND_RE: RegExp;
+/**
+ * A resource id inside the bound project. The charset of D-06's `operationId` (§ 5.2): no `/`, no
+ * whitespace and no `@`, so a filesystem path, a sentence or an email address cannot be one.
+ */
+export declare const AUDIT_ID_RE: RegExp;
+/** A short machine error code (`stale_version`, `operation_key_conflict`, …) — never a message. */
+export declare const AUDIT_ERROR_CODE_RE: RegExp;
+/** D-06 § 4.2's version token, `rev1:<kind>:<id>:<seq>:<digest12>`. Any other shape is not kept. */
+export declare const AUDIT_VERSION_TOKEN_RE: RegExp;
+/** `{ kind, id }` of the resource acted on — never a path, never content (§ 10.2). */
+export declare const auditResourceSchema: z.ZodObject<{
+    kind: z.ZodString;
+    id: z.ZodString;
+}, z.core.$strip>;
+export type AuditResource = z.infer<typeof auditResourceSchema>;
+export declare const auditEntrySchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    ts: z.ZodISODateTime;
+    projectId: z.ZodString;
+    action: z.ZodString;
+    resource: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodString;
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    outcome: z.ZodEnum<{
+        "not-applied": "not-applied";
+        ok: "ok";
+        rejected: "rejected";
+        unverified: "unverified";
+    }>;
+    origin: z.ZodEnum<{
+        automation: "automation";
+        cli: "cli";
+        mcp: "mcp";
+        ui: "ui";
+    }>;
+    ownerGeneration: z.ZodOptional<z.ZodNumber>;
+    operationKey: z.ZodOptional<z.ZodString>;
+    versionToken: z.ZodOptional<z.ZodString>;
+    payloadDigest: z.ZodOptional<z.ZodString>;
+    errorCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type AuditEntry = z.infer<typeof auditEntrySchema>;

package/dist/contract/mcp-discovery.d.ts

@@ -0,0 +1,257 @@
+import { z } from 'zod';
+/**
+ * The MCP discovery result (#90, F-03, U-M06): what a project-bound leader may learn about the
+ * project it is bound to — its identity, its effective capabilities and limits, and which actions
+ * it can take, each unavailable one with a reason a person can act on.
+ *
+ * A FILTERED projection, never a pass-through. It is derived from the same facts `GET /health`
+ * and `GET /config` report, but `healthResponseSchema` also carries `projects` (every registered
+ * project) and `bootProject` (another project's id), and N-01 forbids revealing another project's
+ * name or existence. So this is its own schema rather than a widened or re-exported health shape,
+ * and every object in it is STRICT: a key the builder did not mean to send fails the parse
+ * instead of riding along to the model.
+ *
+ * Deliberately absent, per F-12/F-15 and the D-03 classification: account identity (email, login,
+ * organisation, plan, profile id), the git remote URL (it can embed a credential), install paths,
+ * raw CLI output, and every other project's limits or activity.
+ */
+/** The closed set of action areas discovery reports on. */
+export declare const mcpDiscoveryActionIdSchema: z.ZodEnum<{
+    agent_config_write: "agent_config_write";
+    automations: "automations";
+    create_task: "create_task";
+    github: "github";
+    inbox: "inbox";
+    model_selection: "model_selection";
+    open_in_app: "open_in_app";
+    parallel_variants: "parallel_variants";
+    workspace_limits: "workspace_limits";
+    worktree_choice: "worktree_choice";
+}>;
+export type McpDiscoveryActionId = z.infer<typeof mcpDiscoveryActionIdSchema>;
+/**
+ * U-M06: a usable project function, an unavailable dependency, or a read-only shared constraint.
+ * Only `available` may omit the reason — an action that cannot be taken always says why.
+ */
+export declare const mcpDiscoveryActionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodEnum<{
+        agent_config_write: "agent_config_write";
+        automations: "automations";
+        create_task: "create_task";
+        github: "github";
+        inbox: "inbox";
+        model_selection: "model_selection";
+        open_in_app: "open_in_app";
+        parallel_variants: "parallel_variants";
+        workspace_limits: "workspace_limits";
+        worktree_choice: "worktree_choice";
+    }>;
+    label: z.ZodString;
+    status: z.ZodLiteral<"available">;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodEnum<{
+        agent_config_write: "agent_config_write";
+        automations: "automations";
+        create_task: "create_task";
+        github: "github";
+        inbox: "inbox";
+        model_selection: "model_selection";
+        open_in_app: "open_in_app";
+        parallel_variants: "parallel_variants";
+        workspace_limits: "workspace_limits";
+        worktree_choice: "worktree_choice";
+    }>;
+    label: z.ZodString;
+    status: z.ZodLiteral<"unavailable">;
+    reason: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodEnum<{
+        agent_config_write: "agent_config_write";
+        automations: "automations";
+        create_task: "create_task";
+        github: "github";
+        inbox: "inbox";
+        model_selection: "model_selection";
+        open_in_app: "open_in_app";
+        parallel_variants: "parallel_variants";
+        workspace_limits: "workspace_limits";
+        worktree_choice: "worktree_choice";
+    }>;
+    label: z.ZodString;
+    status: z.ZodLiteral<"read-only">;
+    reason: z.ZodString;
+}, z.core.$strict>], "status">;
+export type McpDiscoveryAction = z.infer<typeof mcpDiscoveryActionSchema>;
+/** One coding agent: installed on this host, enabled, signed in — never WHO it is signed in as. */
+export declare const mcpDiscoveryAgentSchema: z.ZodObject<{
+    runner: z.ZodEnum<{
+        claude: "claude";
+        codex: "codex";
+        opencode: "opencode";
+        pi: "pi";
+    }>;
+    installed: z.ZodBoolean;
+    version: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodBoolean;
+    signIn: z.ZodEnum<{
+        connected: "connected";
+        disconnected: "disconnected";
+        "not-installed": "not-installed";
+        unknown: "unknown";
+    }>;
+    usable: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type McpDiscoveryAgent = z.infer<typeof mcpDiscoveryAgentSchema>;
+export declare const mcpDiscoveryToolCheckSchema: z.ZodObject<{
+    name: z.ZodEnum<{
+        gh: "gh";
+        git: "git";
+    }>;
+    available: z.ZodBoolean;
+    reason: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type McpDiscoveryToolCheck = z.infer<typeof mcpDiscoveryToolCheckSchema>;
+/**
+ * Effective limits. Workspace values are shared with every project and read-only here (D-03
+ * `safe-effective-read`); `project` is this project's own override, `null` when it inherits.
+ * Other projects' overrides and occupancy are never included.
+ */
+export declare const mcpDiscoveryLimitsSchema: z.ZodObject<{
+    maxParallel: z.ZodObject<{
+        effective: z.ZodNumber;
+        project: z.ZodNullable<z.ZodNumber>;
+        workspace: z.ZodNumber;
+    }, z.core.$strict>;
+    memoryLimitMb: z.ZodObject<{
+        effective: z.ZodNullable<z.ZodNumber>;
+        project: z.ZodNullable<z.ZodNumber>;
+        workspace: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strict>;
+    maxMonitoringSessions: z.ZodNumber;
+    monitoringWakeIntervalMinutes: z.ZodNullable<z.ZodNumber>;
+    autoResumeOnUsageLimit: z.ZodBoolean;
+    idleTimeoutMinutes: z.ZodNullable<z.ZodNumber>;
+    worktreeRetention: z.ZodNumber;
+}, z.core.$strict>;
+export type McpDiscoveryLimits = z.infer<typeof mcpDiscoveryLimitsSchema>;
+export declare const mcpDiscoverySchema: z.ZodObject<{
+    project: z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        root: z.ZodString;
+    }, z.core.$strict>;
+    xezarVersion: z.ZodString;
+    repository: z.ZodObject<{
+        git: z.ZodBoolean;
+        branch: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    settings: z.ZodObject<{
+        defaultRunner: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            opencode: "opencode";
+            pi: "pi";
+        }>;
+        baseBranch: z.ZodNullable<z.ZodString>;
+        modelsLocked: z.ZodBoolean;
+    }, z.core.$strict>;
+    capabilities: z.ZodObject<{
+        localHandoff: z.ZodBoolean;
+        followups: z.ZodBoolean;
+        automations: z.ZodBoolean;
+    }, z.core.$strict>;
+    agents: z.ZodArray<z.ZodObject<{
+        runner: z.ZodEnum<{
+            claude: "claude";
+            codex: "codex";
+            opencode: "opencode";
+            pi: "pi";
+        }>;
+        installed: z.ZodBoolean;
+        version: z.ZodOptional<z.ZodString>;
+        enabled: z.ZodBoolean;
+        signIn: z.ZodEnum<{
+            connected: "connected";
+            disconnected: "disconnected";
+            "not-installed": "not-installed";
+            unknown: "unknown";
+        }>;
+        usable: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    tools: z.ZodArray<z.ZodObject<{
+        name: z.ZodEnum<{
+            gh: "gh";
+            git: "git";
+        }>;
+        available: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    limits: z.ZodObject<{
+        maxParallel: z.ZodObject<{
+            effective: z.ZodNumber;
+            project: z.ZodNullable<z.ZodNumber>;
+            workspace: z.ZodNumber;
+        }, z.core.$strict>;
+        memoryLimitMb: z.ZodObject<{
+            effective: z.ZodNullable<z.ZodNumber>;
+            project: z.ZodNullable<z.ZodNumber>;
+            workspace: z.ZodNullable<z.ZodNumber>;
+        }, z.core.$strict>;
+        maxMonitoringSessions: z.ZodNumber;
+        monitoringWakeIntervalMinutes: z.ZodNullable<z.ZodNumber>;
+        autoResumeOnUsageLimit: z.ZodBoolean;
+        idleTimeoutMinutes: z.ZodNullable<z.ZodNumber>;
+        worktreeRetention: z.ZodNumber;
+    }, z.core.$strict>;
+    actions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodEnum<{
+            agent_config_write: "agent_config_write";
+            automations: "automations";
+            create_task: "create_task";
+            github: "github";
+            inbox: "inbox";
+            model_selection: "model_selection";
+            open_in_app: "open_in_app";
+            parallel_variants: "parallel_variants";
+            workspace_limits: "workspace_limits";
+            worktree_choice: "worktree_choice";
+        }>;
+        label: z.ZodString;
+        status: z.ZodLiteral<"available">;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodEnum<{
+            agent_config_write: "agent_config_write";
+            automations: "automations";
+            create_task: "create_task";
+            github: "github";
+            inbox: "inbox";
+            model_selection: "model_selection";
+            open_in_app: "open_in_app";
+            parallel_variants: "parallel_variants";
+            workspace_limits: "workspace_limits";
+            worktree_choice: "worktree_choice";
+        }>;
+        label: z.ZodString;
+        status: z.ZodLiteral<"unavailable">;
+        reason: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodEnum<{
+            agent_config_write: "agent_config_write";
+            automations: "automations";
+            create_task: "create_task";
+            github: "github";
+            inbox: "inbox";
+            model_selection: "model_selection";
+            open_in_app: "open_in_app";
+            parallel_variants: "parallel_variants";
+            workspace_limits: "workspace_limits";
+            worktree_choice: "worktree_choice";
+        }>;
+        label: z.ZodString;
+        status: z.ZodLiteral<"read-only">;
+        reason: z.ZodString;
+    }, z.core.$strict>], "status">>;
+}, z.core.$strict>;
+export type McpDiscovery = z.infer<typeof mcpDiscoverySchema>;

package/dist/contract/mcp-event-catalog.d.ts

@@ -0,0 +1,121 @@
+import { z } from 'zod';
+/**
+ * The significant-event catalog E-01–E-06 (#104) — the wire half: which `kind` a journal row may
+ * carry and which catalog `category` each kind belongs to. The emitter that derives the rows lives
+ * in `packages/xezar/src/mcp/event-catalog.ts`; the journal they land in is `mcp-journal.ts`.
+ *
+ * The catalog itself is AGREED and closed (requirements § 6, restated by D-05 § 1): this file adds,
+ * removes and reinterprets no category. `kind` is D-05 § 6.3's finer machine label under a
+ * category, open for additive growth, so a consumer that meets an unknown kind still has the
+ * category to route on.
+ *
+ * The exclusion is equally binding and is why this list is short: presentation-only changes, log
+ * lines and token counters never become a row (requirements § 6; D-05 § 6.3 names `item.*`,
+ * `tool-call`, `tool-result`, `text`, `token-usage` and `cost`).
+ */
+/** The agreed catalog, verbatim from the requirements contract § 6. */
+export declare const MCP_EVENT_CATALOG: {
+    readonly 'E-01': 'Task completion, failure, cancellation or blocking.';
+    readonly 'E-02': 'A question requiring attention and a human answer to a question.';
+    readonly 'E-03': 'Quality-gate result or a completed result ready for assessment.';
+    readonly 'E-04': 'Human change to goal, acceptance criteria, instruction, plan or task state.';
+    readonly 'E-05': 'Configuration/workflow change affecting execution.';
+    readonly 'E-06': 'Executor availability change affecting execution.';
+};
+/** Every kind this server emits, and the category it belongs to. One table, so the two can never
+ *  disagree. */
+export declare const MCP_EVENT_KIND_CATEGORY: {
+    readonly 'task.done': 'E-01';
+    readonly 'task.failed': 'E-01';
+    readonly 'task.cancelled': 'E-01';
+    /** The run parked at `waiting` with no structured question: it cannot go on without input. */
+    readonly 'task.blocked': 'E-01';
+    /** The agent raised a structured question (`ask.requested`) and parked at `waiting`. */
+    readonly 'question.asked': 'E-02';
+    /** A human replied to a run that was waiting on one. */
+    readonly 'question.answered': 'E-02';
+    readonly 'gate.passed': 'E-03';
+    readonly 'gate.failed': 'E-03';
+    readonly 'result.ready': 'E-03';
+    readonly 'goal.changed': 'E-04';
+    readonly 'instruction.added': 'E-04';
+    readonly 'instruction.queued': 'E-04';
+    readonly 'instruction.edited': 'E-04';
+    readonly 'instruction.removed': 'E-04';
+    readonly 'config.changed': 'E-05';
+    readonly 'workflow.saved': 'E-05';
+    readonly 'workflow.deleted': 'E-05';
+    readonly 'agent-config.changed': 'E-05';
+    readonly 'executor.available': 'E-06';
+    readonly 'executor.unavailable': 'E-06';
+};
+export type McpEventKind = keyof typeof MCP_EVENT_KIND_CATEGORY;
+export declare const mcpEventKindSchema: z.ZodEnum<{
+    "agent-config.changed": "agent-config.changed";
+    "config.changed": "config.changed";
+    "executor.available": "executor.available";
+    "executor.unavailable": "executor.unavailable";
+    "gate.failed": "gate.failed";
+    "gate.passed": "gate.passed";
+    "goal.changed": "goal.changed";
+    "instruction.added": "instruction.added";
+    "instruction.edited": "instruction.edited";
+    "instruction.queued": "instruction.queued";
+    "instruction.removed": "instruction.removed";
+    "question.answered": "question.answered";
+    "question.asked": "question.asked";
+    "result.ready": "result.ready";
+    "task.blocked": "task.blocked";
+    "task.cancelled": "task.cancelled";
+    "task.done": "task.done";
+    "task.failed": "task.failed";
+    "workflow.deleted": "workflow.deleted";
+    "workflow.saved": "workflow.saved";
+}>;
+/** What a catalog row is about. `version` is D-06's token for a run, `null` where none exists. */
+export declare const MCP_EVENT_SUBJECT_TYPES: readonly ['run', 'config', 'workflow', 'agent-config', 'executor'];
+export declare const mcpEventSubjectTypeSchema: z.ZodEnum<{
+    "agent-config": "agent-config";
+    config: "config";
+    executor: "executor";
+    run: "run";
+    workflow: "workflow";
+}>;
+export type McpEventSubjectType = z.infer<typeof mcpEventSubjectTypeSchema>;
+/**
+ * A journal row this catalog wrote: an ordinary journal row whose `kind` is a catalog kind, whose
+ * `category` is that kind's category, and whose E-04 row names a human — a leader's own change is
+ * never an E-04 row, because the catalog entry is "human change".
+ */
+export declare const mcpCatalogEventSchema: z.ZodObject<{
+    category: z.ZodEnum<{
+        "E-01": "E-01";
+        "E-02": "E-02";
+        "E-03": "E-03";
+        "E-04": "E-04";
+        "E-05": "E-05";
+        "E-06": "E-06";
+    }>;
+    kind: z.ZodString;
+    subject: z.ZodObject<{
+        type: z.ZodString;
+        id: z.ZodString;
+        version: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    origin: z.ZodEnum<{
+        human: "human";
+        leader: "leader";
+        system: "system";
+    }>;
+    causedBy: z.ZodNullable<z.ZodString>;
+    summary: z.ZodString;
+    source: z.ZodOptional<z.ZodObject<{
+        runId: z.ZodString;
+        runSeq: z.ZodNumber;
+    }, z.core.$strip>>;
+    eventId: z.ZodString;
+    journalSeq: z.ZodNumber;
+    ts: z.ZodString;
+    projectId: z.ZodString;
+}, z.core.$strip>;
+export type McpCatalogEvent = z.infer<typeof mcpCatalogEventSchema>;

package/dist/contract/mcp-event-catalog.test.d.ts

@@ -0,0 +1 @@
+export {};