@opengeni/api-router 0.30.3 → 2.2.0-canary.0

package/src/interaction-frame-proxy.ts

@@ -0,0 +1,409 @@
+import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
+import { canonicalPublicOrigin } from "@opengeni/config";
+import { WebSocket as UpstreamWebSocket } from "ws";
+import type {
+  ApiWebSocketConnection,
+  ApiWebSocketLike,
+  ApiWebSocketUpgradeServer,
+} from "./api-websocket";
+
+export const INTERACTION_FRAME_PROXY_PATH = "/v1/interaction/frame-proxy";
+export const INTERACTION_FRAME_PROXY_PROTOCOL_PREFIX = "opengeni-frame-proxy.";
+
+const TOKEN_VERSION = 1;
+const TOKEN_IV_BYTES = 12;
+const TOKEN_TAG_BYTES = 16;
+const TOKEN_MAX_BYTES = 8 * 1024;
+const TOKEN_KEY_CONTEXT = "OpenGeni interaction frame proxy v1";
+const MAX_QUEUED_MESSAGES = 64;
+const MAX_QUEUED_BYTES = 12 * 1024 * 1024;
+
+type ProxyGrant = Readonly<{
+  version: 1;
+  upstreamUrl: string;
+  upstreamProtocols: readonly string[];
+  responseProtocol: string;
+  origin: string | null;
+  expiresAt: number;
+}>;
+
+export type InteractionFrameProxyAttachment = Readonly<{
+  url: string;
+  protocols: readonly string[];
+}>;
+
+/** Docker boxes cannot carry browserd's WebSocket subprotocol grant to the
+ * viewer. Unsigned OpenSandbox Channel B still uses the lifecycle proxy, so
+ * it needs the same hatch. Signed URI-mode ingress keeps native subprotocols;
+ * `openSandboxInteractionFrameProxy` is an emergency override only. */
+export function placementUsesInteractionFrameProxy(
+  backend: string | null | undefined,
+  options?: {
+    openSandboxSignedEndpoints?: boolean;
+    openSandboxInteractionFrameProxy?: boolean;
+  },
+): boolean {
+  if (backend === "docker") return true;
+  if (backend !== "opensandbox") return false;
+  if (typeof options?.openSandboxInteractionFrameProxy === "boolean") {
+    return options.openSandboxInteractionFrameProxy;
+  }
+  return options?.openSandboxSignedEndpoints !== true;
+}
+
+/** Public origin the browser can open. TLS-terminating reverse proxies make
+ * `requestUrl` `http://127.0.0.1` / the API container; that would mint `ws://`
+ * and Chrome blocks it from an `https://` console. */
+export function resolveInteractionFrameProxyRequestUrl(input: {
+  requestUrl: string;
+  publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
+  forwardedProto?: string | null | undefined;
+  forwardedHost?: string | null | undefined;
+}): string {
+  const publicOrigin =
+    canonicalPublicOrigin(input.publicBaseUrl) ??
+    (input.webBaseUrl?.startsWith("https://") ? canonicalPublicOrigin(input.webBaseUrl) : null);
+  if (publicOrigin) return `${publicOrigin}/`;
+  const request = new URL(input.requestUrl);
+  const forwardedProto = firstForwardedValue(input.forwardedProto)?.toLowerCase();
+  const protocol =
+    forwardedProto === "https" ? "https:" : forwardedProto === "http" ? "http:" : request.protocol;
+  const forwardedHost = firstForwardedValue(input.forwardedHost);
+  const host = forwardedHost && isSafeForwardedHost(forwardedHost) ? forwardedHost : request.host;
+  try {
+    return new URL(`${protocol}//${host}/`).toString();
+  } catch {
+    return request.toString();
+  }
+}
+
+export function createInteractionFrameProxyAttachment(input: {
+  requestUrl: string;
+  publicBaseUrl?: string | undefined;
+  webBaseUrl?: string | undefined;
+  forwardedProto?: string | null | undefined;
+  forwardedHost?: string | null | undefined;
+  rootSecret: string;
+  upstreamUrl: string;
+  upstreamProtocols: readonly string[];
+  origin: string | null;
+  expiresAt: string;
+}): InteractionFrameProxyAttachment {
+  const grant = validateGrant({
+    version: TOKEN_VERSION,
+    upstreamUrl: input.upstreamUrl,
+    upstreamProtocols: input.upstreamProtocols,
+    responseProtocol: input.upstreamProtocols[0] ?? "",
+    origin: input.origin,
+    expiresAt: Date.parse(input.expiresAt),
+  });
+  const token = encryptGrant(grant, input.rootSecret);
+  const url = new URL(
+    resolveInteractionFrameProxyRequestUrl({
+      requestUrl: input.requestUrl,
+      publicBaseUrl: input.publicBaseUrl,
+      webBaseUrl: input.webBaseUrl,
+      forwardedProto: input.forwardedProto,
+      forwardedHost: input.forwardedHost,
+    }),
+  );
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  url.pathname = INTERACTION_FRAME_PROXY_PATH;
+  url.search = "";
+  url.hash = "";
+  return Object.freeze({
+    url: url.toString(),
+    protocols: Object.freeze([
+      grant.responseProtocol,
+      `${INTERACTION_FRAME_PROXY_PROTOCOL_PREFIX}${token}`,
+    ]),
+  });
+}
+
+export class InteractionFrameProxyTransport {
+  constructor(
+    private readonly rootSecret: string | undefined,
+    private readonly clock: () => number = Date.now,
+  ) {}
+
+  handles(request: Request): boolean {
+    return new URL(request.url).pathname === INTERACTION_FRAME_PROXY_PATH;
+  }
+
+  upgrade(request: Request, server: ApiWebSocketUpgradeServer): Response | undefined {
+    if (!this.handles(request)) return undefined;
+    if (request.method !== "GET") {
+      return new Response("Method Not Allowed", { status: 405, headers: { allow: "GET" } });
+    }
+    if (!this.rootSecret) return new Response("Service Unavailable", { status: 503 });
+    const offered = offeredProtocols(request.headers.get("sec-websocket-protocol"));
+    const proxyProtocol = offered.find((protocol) =>
+      protocol.startsWith(INTERACTION_FRAME_PROXY_PROTOCOL_PREFIX),
+    );
+    if (!proxyProtocol) return new Response("WebSocket proxy grant required", { status: 426 });
+    let grant: ProxyGrant;
+    try {
+      grant = decryptGrant(
+        proxyProtocol.slice(INTERACTION_FRAME_PROXY_PROTOCOL_PREFIX.length),
+        this.rootSecret,
+      );
+    } catch {
+      return new Response("Invalid WebSocket proxy grant", { status: 401 });
+    }
+    if (grant.expiresAt <= this.clock()) {
+      return new Response("WebSocket proxy grant expired", { status: 401 });
+    }
+    if (!offered.includes(grant.responseProtocol)) {
+      return new Response("WebSocket protocol required", { status: 426 });
+    }
+    const origin = normalizedOrigin(request.headers.get("origin"));
+    if (origin !== grant.origin) {
+      return new Response("WebSocket origin is not allowed", { status: 403 });
+    }
+    const connection = new InteractionFrameProxyConnection(grant);
+    const upgraded = server.upgrade(request, {
+      data: connection,
+      headers: { "sec-websocket-protocol": grant.responseProtocol },
+    });
+    return upgraded ? undefined : new Response("Bad Request", { status: 400 });
+  }
+}
+
+export class InteractionFrameProxyConnection implements ApiWebSocketConnection {
+  private socket: ApiWebSocketLike | null = null;
+  private upstream: UpstreamWebSocket | null = null;
+  private upstreamOpen = false;
+  private terminal = false;
+  private queued: Uint8Array[] = [];
+  private queuedBytes = 0;
+
+  constructor(private readonly grant: ProxyGrant) {}
+
+  attach(socket: ApiWebSocketLike): void {
+    if (this.socket || this.terminal) {
+      socket.close(4400, "invalid connection state");
+      return;
+    }
+    this.socket = socket;
+    let upstream: UpstreamWebSocket;
+    try {
+      upstream = new UpstreamWebSocket(this.grant.upstreamUrl, [...this.grant.upstreamProtocols], {
+        ...(this.grant.origin ? { headers: { origin: this.grant.origin } } : {}),
+      });
+    } catch {
+      this.fail(1011, "upstream unavailable");
+      return;
+    }
+    this.upstream = upstream;
+    upstream.binaryType = "arraybuffer";
+    upstream.once("open", () => {
+      if (this.terminal) {
+        upstream.close(1000, "viewer closed");
+        return;
+      }
+      this.upstreamOpen = true;
+      for (const message of this.queued) upstream.send(webSocketBinary(message));
+      this.queued = [];
+      this.queuedBytes = 0;
+    });
+    upstream.on("message", (data) => {
+      if (this.terminal || !this.socket) return;
+      const bytes = binaryMessage(data);
+      if (!bytes || this.socket.send(bytes, false) <= 0) {
+        this.fail(1011, "stream unavailable");
+      }
+    });
+    upstream.on("error", () => this.fail(1011, "upstream unavailable"));
+    upstream.once("close", (code, reason) => {
+      this.fail(safeCloseCode(code), boundedReason(reason.toString("utf8")));
+    });
+  }
+
+  receive(message: string | Uint8Array | ArrayBuffer): void {
+    if (this.terminal) return;
+    if (typeof message === "string") {
+      this.fail(4400, "binary frames required");
+      return;
+    }
+    const bytes =
+      message instanceof Uint8Array ? Uint8Array.from(message) : new Uint8Array(message).slice();
+    if (this.upstreamOpen && this.upstream) {
+      this.upstream.send(webSocketBinary(bytes));
+      return;
+    }
+    if (
+      this.queued.length + 1 > MAX_QUEUED_MESSAGES ||
+      this.queuedBytes + bytes.byteLength > MAX_QUEUED_BYTES
+    ) {
+      this.fail(4409, "viewer is too fast");
+      return;
+    }
+    this.queued.push(bytes);
+    this.queuedBytes += bytes.byteLength;
+  }
+
+  transportClosed(): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.upstream?.close(1000, "viewer closed");
+    this.clear();
+  }
+
+  private fail(code: number, reason: string): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.upstream?.close(code === 1000 ? 1000 : 1011, reason);
+    this.socket?.close(code, reason);
+    this.clear();
+  }
+
+  private clear(): void {
+    this.queued = [];
+    this.queuedBytes = 0;
+    this.socket = null;
+    this.upstream = null;
+  }
+}
+
+function encryptGrant(grant: ProxyGrant, rootSecret: string): string {
+  const iv = randomBytes(TOKEN_IV_BYTES);
+  const cipher = createCipheriv("aes-256-gcm", tokenKey(rootSecret), iv);
+  cipher.setAAD(Buffer.from(TOKEN_KEY_CONTEXT));
+  const ciphertext = Buffer.concat([cipher.update(JSON.stringify(grant), "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([iv, tag, ciphertext]).toString("base64url");
+}
+
+function decryptGrant(token: string, rootSecret: string): ProxyGrant {
+  const bytes = Buffer.from(token, "base64url");
+  if (
+    token.length === 0 ||
+    token.length > TOKEN_MAX_BYTES ||
+    bytes.byteLength <= TOKEN_IV_BYTES + TOKEN_TAG_BYTES
+  ) {
+    throw new Error("invalid proxy grant");
+  }
+  const iv = bytes.subarray(0, TOKEN_IV_BYTES);
+  const tag = bytes.subarray(TOKEN_IV_BYTES, TOKEN_IV_BYTES + TOKEN_TAG_BYTES);
+  const ciphertext = bytes.subarray(TOKEN_IV_BYTES + TOKEN_TAG_BYTES);
+  const decipher = createDecipheriv("aes-256-gcm", tokenKey(rootSecret), iv);
+  decipher.setAAD(Buffer.from(TOKEN_KEY_CONTEXT));
+  decipher.setAuthTag(tag);
+  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString("utf8");
+  return validateGrant(JSON.parse(plaintext));
+}
+
+function tokenKey(rootSecret: string): Buffer {
+  if (rootSecret.length === 0) throw new Error("proxy authority is empty");
+  return createHmac("sha256", rootSecret).update(TOKEN_KEY_CONTEXT).digest();
+}
+
+function validateGrant(value: unknown): ProxyGrant {
+  if (!value || typeof value !== "object") throw new Error("invalid proxy grant");
+  const grant = value as Record<string, unknown>;
+  if (grant.version !== TOKEN_VERSION) throw new Error("invalid proxy grant version");
+  const upstreamUrl = requireUpstreamUrl(grant.upstreamUrl);
+  const upstreamProtocols = requireProtocols(grant.upstreamProtocols);
+  if (
+    typeof grant.responseProtocol !== "string" ||
+    grant.responseProtocol !== upstreamProtocols[0]
+  ) {
+    throw new Error("invalid proxy response protocol");
+  }
+  const origin = grant.origin === null ? null : normalizedOrigin(grant.origin);
+  if (grant.origin !== null && !origin) throw new Error("invalid proxy origin");
+  if (!Number.isSafeInteger(grant.expiresAt) || (grant.expiresAt as number) <= 0) {
+    throw new Error("invalid proxy expiry");
+  }
+  return Object.freeze({
+    version: TOKEN_VERSION,
+    upstreamUrl,
+    upstreamProtocols: Object.freeze(upstreamProtocols),
+    responseProtocol: upstreamProtocols[0]!,
+    origin,
+    expiresAt: grant.expiresAt as number,
+  });
+}
+
+function requireUpstreamUrl(value: unknown): string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 4096) {
+    throw new Error("invalid upstream URL");
+  }
+  const url = new URL(value);
+  if (!["ws:", "wss:"].includes(url.protocol) || url.username || url.password) {
+    throw new Error("invalid upstream URL");
+  }
+  return url.toString();
+}
+
+function requireProtocols(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length === 0 || value.length > 4) {
+    throw new Error("invalid upstream protocols");
+  }
+  return value.map((protocol) => {
+    if (
+      typeof protocol !== "string" ||
+      protocol.length === 0 ||
+      protocol.length > 2048 ||
+      protocol.includes(",")
+    ) {
+      throw new Error("invalid upstream protocol");
+    }
+    return protocol;
+  });
+}
+
+function offeredProtocols(value: string | null): string[] {
+  return value
+    ? value
+        .split(",")
+        .map((part) => part.trim())
+        .filter(Boolean)
+    : [];
+}
+
+function normalizedOrigin(value: unknown): string | null {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return null;
+  try {
+    const url = new URL(value);
+    return url.pathname === "/" && !url.search && !url.hash ? url.origin : null;
+  } catch {
+    return null;
+  }
+}
+
+function firstForwardedValue(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const part = value.split(",")[0]?.trim() ?? "";
+  return part.length > 0 ? part : null;
+}
+
+function isSafeForwardedHost(host: string): boolean {
+  return host.length > 0 && host.length <= 253 && !/[\s/@?#\\]/.test(host);
+}
+
+function binaryMessage(value: unknown): Uint8Array | null {
+  if (value instanceof ArrayBuffer) return new Uint8Array(value).slice();
+  if (ArrayBuffer.isView(value)) {
+    return new Uint8Array(value.buffer, value.byteOffset, value.byteLength).slice();
+  }
+  return null;
+}
+
+function webSocketBinary(bytes: Uint8Array): ArrayBuffer {
+  const buffer = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(buffer).set(bytes);
+  return buffer;
+}
+
+function safeCloseCode(code: number): number {
+  return Number.isInteger(code) && (code === 1000 || (code >= 3000 && code <= 4999)) ? code : 1011;
+}
+
+function boundedReason(reason: string): string {
+  const normalized = reason.trim();
+  return normalized.length > 0 && Buffer.byteLength(normalized) <= 123
+    ? normalized
+    : "upstream closed";
+}

package/src/mcp/company-brain-governed-writes.ts

@@ -0,0 +1,262 @@
+import {
+  AGENT_AUTHORED_DURABLE_TEXT_STYLE,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+  AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+  PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS,
+  PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS,
+  PREFERENCE_REGISTRY_TITLE_MAX_CHARS,
+  WorkspaceInstructionPolicyTarget,
+  type CompanyBrainGovernedWriteAttempt,
+} from "@opengeni/contracts";
+import { createCompanyBrainLearningPolicyRouter } from "@opengeni/core";
+import type { Database } from "@opengeni/db";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod/v4";
+
+type JsonResult = (value: unknown) => {
+  content: { type: "text"; text: string }[];
+};
+
+const reason = z.string().trim().min(1).max(4_096);
+const evidence = {
+  operationId: z.string().uuid(),
+  claimId: z.string().uuid(),
+  evidenceId: z.string().uuid(),
+};
+const taskNotePromotion = {
+  operationId: z.string().uuid(),
+  noteId: z.string().uuid(),
+  expectedNoteVersion: z.literal(1),
+  entityType: z
+    .string()
+    .trim()
+    .min(1)
+    .max(96)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  normalizedKey: z.string().trim().min(1).max(512),
+  displayName: z.string().trim().min(1).max(512),
+  predicateKey: z
+    .string()
+    .trim()
+    .min(1)
+    .max(128)
+    .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/),
+  confidenceBps: z.number().int().min(0).max(10_000),
+  reason,
+};
+
+export type RegisterCompanyBrainGovernedWriteToolsInput = {
+  server: McpServer;
+  db: Database;
+  attempt: CompanyBrainGovernedWriteAttempt;
+  authorize: () => Promise<void>;
+  json: JsonResult;
+  router?: Pick<ReturnType<typeof createCompanyBrainLearningPolicyRouter>, "write">;
+};
+
+/**
+ * Register explicit proposal-only Company Brain tools. The signed host attempt
+ * owns tenant/session authority and the exact evidence id owns the learning
+ * policy source override. Tool input cannot select scope, active authority, or
+ * another policy source.
+ */
+export function registerCompanyBrainGovernedWriteTools(
+  input: RegisterCompanyBrainGovernedWriteToolsInput,
+): void {
+  const router = input.router ?? createCompanyBrainLearningPolicyRouter({ db: input.db });
+  input.server.registerTool(
+    "knowledge_propose",
+    {
+      description:
+        "Propose one existing evidence-backed workspace Knowledge claim through the frozen learning policy. Off creates nothing; Suggest and Automatic both create a proposal that only the human Knowledge review lifecycle can accept.",
+      inputSchema: { ...evidence, reason },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "propose_knowledge", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "knowledge_correct",
+    {
+      description:
+        "Propose an evidence-backed replacement for another workspace Knowledge claim. The old claim remains in immutable history and the correction never widens scope.",
+      inputSchema: { ...evidence, replacesClaimId: z.string().uuid(), reason },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "correct_knowledge", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "task_note_promote_knowledge",
+    {
+      description:
+        "Promote one still-active note from this exact root task tree into a normalized workspace Knowledge proposal. The immutable note bytes remain source evidence; this never activates the claim or widens it to personal/organization scope.",
+      inputSchema: taskNotePromotion,
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "promote_task_note_knowledge", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "task_note_promote_instruction_policy",
+    {
+      description:
+        "Atomically promote one still-active note from this exact root task tree into an inactive workspace instruction-policy draft. The note bytes remain exact evidence and draft content. " +
+        `Once a human activates the draft, those bytes are composed verbatim into the prompt of every session the target applies to, so a note over ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters is rejected here rather than truncated: write a fresh short imperative note instead of promoting a long working note. ` +
+        "The frozen learning policy records a decision receipt, but mandatory policy still requires human activation even under Automatic; this never widens scope.",
+      inputSchema: {
+        ...taskNotePromotion,
+        target: WorkspaceInstructionPolicyTarget,
+        expectedCurrentRevisionId: z.string().uuid().nullable(),
+        expectedActivationVersion: z.number().int().nonnegative(),
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "promote_task_note_instruction_policy", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "task_note_promote_preference",
+    {
+      description:
+        "Atomically promote one still-active note from this exact root task tree into a workspace preference proposal. The note bytes remain exact evidence and full proposal content. " +
+        `The title and description you supply are what gets composed into every session prompt, so write them as one short imperative statement; the note content is retrieved on demand and a note over ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters is rejected here rather than truncated. ` +
+        "Under Suggest the proposal waits for human review; under Automatic an eligible decision is activated through the preference lifecycle and remains undoable. This never widens scope.",
+      inputSchema: {
+        ...taskNotePromotion,
+        stableKey: z.string().trim().min(1).max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+        title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+        description: z
+          .string()
+          .trim()
+          .min(1)
+          .max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+        precedenceRank: z.number().int().min(-1_000).max(1_000).optional().default(0),
+        conflictStrategy: z
+          .enum(["override", "merge", "reject", "inform"])
+          .optional()
+          .default("override"),
+        conflictsWith: z.array(z.string().min(1)).max(32).optional().default([]),
+        expiresAt: z.string().datetime({ offset: true }).nullable().optional().default(null),
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "promote_task_note_preference", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "instruction_policy_propose",
+    {
+      description:
+        "Materialize an evidence-backed inactive workspace instruction-policy draft. " +
+        `Once a human activates it, this content is composed verbatim into the prompt of every session the target applies to (every session in this workspace for a global charter or policy, every session bound to the role for a role policy), so keep it under ${AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS} characters. ${AGENT_AUTHORED_DURABLE_TEXT_STYLE} ` +
+        "The frozen learning policy records a decision receipt, but this tool cannot activate mandatory behavior, including when learning mode is Automatic; a human must activate the draft.",
+      inputSchema: {
+        ...evidence,
+        target: WorkspaceInstructionPolicyTarget,
+        content: z
+          .string()
+          .trim()
+          .min(1)
+          .max(
+            AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_MAX_CHARS,
+            AGENT_AUTHORED_INSTRUCTION_POLICY_CONTENT_TOO_LONG_MESSAGE,
+          ),
+        expectedCurrentRevisionId: z.string().uuid().nullable(),
+        expectedActivationVersion: z.number().int().nonnegative(),
+        reason,
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "propose_instruction_policy", ...request },
+        }),
+      );
+    },
+  );
+
+  input.server.registerTool(
+    "preference_propose",
+    {
+      description:
+        "Materialize an evidence-backed workspace preference proposal. " +
+        `Its short title and description are what get composed into every session prompt; the content is retrieved on demand, so its length is retrieval cost rather than standing prompt cost. Keep the content under ${AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS} characters. ${AGENT_AUTHORED_DURABLE_TEXT_STYLE} ` +
+        "Under Suggest it stays inactive for human review; under Automatic an eligible decision is activated through the governed preference lifecycle with an undoable receipt. It never creates mandatory authority.",
+      inputSchema: {
+        ...evidence,
+        stableKey: z.string().trim().min(1).max(PREFERENCE_REGISTRY_STABLE_KEY_MAX_CHARS),
+        title: z.string().trim().min(1).max(PREFERENCE_REGISTRY_TITLE_MAX_CHARS),
+        description: z
+          .string()
+          .trim()
+          .min(1)
+          .max(PREFERENCE_REGISTRY_DESCRIPTOR_DESCRIPTION_MAX_CHARS),
+        content: z
+          .string()
+          .trim()
+          .min(1)
+          .max(
+            AGENT_AUTHORED_PREFERENCE_CONTENT_MAX_CHARS,
+            AGENT_AUTHORED_PREFERENCE_CONTENT_TOO_LONG_MESSAGE,
+          ),
+        precedenceRank: z.number().int().min(-1_000).max(1_000).optional().default(0),
+        conflictStrategy: z
+          .enum(["override", "merge", "reject", "inform"])
+          .optional()
+          .default("override"),
+        conflictsWith: z.array(z.string().min(1)).max(32).optional().default([]),
+        expiresAt: z.string().datetime({ offset: true }).nullable().optional().default(null),
+        reason,
+      },
+    },
+    async (request) => {
+      await input.authorize();
+      return input.json(
+        await router.write({
+          attempt: input.attempt,
+          request: { kind: "propose_preference", ...request },
+        }),
+      );
+    },
+  );
+}