@nebutra/agent-runtime 0.2.0

package/src/project-repo.test.ts

@@ -0,0 +1,232 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  appendJsonlLine,
+  CONVERSATIONS_DIR,
+  type CommitRef,
+  emptyProjectMetadata,
+  type GitHostPort,
+  METADATA_PATH,
+  type OwnsRepoPredicate,
+  ProjectRepo,
+  ProjectRepoError,
+  parseJsonl,
+} from "./project-repo.js";
+
+/**
+ * Fake git host: content-addressed by branch HEAD plus per-sha snapshots.
+ * Faithfully models "every project is a git repo": writeCommit appends a
+ * commit to the branch and freezes a full file snapshot under its sha.
+ */
+class FakeGitHost implements GitHostPort {
+  defaultBranch = "main";
+  // repoId -> branch -> ordered commit shas
+  private branches = new Map<string, Map<string, string[]>>();
+  // repoId -> sha -> full file snapshot
+  private snapshots = new Map<string, Map<string, Record<string, string>>>();
+  private commitMeta = new Map<string, CommitRef>();
+  public writeCount = 0;
+  private seq = 0;
+
+  async getDefaultBranch(): Promise<string> {
+    return this.defaultBranch;
+  }
+
+  private head(repoId: string, branch: string): string | null {
+    const shas = this.branches.get(repoId)?.get(branch);
+    if (!shas || shas.length === 0) return null;
+    return shas[shas.length - 1] ?? null;
+  }
+
+  async readFile(repoId: string, path: string, ref?: string | undefined): Promise<string | null> {
+    const sha = ref ?? this.head(repoId, this.defaultBranch);
+    if (!sha) return null;
+    const snap = this.snapshots.get(repoId)?.get(sha);
+    if (!snap) return null;
+    return snap[path] ?? null;
+  }
+
+  async writeCommit(
+    repoId: string,
+    branch: string,
+    files: Record<string, string>,
+    message: string,
+  ): Promise<CommitRef> {
+    this.writeCount += 1;
+    const prevSha = this.head(repoId, branch);
+    const prevSnap = (prevSha ? this.snapshots.get(repoId)?.get(prevSha) : undefined) ?? {};
+    const nextSnap = { ...prevSnap, ...files };
+    this.seq += 1;
+    const sha = `sha-${this.seq}`;
+    if (!this.snapshots.has(repoId)) this.snapshots.set(repoId, new Map());
+    this.snapshots.get(repoId)!.set(sha, nextSnap);
+    if (!this.branches.has(repoId)) this.branches.set(repoId, new Map());
+    const bmap = this.branches.get(repoId)!;
+    if (!bmap.has(branch)) bmap.set(branch, []);
+    bmap.get(branch)!.push(sha);
+    const ref: CommitRef = {
+      sha,
+      message,
+      date: new Date(2026, 0, this.seq).toISOString(),
+    };
+    this.commitMeta.set(sha, ref);
+    return ref;
+  }
+
+  async listCommits(
+    repoId: string,
+    branch: string,
+    limit?: number | undefined,
+  ): Promise<CommitRef[]> {
+    const shas = this.branches.get(repoId)?.get(branch) ?? [];
+    const refs = [...shas]
+      .reverse()
+      .map((s) => this.commitMeta.get(s))
+      .filter((r): r is CommitRef => Boolean(r));
+    return typeof limit === "number" ? refs.slice(0, limit) : refs;
+  }
+}
+
+const T = "tenant-1";
+const REPO = "tenant-1/proj-a";
+const ownsAll: OwnsRepoPredicate = () => true;
+
+function makeRepo(host: FakeGitHost, owns: OwnsRepoPredicate = ownsAll): ProjectRepo {
+  return new ProjectRepo({ host, ownsRepo: owns });
+}
+
+describe("pure helpers", () => {
+  it("parseJsonl tolerates blank and trailing newline", () => {
+    expect(parseJsonl("")).toEqual([]);
+    expect(parseJsonl("\n\n")).toEqual([]);
+    expect(parseJsonl('{"a":1}\n{"b":2}\n')).toEqual([{ a: 1 }, { b: 2 }]);
+    expect(parseJsonl('{"a":1}')).toEqual([{ a: 1 }]);
+  });
+
+  it("appendJsonlLine is immutable and appends a single line", () => {
+    const prev = '{"a":1}\n';
+    const next = appendJsonlLine(prev, { b: 2 });
+    expect(next).toBe('{"a":1}\n{"b":2}\n');
+    expect(prev).toBe('{"a":1}\n');
+    expect(appendJsonlLine("", { x: 1 })).toBe('{"x":1}\n');
+    expect(appendJsonlLine('{"a":1}', { b: 2 })).toBe('{"a":1}\n{"b":2}\n');
+  });
+
+  it("emptyProjectMetadata is well-formed", () => {
+    const m = emptyProjectMetadata("proj-a", "Proj A");
+    expect(m.projectId).toBe("proj-a");
+    expect(m.conversations).toEqual([]);
+    expect(m.deployments).toEqual([]);
+  });
+});
+
+describe("ProjectRepo metadata", () => {
+  let host: FakeGitHost;
+  let repo: ProjectRepo;
+  beforeEach(() => {
+    host = new FakeGitHost();
+    repo = makeRepo(host);
+  });
+
+  it("reads missing metadata as empty without throwing", async () => {
+    const m = await repo.readMetadata(T, REPO);
+    expect(m.conversations).toEqual([]);
+    expect(m.deployments).toEqual([]);
+  });
+
+  it("throws typed error on malformed JSON metadata", async () => {
+    await host.writeCommit(REPO, "main", { [METADATA_PATH]: "{not json" }, "x");
+    await expect(repo.readMetadata(T, REPO)).rejects.toBeInstanceOf(ProjectRepoError);
+  });
+
+  it("write -> read round-trips", async () => {
+    const meta = emptyProjectMetadata("proj-a", "Proj A");
+    const input = { ...meta, productionDomain: "proj-a.example.com" };
+    const ref = await repo.writeMetadata(T, REPO, input);
+    expect(ref.sha).toBeTruthy();
+    const back = await repo.readMetadata(T, REPO);
+    expect(back.productionDomain).toBe("proj-a.example.com");
+    // input not mutated
+    expect(input.conversations).toEqual([]);
+  });
+});
+
+describe("ProjectRepo conversations", () => {
+  let host: FakeGitHost;
+  let repo: ProjectRepo;
+  beforeEach(() => {
+    host = new FakeGitHost();
+    repo = makeRepo(host);
+  });
+
+  it("appends one commit per call and accumulates", async () => {
+    await repo.appendConversationMessage(T, REPO, "c1", { role: "user", text: "hi" });
+    expect(host.writeCount).toBe(1);
+    await repo.appendConversationMessage(T, REPO, "c1", { role: "assistant", text: "yo" });
+    expect(host.writeCount).toBe(2);
+    const msgs = await repo.readConversationMessages(T, REPO, "c1");
+    expect(msgs).toEqual([
+      { role: "user", text: "hi" },
+      { role: "assistant", text: "yo" },
+    ]);
+  });
+
+  it("readConversationMessages tolerates blank / missing file", async () => {
+    expect(await repo.readConversationMessages(T, REPO, "none")).toEqual([]);
+    await host.writeCommit(REPO, "main", { [`${CONVERSATIONS_DIR}/c2.jsonl`]: "\n\n" }, "blank");
+    expect(await repo.readConversationMessages(T, REPO, "c2")).toEqual([]);
+  });
+});
+
+describe("ProjectRepo history & restore", () => {
+  let host: FakeGitHost;
+  let repo: ProjectRepo;
+  beforeEach(() => {
+    host = new FakeGitHost();
+    repo = makeRepo(host);
+  });
+
+  it("restoreAt reads metadata at a specific sha", async () => {
+    const r1 = await repo.writeMetadata(T, REPO, {
+      ...emptyProjectMetadata("proj-a", "v1"),
+    });
+    await repo.writeMetadata(T, REPO, {
+      ...emptyProjectMetadata("proj-a", "v2"),
+    });
+    const restored = await repo.restoreAt(T, REPO, r1.sha);
+    expect(restored.metadata.name).toBe("v1");
+    const head = await repo.readMetadata(T, REPO);
+    expect(head.name).toBe("v2");
+  });
+
+  it("historyFromCommits delegates to the port", async () => {
+    await repo.writeMetadata(T, REPO, emptyProjectMetadata("proj-a", "v1"));
+    await repo.writeMetadata(T, REPO, emptyProjectMetadata("proj-a", "v2"));
+    const hist = await repo.historyFromCommits(T, REPO, 1);
+    expect(hist).toHaveLength(1);
+  });
+});
+
+describe("multi-tenant fail-closed", () => {
+  let host: FakeGitHost;
+  beforeEach(() => {
+    host = new FakeGitHost();
+  });
+
+  it("empty tenant throws", async () => {
+    const repo = makeRepo(host);
+    await expect(repo.readMetadata("", REPO)).rejects.toBeInstanceOf(ProjectRepoError);
+    await expect(repo.readMetadata("   ", REPO)).rejects.toBeInstanceOf(ProjectRepoError);
+  });
+
+  it("denies cross-tenant repo access (ownsRepo default-deny)", async () => {
+    const repo = makeRepo(host, (tenant, repoId) => repoId.startsWith(`${tenant}/`));
+    await expect(repo.readMetadata("tenant-2", "tenant-1/proj-a")).rejects.toBeInstanceOf(
+      ProjectRepoError,
+    );
+  });
+
+  it("default ownsRepo is deny when not provided", async () => {
+    const repo = new ProjectRepo({ host });
+    await expect(repo.readMetadata(T, REPO)).rejects.toBeInstanceOf(ProjectRepoError);
+  });
+});

package/src/project-repo.ts

@@ -0,0 +1,311 @@
+import { z } from "zod";
+
+/**
+ * Git-backed project repository model.
+ *
+ * Faithful re-expression of the "every project is a git repo" persistence
+ * model: a project's metadata and conversation logs live AS committed files
+ * inside its repository. The commit graph IS the history — there is no
+ * in-memory snapshot ring (that is `workbench.ts`'s concern). The actual
+ * provider-specific git implementation is injected via `GitHostPort`; this
+ * module never performs git operations itself.
+ */
+
+// ---------------------------------------------------------------------------
+// Domain types
+// ---------------------------------------------------------------------------
+
+export interface ConversationSummary {
+  id: string;
+  title: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export type DeploymentState = "idle" | "deploying" | "live" | "failed";
+
+export interface DeploymentSummary {
+  commitSha: string;
+  commitMessage: string;
+  commitDate: string;
+  domain: string;
+  url: string;
+  deploymentId: string | null;
+  state: DeploymentState;
+}
+
+export interface ProjectMetadata {
+  projectId: string;
+  name: string;
+  conversations: ConversationSummary[];
+  deployments: DeploymentSummary[];
+  productionDomain?: string | undefined;
+  productionDeploymentId?: string | undefined;
+}
+
+export interface CommitRef {
+  sha: string;
+  message: string;
+  date: string;
+}
+
+// ---------------------------------------------------------------------------
+// Injected git-host port (provider-specific git impl is NOT ported here)
+// ---------------------------------------------------------------------------
+
+export interface GitHostPort {
+  getDefaultBranch(repoId: string): Promise<string>;
+  readFile(repoId: string, path: string, ref?: string | undefined): Promise<string | null>;
+  writeCommit(
+    repoId: string,
+    branch: string,
+    files: Record<string, string>,
+    message: string,
+  ): Promise<CommitRef>;
+  listCommits(repoId: string, branch: string, limit?: number | undefined): Promise<CommitRef[]>;
+}
+
+/** Default-deny ownership predicate: cross-tenant access impossible unless wired. */
+export type OwnsRepoPredicate = (tenantId: string, repoId: string) => boolean | Promise<boolean>;
+
+export interface ProjectRepoDeps {
+  host: GitHostPort;
+  ownsRepo?: OwnsRepoPredicate | undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Typed error
+// ---------------------------------------------------------------------------
+
+export type ProjectRepoErrorCode = "tenant_required" | "tenant_denied" | "metadata_malformed";
+
+export class ProjectRepoError extends Error {
+  public readonly code: ProjectRepoErrorCode;
+  constructor(code: ProjectRepoErrorCode, message: string) {
+    super(message);
+    this.name = "ProjectRepoError";
+    this.code = code;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+export const METADATA_PATH = "metadata.json";
+export const CONVERSATIONS_DIR = "conversations";
+
+const conversationPath = (conversationId: string): string =>
+  `${CONVERSATIONS_DIR}/${conversationId}.jsonl`;
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+/** Parse JSONL content; tolerant of blank lines and trailing newline. */
+export function parseJsonl(content: string): unknown[] {
+  return content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as unknown);
+}
+
+/** Append one JSON line to existing JSONL content (immutable; never mutates input). */
+export function appendJsonlLine(prev: string, value: unknown): string {
+  const base = prev.length > 0 && !prev.endsWith("\n") ? `${prev}\n` : prev;
+  return `${base}${JSON.stringify(value)}\n`;
+}
+
+/** Well-formed empty metadata — used when a project repo has no metadata yet. */
+export function emptyProjectMetadata(projectId: string, name: string): ProjectMetadata {
+  return {
+    projectId,
+    name,
+    conversations: [],
+    deployments: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema (boundary validation)
+// ---------------------------------------------------------------------------
+
+const conversationSummarySchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+
+const deploymentSummarySchema = z.object({
+  commitSha: z.string(),
+  commitMessage: z.string(),
+  commitDate: z.string(),
+  domain: z.string(),
+  url: z.string(),
+  deploymentId: z.string().nullable(),
+  state: z.enum(["idle", "deploying", "live", "failed"]),
+});
+
+const projectMetadataSchema = z.object({
+  projectId: z.string(),
+  name: z.string(),
+  conversations: z.array(conversationSummarySchema),
+  deployments: z.array(deploymentSummarySchema),
+  productionDomain: z.string().optional(),
+  productionDeploymentId: z.string().optional(),
+});
+
+function normalizeMetadata(meta: ProjectMetadata): ProjectMetadata {
+  const parsed = projectMetadataSchema.parse(meta);
+  const out: ProjectMetadata = {
+    projectId: parsed.projectId,
+    name: parsed.name,
+    conversations: parsed.conversations,
+    deployments: parsed.deployments,
+  };
+  if (parsed.productionDomain !== undefined) {
+    out.productionDomain = parsed.productionDomain;
+  }
+  if (parsed.productionDeploymentId !== undefined) {
+    out.productionDeploymentId = parsed.productionDeploymentId;
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// ProjectRepo
+// ---------------------------------------------------------------------------
+
+export class ProjectRepo {
+  private readonly host: GitHostPort;
+  private readonly ownsRepo: OwnsRepoPredicate;
+
+  constructor(deps: ProjectRepoDeps) {
+    this.host = deps.host;
+    // Default-deny: if no ownership predicate is wired, all access is denied.
+    this.ownsRepo = deps.ownsRepo ?? (() => false);
+  }
+
+  private async authorize(tenantId: string, repoId: string): Promise<void> {
+    if (typeof tenantId !== "string" || tenantId.trim().length === 0) {
+      throw new ProjectRepoError("tenant_required", "tenantId is required");
+    }
+    const owns = await this.ownsRepo(tenantId, repoId);
+    if (!owns) {
+      throw new ProjectRepoError(
+        "tenant_denied",
+        `tenant ${tenantId} may not access repo ${repoId}`,
+      );
+    }
+  }
+
+  private async defaultBranch(repoId: string): Promise<string> {
+    return this.host.getDefaultBranch(repoId);
+  }
+
+  async readMetadata(tenantId: string, repoId: string): Promise<ProjectMetadata> {
+    await this.authorize(tenantId, repoId);
+    const raw = await this.host.readFile(repoId, METADATA_PATH);
+    if (raw === null) {
+      return emptyProjectMetadata("", "");
+    }
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(raw);
+    } catch {
+      throw new ProjectRepoError("metadata_malformed", `${METADATA_PATH} is not valid JSON`);
+    }
+    const result = projectMetadataSchema.safeParse(parsedJson);
+    if (!result.success) {
+      throw new ProjectRepoError(
+        "metadata_malformed",
+        `${METADATA_PATH} does not match the project metadata schema`,
+      );
+    }
+    return normalizeMetadata(result.data);
+  }
+
+  async writeMetadata(tenantId: string, repoId: string, meta: ProjectMetadata): Promise<CommitRef> {
+    await this.authorize(tenantId, repoId);
+    const normalized = normalizeMetadata(meta);
+    const branch = await this.defaultBranch(repoId);
+    return this.host.writeCommit(
+      repoId,
+      branch,
+      { [METADATA_PATH]: `${JSON.stringify(normalized, null, 2)}\n` },
+      "chore: update project metadata",
+    );
+  }
+
+  async appendConversationMessage(
+    tenantId: string,
+    repoId: string,
+    conversationId: string,
+    message: unknown,
+  ): Promise<CommitRef> {
+    await this.authorize(tenantId, repoId);
+    const path = conversationPath(conversationId);
+    const existing = (await this.host.readFile(repoId, path)) ?? "";
+    const next = appendJsonlLine(existing, message);
+    const branch = await this.defaultBranch(repoId);
+    // One commit per call = one commit per turn.
+    return this.host.writeCommit(
+      repoId,
+      branch,
+      { [path]: next },
+      `chore: append message to ${conversationId}`,
+    );
+  }
+
+  async readConversationMessages(
+    tenantId: string,
+    repoId: string,
+    conversationId: string,
+  ): Promise<unknown[]> {
+    await this.authorize(tenantId, repoId);
+    const raw = await this.host.readFile(repoId, conversationPath(conversationId));
+    if (raw === null) return [];
+    return parseJsonl(raw);
+  }
+
+  async restoreAt(
+    tenantId: string,
+    repoId: string,
+    sha: string,
+  ): Promise<{ metadata: ProjectMetadata }> {
+    await this.authorize(tenantId, repoId);
+    const raw = await this.host.readFile(repoId, METADATA_PATH, sha);
+    if (raw === null) {
+      return { metadata: emptyProjectMetadata("", "") };
+    }
+    let parsedJson: unknown;
+    try {
+      parsedJson = JSON.parse(raw);
+    } catch {
+      throw new ProjectRepoError(
+        "metadata_malformed",
+        `${METADATA_PATH} at ${sha} is not valid JSON`,
+      );
+    }
+    const result = projectMetadataSchema.safeParse(parsedJson);
+    if (!result.success) {
+      throw new ProjectRepoError(
+        "metadata_malformed",
+        `${METADATA_PATH} at ${sha} does not match the project metadata schema`,
+      );
+    }
+    return { metadata: normalizeMetadata(result.data) };
+  }
+
+  async historyFromCommits(
+    tenantId: string,
+    repoId: string,
+    limit?: number | undefined,
+  ): Promise<CommitRef[]> {
+    await this.authorize(tenantId, repoId);
+    const branch = await this.defaultBranch(repoId);
+    return this.host.listCommits(repoId, branch, limit);
+  }
+}

package/src/protocol.ts

@@ -0,0 +1,159 @@
+/**
+ * App-server protocol contract (WRAP — capability #5).
+ *
+ * Faithful re-expression of the upstream JSON-RPC method registry, the
+ * serialization-scope concurrency model, server-initiated approval requests,
+ * and the notification event stream.
+ *
+ * Multi-tenant adaptation (non-negotiable): every serialization scope is
+ * additionally keyed by `tenantId`. Upstream `Thread { thread_id }` becomes
+ * `{ tenantId, threadId }` — natural per-tenant ordering + isolation for free.
+ * This is the only coupling seam to an optional decoupled kernel sidecar
+ * (Track B); transport (WS/SSE/stdio) is pluggable and not defined here.
+ */
+
+import { z } from "zod";
+
+// ── Serialization scope (concurrency control) ────────────────────────────────
+
+/**
+ * Requests sharing a scope are serialized; distinct scopes run in parallel.
+ * `tenantId` is mandatory on every scope — cross-tenant requests can never
+ * share a scope.
+ */
+export type SerializationScope =
+  | { readonly tenantId: string; readonly kind: "none" }
+  | { readonly tenantId: string; readonly kind: "global"; readonly key: string }
+  | { readonly tenantId: string; readonly kind: "global_shared_read"; readonly key: string }
+  | { readonly tenantId: string; readonly kind: "thread"; readonly threadId: string }
+  | { readonly tenantId: string; readonly kind: "command_exec"; readonly processId: string }
+  | { readonly tenantId: string; readonly kind: "mcp_oauth"; readonly server: string };
+
+/** Stable string key used to coalesce requests into the same serial lane. */
+export function scopeKey(scope: SerializationScope): string {
+  switch (scope.kind) {
+    case "none":
+      return `t:${scope.tenantId}|none:${cryptoRandom()}`;
+    case "global":
+    case "global_shared_read":
+      return `t:${scope.tenantId}|${scope.kind}:${scope.key}`;
+    case "thread":
+      return `t:${scope.tenantId}|thread:${scope.threadId}`;
+    case "command_exec":
+      return `t:${scope.tenantId}|cmd:${scope.processId}`;
+    case "mcp_oauth":
+      return `t:${scope.tenantId}|mcpoauth:${scope.server}`;
+  }
+}
+
+function cryptoRandom(): string {
+  return globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random()}`;
+}
+
+// ── Client -> server method registry ─────────────────────────────────────────
+
+/** How a method's scope is derived from its params. */
+export type ScopeRule =
+  | { readonly kind: "none" }
+  | { readonly kind: "global"; readonly key: string }
+  | { readonly kind: "thread" };
+
+export interface MethodSpec {
+  /** Namespaced `domain/verb` wire name. */
+  readonly method: string;
+  readonly scope: ScopeRule;
+  readonly experimental?: boolean;
+}
+
+/**
+ * The faithful subset of the upstream registry relevant to a multi-tenant web
+ * product. `thread`-scoped methods derive `{ tenantId, threadId }`.
+ */
+export const METHOD_REGISTRY = {
+  initialize: { method: "initialize", scope: { kind: "none" } },
+  threadStart: { method: "thread/start", scope: { kind: "none" } },
+  threadResume: { method: "thread/resume", scope: { kind: "thread" } },
+  threadFork: { method: "thread/fork", scope: { kind: "thread" } },
+  threadArchive: { method: "thread/archive", scope: { kind: "thread" } },
+  threadCompactStart: { method: "thread/compact/start", scope: { kind: "thread" } },
+  threadRollback: { method: "thread/rollback", scope: { kind: "thread" } },
+  turnStart: { method: "turn/start", scope: { kind: "thread" } },
+  turnSteer: { method: "turn/steer", scope: { kind: "thread" } },
+  turnInterrupt: { method: "turn/interrupt", scope: { kind: "thread" } },
+  modelList: { method: "model/list", scope: { kind: "none" } },
+} as const satisfies Record<string, MethodSpec>;
+
+export type MethodName = (typeof METHOD_REGISTRY)[keyof typeof METHOD_REGISTRY]["method"];
+
+/** Resolve a method's runtime scope from tenant + params. */
+export function resolveScope(
+  spec: MethodSpec,
+  tenantId: string,
+  params: { threadId?: string },
+): SerializationScope {
+  switch (spec.scope.kind) {
+    case "none":
+      return { tenantId, kind: "none" };
+    case "global":
+      return { tenantId, kind: "global", key: spec.scope.key };
+    case "thread": {
+      if (!params.threadId) {
+        throw new Error(`Method ${spec.method} requires a threadId for scoping`);
+      }
+      return { tenantId, kind: "thread", threadId: params.threadId };
+    }
+  }
+}
+
+// ── Server -> client requests (approval / elicitation) ───────────────────────
+
+/** Approvals are server-initiated RPC, not side channels. */
+export type ServerRequest =
+  | {
+      readonly type: "command_execution.request_approval";
+      readonly requestId: string;
+      readonly command: string;
+    }
+  | {
+      readonly type: "file_change.request_approval";
+      readonly requestId: string;
+      readonly paths: readonly string[];
+    }
+  | {
+      readonly type: "permissions.request_approval";
+      readonly requestId: string;
+      readonly summary: string;
+    }
+  | {
+      readonly type: "mcp.elicitation";
+      readonly requestId: string;
+      readonly server: string;
+      readonly schema: unknown;
+    };
+
+// ── Server -> client notifications (event stream) ────────────────────────────
+
+export const NOTIFICATIONS = [
+  "thread/started",
+  "turn/started",
+  "turn/completed",
+  "turn/failed",
+  "item/started",
+  "item/updated",
+  "item/completed",
+  "model/rerouted",
+  "thread/compacted",
+] as const;
+export type NotificationName = (typeof NOTIFICATIONS)[number];
+
+// ── Boundary validation for the universal envelope ───────────────────────────
+
+export const requestEnvelopeSchema = z.object({
+  jsonrpc: z.literal("2.0"),
+  id: z.union([z.string(), z.number()]),
+  method: z.string(),
+  /** tenantId is mandatory at the envelope boundary — fail closed otherwise. */
+  tenantId: z.string().min(1),
+  params: z.unknown().optional(),
+});
+export type RequestEnvelope = z.infer<typeof requestEnvelopeSchema>;