@hienlh/ppm 0.22.10 → 0.23.0

package/src/providers/claude-agent-sdk.ts

@@ -5,7 +5,9 @@ import {
   getSessionInfo as sdkGetSessionInfo,
   getSessionMessages,
 } from "@anthropic-ai/claude-agent-sdk";
-import { buildModelQueryOptions } from "./claude-agent-sdk-query-options.ts";
+import { buildModelQueryOptions, buildSystemPromptOption, designMcpServers, preToolUseDecision } from "./claude-agent-sdk-query-options.ts";
+import { CLAUDE_DESIGN_CHECK_TOOL } from "../services/design/mcp/design-mcp-tool.ts";
+import { designToolDecision } from "../services/design/design-tool-policy.ts";
 import { CLAUDE_MODELS } from "../types/claude-models.ts";
 import { isImageLimitRejection } from "./image-limit-detection.ts";
 import type {
@@ -215,6 +217,7 @@ interface PendingApproval {
  */
 export class ClaudeAgentSdkProvider implements AIProvider {
   readonly supportsSharedContext = true;
+  readonly supportsDesignInstructions = true;
   id = "claude";
   name = "Claude";
 
@@ -881,23 +884,34 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     const providerConfig = this.getProviderConfig();
     const permissionMode = opts?.permissionMode || providerConfig.permission_mode || "bypassPermissions";
     const isBypass = permissionMode === "bypassPermissions";
-    const systemPromptOpt = providerConfig.system_prompt
-      ? { type: "custom" as const, value: providerConfig.system_prompt }
-      : { type: "preset" as const, preset: "claude_code" as const };
+    const systemPromptOpt = buildSystemPromptOption(providerConfig.system_prompt, opts?.designInstructions);
+    // A design session in acceptEdits auto-approves file tools only while they target the
+    // project, and asks for everything else. Any other mode the user picks for a design
+    // session behaves exactly as that mode does in an ordinary chat.
+    const designPolicy = !!opts?.designSession && permissionMode === "acceptEdits";
+    // No project root means nothing can be proven inside it, so every file tool asks.
+    const designRoot = designPolicy && meta.projectPath && existsSync(meta.projectPath) ? meta.projectPath : undefined;
 
     // Build allowedTools based on permission mode.
     // SDK auto-approves everything in allowedTools (skips canUseTool callback).
     // In non-bypass modes, only pre-approve read-only tools so write/execute tools
     // go through the permission evaluation chain → canUseTool callback.
+    // The design policy pre-approves nothing: the read-only list would let Read and Grep
+    // reach any path on disk and every MCP tool run unasked, which is exactly what a
+    // design session's agent (fed page content it did not write) must not do.
     const readOnlyTools = ["Read", "Glob", "Grep", "WebSearch", "WebFetch", "ToolSearch"];
     const writeTools = ["Write", "Edit", "Bash", "Agent", "Skill", "TodoWrite", "AskUserQuestion"];
     const teamTools = providerConfig.agent_teams
       ? ["TeamCreate", "TeamDelete", "SendMessage", "TaskCreate", "TaskUpdate", "TaskList", "TaskGet"]
       : [];
     const mcpTools = ["mcp__*"];
-    const allowedTools = isBypass
-      ? [...readOnlyTools, ...writeTools, ...teamTools, ...mcpTools]
-      : [...readOnlyTools, ...mcpTools];
+    // `design_check` only reads the canvas, so a design session never asks before it runs.
+    const designCheckTool = opts?.designSession && opts.designMcp ? CLAUDE_DESIGN_CHECK_TOOL : null;
+    const allowedTools = designPolicy
+      ? (designCheckTool ? [designCheckTool] : [])
+      : isBypass
+        ? [...readOnlyTools, ...writeTools, ...teamTools, ...mcpTools]
+        : [...readOnlyTools, ...mcpTools];
 
     /**
      * Approval events to yield from the generator.
@@ -936,6 +950,12 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         }
         return { behavior: "deny" as const, message: "User skipped the question" };
       }
+      // The PreToolUse hook normally settles design-policy tools before this runs; this is
+      // the fail-closed backstop for any path that reaches the callback without it.
+      if (designPolicy && toolName !== designCheckTool && designToolDecision(toolName, input, designRoot) !== "allow") {
+        const result = await waitForApproval(toolName, input);
+        if (!result.approved) return { behavior: "deny" as const, message: "User denied tool execution" };
+      }
       return { behavior: "allow" as const, updatedInput: input };
     };
 
@@ -952,18 +972,27 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       // Bypass mode: allow everything
       if (isBypass) return {};
 
-      // Read-only tools: always allow
-      if (readOnlyTools.includes(toolName)) return {};
-
       // AskUserQuestion: handled by canUseTool callback
       if (toolName === "AskUserQuestion") return {};
 
+      if (designCheckTool && toolName === designCheckTool) return preToolUseDecision("allow");
+
+      // Design policy: project-scoped file tools pass, everything else falls through to
+      // the approval prompt below. The decision is explicit so the SDK's own acceptEdits
+      // auto-approvals (which include some shell commands) never get a say.
+      if (designPolicy) {
+        if (designToolDecision(toolName, hookInput?.tool_input, designRoot) === "allow") {
+          return preToolUseDecision("allow");
+        }
+      } else if (readOnlyTools.includes(toolName)) {
+        // Read-only tools: always allow
+        return {};
+      }
+
       // Non-bypass mode: ask FE for approval on write/execute tools
       const result = await waitForApproval(toolName, hookInput?.tool_input);
-      if (result.approved) {
-        return { hookSpecificOutput: { permissionDecision: "allow" } };
-      }
-      return { hookSpecificOutput: { permissionDecision: "deny", message: "User denied tool execution" } };
+      if (result.approved) return preToolUseDecision("allow");
+      return preToolUseDecision("deny", "User denied tool execution");
     };
 
     // Hooks config: add our permission hook for non-bypass modes
@@ -1072,7 +1101,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
       console.log(`[sdk] query: session=${sessionId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform} accountMode=${!!account} permissionMode=${permissionMode} isBypass=${isBypass}`);
 
-      const mcpServers = this.resolveMcpServers(effectiveCwd);
+      const mcpServers = { ...this.resolveMcpServers(effectiveCwd), ...designMcpServers(opts?.designSession ? opts.designMcp : undefined) };
       const hasMcp = Object.keys(mcpServers).length > 0;
 
       // Buffer subprocess stderr for crash diagnostics + log in real-time

package/src/providers/codex-app-server/codex-event-mapper.ts

@@ -146,6 +146,23 @@ export function itemToToolUse(item: Item): ChatEvent {
 }
 
 /** Build the tool_result from a completed ThreadItem. */
+/**
+ * An MCP result's content blocks as readable text, with any image reduced to a label. A
+ * block's base64 payload (a `design_check` screenshot is up to half a megabyte) would
+ * otherwise be the visible result, and ride through the turn buffer and the JSONL with it.
+ */
+export function mcpResultText(result: unknown): string | undefined {
+  if (result == null) return undefined;
+  const content = (result as { content?: unknown }).content;
+  if (!Array.isArray(content)) return typeof result === "string" ? result : JSON.stringify(result);
+  return content.map((block) => {
+    const b = (block ?? {}) as { type?: unknown; text?: unknown; mimeType?: unknown };
+    if (b.type === "text" && typeof b.text === "string") return b.text;
+    if (b.type === "image") return `[image ${typeof b.mimeType === "string" ? b.mimeType : ""}]`.replace(" ]", "]");
+    return JSON.stringify(block);
+  }).join("\n");
+}
+
 export function itemToToolResult(item: Item): ChatEvent {
   const type = item.type;
   let output = "";
@@ -158,7 +175,7 @@ export function itemToToolResult(item: Item): ChatEvent {
     exitCode = typeof exit === "number" ? exit : undefined;
     isError = exitCode != null && exitCode !== 0;
   } else if (type === "mcpToolCall") {
-    output = redactTruncate(item.result ?? item.error ?? "");
+    output = redactTruncate(mcpResultText(item.result) ?? item.error ?? "");
     isError = item.error != null;
   } else if (type === "fileChange") {
     const changes = Array.isArray(item.changes) ? item.changes : [];

package/src/providers/codex-app-server/codex-jsonrpc-client.ts

@@ -58,9 +58,10 @@ export class CodexJsonRpcClient {
   private closed = false;
 
   /** Spawn the subprocess. Injectable streams allow unit testing without a real spawn.
-   * `codexHome` selects which account's auth the app-server uses (CODEX_HOME). */
-  start(opts?: { cwd?: string; codexHome?: string }): void {
-    const env = buildSpawnEnv();
+   * `codexHome` selects which account's auth the app-server uses (CODEX_HOME); `env` adds
+   * variables this one session needs (a design session's MCP token). */
+  start(opts?: { cwd?: string; codexHome?: string; env?: Record<string, string> }): void {
+    const env = { ...buildSpawnEnv(), ...(opts?.env ?? {}) };
     if (opts?.codexHome) env.CODEX_HOME = opts.codexHome;
     this.proc = spawn(process.execPath, ["x", "@openai/codex", "app-server"], {
       cwd: opts?.cwd,

package/src/providers/codex-app-server/codex-permission-map.ts

@@ -22,7 +22,17 @@ const MAP: Record<string, CodexPermission> = {
   plan: { sandbox: "read-only", approvalPolicy: "never" },
 };
 
+/**
+ * A design session's acceptEdits: file edits stay inside the workspace, and any command
+ * outside codex's trusted read-only set asks first. `on-request` would let the model run
+ * arbitrary commands in the sandbox unasked, which is the opposite of the design default
+ * ("edits yes, shell asks"). Residual, and accepted: codex still auto-runs its trusted
+ * read-only commands (`cat`, `ls`, …) and its sandbox can read outside the workspace.
+ */
+const DESIGN_ACCEPT_EDITS: CodexPermission = { sandbox: "workspace-write", approvalPolicy: "untrusted" };
+
 /** Pure map from PPM permissionMode → codex {sandbox, approvalPolicy}. Unknown → bypass. */
-export function permissionModeToCodex(mode?: string): CodexPermission {
+export function permissionModeToCodex(mode?: string, opts?: { designSession?: boolean }): CodexPermission {
+  if (opts?.designSession && mode === "acceptEdits") return DESIGN_ACCEPT_EDITS;
   return (mode && MAP[mode]) || MAP.bypassPermissions!;
 }

package/src/providers/codex-app-server/codex-protocol.ts

@@ -27,6 +27,9 @@ export interface ThreadStartParams {
   sandbox?: SandboxMode;
   approvalPolicy?: AskForApproval;
   model?: string;
+  /** Supplements (never replaces) codex's base instructions. Not persisted by the thread:
+   *  it is a per-request override, so every thread/start and thread/resume must carry it. */
+  developerInstructions?: string;
 }
 
 export interface ThreadResumeParams {
@@ -35,6 +38,8 @@ export interface ThreadResumeParams {
   sandbox?: SandboxMode;
   approvalPolicy?: AskForApproval;
   model?: string;
+  /** See ThreadStartParams.developerInstructions. */
+  developerInstructions?: string;
 }
 
 /** thread/started notification + thread/start response both carry a Thread. */

package/src/providers/codex-app-server/codex-provider.ts

@@ -31,6 +31,8 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS } from "./codex-jsonrpc-client.ts";
 import { permissionModeToCodex, type CodexPermission } from "./codex-permission-map.ts";
+import { buildThreadParams, designMcpEnv, requestWithInstructionsFallback, type CodexThreadParams } from "./codex-thread-params.ts";
+import type { DesignMcpAccess } from "../../services/design/mcp/design-mcp-tool.ts";
 import { mapCodexEvent, parseTokenUsage } from "./codex-event-mapper.ts";
 import { subagentCardId } from "./codex-subagent-thread.ts";
 import { decisionFor, isApprovalMethod, type ApprovalMethod } from "./codex-approval-decision.ts";
@@ -139,6 +141,11 @@ interface LiveSession {
   channel: EventChannel;
   permission: CodexPermission;
   model?: string;
+  /** Design instructions, resent on every thread/start and thread/resume — codex does not
+   *  persist them, and the account-switch respawn has no send options to read them from. */
+  developerInstructions?: string;
+  /** A design session's `design_check` endpoint, kept for the same reason. */
+  designMcp?: DesignMcpAccess;
   pendingApprovals: Map<string, PendingApproval>;
   answeredCodexIds: Set<number | string>;
   /** Rollout history snapshot at connect — lets live message ids continue the
@@ -297,6 +304,7 @@ function buildUserInputResponse(questions: unknown, data: unknown): ToolRequestU
  */
 export class CodexAppServerProvider implements AIProvider {
   readonly supportsSharedContext = true;
+  readonly supportsDesignInstructions = true;
   readonly id = "codex";
   readonly name = "Codex";
 
@@ -680,20 +688,22 @@ export class CodexAppServerProvider implements AIProvider {
     client.onNotification((n) => this.handleNotification(live, n));
     client.onServerRequest((r) => this.handleServerRequest(live, r));
     client.onClose(() => this.handleClose(live));
-    client.start({ cwd: live.cwd, codexHome: account.home });
+    client.start({ cwd: live.cwd, codexHome: account.home, env: designMcpEnv(live.designMcp) });
     live.client = client;
 
     await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
     client.notify("initialized");
 
-    const resumeBase = {
-      ...this.contextConfigOverrides(),
+    const resumeBase = buildThreadParams({
       cwd: live.cwd,
-      sandbox: live.permission.sandbox,
-      approvalPolicy: live.permission.approvalPolicy,
-      ...(live.model ? { model: live.model } : {}),
-    };
-    await this.resumeThread(client, threadId, found, account.home, resumeBase);
+      permission: live.permission,
+      model: live.model,
+      configOverrides: this.contextConfigOverrides(),
+      developerInstructions: live.developerInstructions,
+      designMcp: live.designMcp,
+    });
+    await requestWithInstructionsFallback(resumeBase,
+      (params) => this.resumeThread(client, threadId, found, account.home, params));
   }
 
   /**
@@ -714,7 +724,7 @@ export class CodexAppServerProvider implements AIProvider {
     threadId: string,
     found: { path: string; sessionsDir: string },
     codexHome: string | undefined,
-    resumeBase: Record<string, unknown>,
+    resumeBase: CodexThreadParams,
   ): Promise<unknown> {
     const target = sessionsDirForHome(codexHome);
     const path = localizeRollout(found.path, found.sessionsDir, target);
@@ -738,7 +748,7 @@ export class CodexAppServerProvider implements AIProvider {
   private async connect(sessionId: string, opts?: SendMessageOpts): Promise<LiveSession> {
     const meta = this.sessions.get(sessionId);
     const cwd = meta?.projectPath || getSessionProjectPath(sessionId) || process.cwd();
-    const permission = permissionModeToCodex(opts?.permissionMode ?? this.config?.permission_mode);
+    const permission = permissionModeToCodex(opts?.permissionMode ?? this.config?.permission_mode, { designSession: opts?.designSession });
     const model = codexModel(opts?.model ?? this.config?.model);
 
     // Only resume a rollout attributable to this project. An unknown/resumed ID
@@ -750,6 +760,8 @@ export class CodexAppServerProvider implements AIProvider {
     const channel = createEventChannel();
     const live: LiveSession = {
       client, threadId: null, cwd, channel, permission, model,
+      developerInstructions: opts?.designInstructions,
+      designMcp: opts?.designSession ? opts.designMcp : undefined,
       pendingApprovals: new Map(), answeredCodexIds: new Set(),
       history: [], transcript: [], currentAssistant: "", currentEvents: [],
       pendingTurns: [], subagentThreadIds: new Set(),
@@ -763,17 +775,22 @@ export class CodexAppServerProvider implements AIProvider {
     client.onNotification((n) => this.handleNotification(live, n));
     client.onServerRequest((r) => this.handleServerRequest(live, r));
     client.onClose(() => this.handleClose(live));
-    client.start({ cwd, codexHome: account?.home });
+    client.start({ cwd, codexHome: account?.home, env: designMcpEnv(live.designMcp) });
 
     await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
     client.notify("initialized");
 
-    const resumeBase = { cwd, sandbox: permission.sandbox, approvalPolicy: permission.approvalPolicy, ...(model ? { model } : {}), ...this.contextConfigOverrides() };
+    const resumeBase = buildThreadParams({
+      cwd, permission, model,
+      configOverrides: this.contextConfigOverrides(),
+      developerInstructions: live.developerInstructions,
+      designMcp: live.designMcp,
+    });
     // Only treat as a resume when a rollout for this id is attributable to THIS
     // project (fail-closed cwd guard) — never resume another project's thread.
-    const result = found
-      ? await this.resumeThread(client, sessionId, found, account?.home, resumeBase)
-      : await client.request("thread/start", resumeBase);
+    const result = await requestWithInstructionsFallback(resumeBase, (params) => found
+      ? this.resumeThread(client, sessionId, found, account?.home, params)
+      : client.request("thread/start", params));
 
     const threadId = extractThreadId(result) ?? (found ? sessionId : null);
     if (!threadId) throw new Error("codex thread/start returned no thread id");

package/src/providers/codex-app-server/codex-thread-params.ts

@@ -0,0 +1,96 @@
+import type { CodexPermission } from "./codex-permission-map.ts";
+import type { ThreadStartParams } from "./codex-protocol.ts";
+import {
+  CODEX_DESIGN_MCP_SERVER, CODEX_DESIGN_MCP_TOKEN_ENV, DESIGN_CHECK_TOOL, DESIGN_CHECK_TOOL_TIMEOUT_MS,
+  type DesignMcpAccess,
+} from "../../services/design/mcp/design-mcp-tool.ts";
+
+/** Config overrides, keyed like `-c key=value` on codex's command line (dotted paths). */
+export type CodexConfigOverrides = Record<string, unknown>;
+
+/** The overrides both thread/start and thread/resume carry (resume adds threadId + path). */
+export type CodexThreadParams = ThreadStartParams & { config?: CodexConfigOverrides };
+
+export interface ThreadParamsInput {
+  cwd: string;
+  permission: CodexPermission;
+  model?: string;
+  /** Provider-wide config overrides, already shaped as `{ config }` or `{}`. */
+  configOverrides?: { config?: CodexConfigOverrides };
+  developerInstructions?: string;
+  /** A design session's `design_check` endpoint; added as one more MCP server. */
+  designMcp?: DesignMcpAccess;
+}
+
+/**
+ * The design MCP server as a codex config override. The dotted key adds this one server and
+ * leaves the user's own `mcp_servers` alone. The token is not in the config: codex reads it
+ * from the app-server's environment (`bearer_token_env_var`), so it is never written into a
+ * thread's saved settings, and codex's default shell policy drops `*TOKEN*` variables from
+ * the commands the agent runs. The tool only reads the canvas, so it is approved up front —
+ * an approval prompt here would reach PPM as an elicitation it declines, cancelling the call.
+ */
+export function designMcpConfig(access: DesignMcpAccess | undefined): CodexConfigOverrides {
+  if (!access) return {};
+  return {
+    [`mcp_servers.${CODEX_DESIGN_MCP_SERVER}`]: {
+      url: access.url,
+      bearer_token_env_var: CODEX_DESIGN_MCP_TOKEN_ENV,
+      enabled_tools: [DESIGN_CHECK_TOOL],
+      default_tools_approval_mode: "approve",
+      startup_timeout_sec: 10,
+      tool_timeout_sec: Math.ceil(DESIGN_CHECK_TOOL_TIMEOUT_MS / 1000),
+    },
+  };
+}
+
+/** The environment the app-server needs for {@link designMcpConfig}; `{}` for other sessions. */
+export function designMcpEnv(access: DesignMcpAccess | undefined): Record<string, string> {
+  return access ? { [CODEX_DESIGN_MCP_TOKEN_ENV]: access.token } : {};
+}
+
+/**
+ * One builder for the params of every thread/start and thread/resume — the first connect
+ * and the account-switch respawn used to assemble them separately, which is how a field
+ * added to one silently goes missing from the other. `developerInstructions` is left out
+ * entirely when empty, so an ordinary session sends exactly what it always has.
+ */
+export function buildThreadParams(input: ThreadParamsInput): CodexThreadParams {
+  const instructions = input.developerInstructions?.trim();
+  const config = { ...(input.configOverrides?.config ?? {}), ...designMcpConfig(input.designMcp) };
+  return {
+    ...(Object.keys(config).length ? { config } : {}),
+    cwd: input.cwd,
+    sandbox: input.permission.sandbox,
+    approvalPolicy: input.permission.approvalPolicy,
+    ...(input.model ? { model: input.model } : {}),
+    ...(instructions ? { developerInstructions: instructions } : {}),
+  };
+}
+
+/** A codex build that predates `developerInstructions` rejects it as an unknown field. */
+export function isUnknownDeveloperInstructionsError(err: unknown): boolean {
+  const message = err instanceof Error ? err.message : String(err ?? "");
+  return /developerInstructions|developer_instructions/.test(message)
+    && /unknown|unexpected|unrecognized|not allowed|invalid/i.test(message);
+}
+
+/**
+ * Send a thread request, and if an older codex refuses the instructions field, send it
+ * once more without it — a design session that loses its instructions still works as a
+ * chat, while a refused thread/start is no session at all. Logged, never silent.
+ */
+export async function requestWithInstructionsFallback<T>(
+  params: CodexThreadParams,
+  send: (params: CodexThreadParams) => Promise<T>,
+  log: (message: string) => void = console.warn,
+): Promise<T> {
+  try {
+    return await send(params);
+  } catch (err) {
+    if (!params.developerInstructions || !isUnknownDeveloperInstructionsError(err)) throw err;
+    log("[codex] app-server rejected developerInstructions; retrying without design instructions");
+    const { developerInstructions: _dropped, ...rest } = params;
+    return send(rest);
+  }
+}

package/src/server/helpers/preview-asset-guard.ts

@@ -0,0 +1,36 @@
+import { dirname, extname, isAbsolute, relative, sep } from "node:path";
+import { assertAllowed, assertNotPpmDir } from "../../services/fs-path-guard.service.ts";
+
+/**
+ * The file-level rules every sandboxed preview route shares (the HTML file preview and the
+ * design canvas): which files may be served at all, and which Host may be written into a
+ * CSP directive.
+ */
+
+/** Web assets a preview may load. Anything else (dotenv, databases, keys) is a 403. */
+export const PREVIEW_ASSET_EXTENSIONS = new Set([".html", ".htm", ".css", ".js", ".mjs", ".json", ".png", ".jpg", ".jpeg", ".gif", ".webp", ".avif", ".svg", ".ico", ".mp4", ".webm", ".mov", ".mp3", ".wav", ".ogg", ".m4a", ".woff", ".woff2", ".ttf", ".otf", ".vtt"]);
+
+export function previewDenied(): never {
+  throw Object.assign(new Error("Preview path is not allowed"), { status: 403 });
+}
+
+export function isInsideRoot(root: string, path: string): boolean {
+  const rel = relative(root, path);
+  return rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+
+export function guardPreviewAsset(path: string, root = dirname(path)): void {
+  assertAllowed(path);
+  assertNotPpmDir(path);
+  // Only web assets, never hidden directories, dotenv, database or key files.
+  if (relative(root, path).split(/[\\/]/).some((part) => part.startsWith(".")) || !PREVIEW_ASSET_EXTENSIONS.has(extname(path).toLowerCase())) previewDenied();
+}
+
+/**
+ * Bun reconstructs req.url with its listening port. Preserve the browser's Host through
+ * Vite/tunnels; validate before inserting into a CSP directive.
+ */
+export function browserFacingHost(requestHost: string | undefined, requestUrl: string): string {
+  const host = requestHost ?? "";
+  return /^(?:[a-z0-9.-]+|\[[a-f0-9:]+\])(?::\d{1,5})?$/i.test(host) ? host : new URL(requestUrl).host;
+}

package/src/server/index.ts

@@ -180,17 +180,28 @@ app.route("/proxy", proxyRoutes);
 // HTML assets authenticate with bounded preview capabilities, never the PPM session token.
 app.route("/api/html-preview/content", htmlPreviewRoutes.content);
 
+// Design canvas files: the same bounded-capability model, one design per token.
+import { designPreviewRoutes } from "./routes/design-preview.ts";
+app.route("/api/design-preview/content", designPreviewRoutes.content);
+
 // MCP sign-in redirect: reached by a browser navigation from the authorization server,
 // which carries no PPM token. It only completes a flow an authenticated user started.
 import { mcpAuthRoutes, mcpAuthCallbackHandler } from "./routes/mcp-auth.ts";
 import { mcpOAuthFlows } from "../services/mcp-oauth/mcp-oauth-flows.ts";
 app.get("/api/mcp-auth/callback", mcpAuthCallbackHandler);
 
+// Design MCP endpoint: called by a design session's own Claude/Codex subprocess, which has
+// no PPM token. A per-session capability token in `Authorization` is its only credential.
+import { designMcpHandler } from "../services/design/mcp/design-mcp-endpoint.ts";
+import { setServerListenAddress } from "../services/server-listen-address.ts";
+app.all("/api/design-mcp", designMcpHandler);
+
 // Auth check endpoint (behind auth middleware)
 app.use("/api/*", authMiddleware);
 app.use("/api/*", gzipJson);
 app.get("/api/auth/check", (c) => c.json(ok(true)));
 app.route("/api/html-preview", htmlPreviewRoutes.api);
+app.route("/api/design-preview", designPreviewRoutes.api);
 
 // Port forwarding — starts per-port Cloudflare tunnels
 app.route("/api/preview", portForwardingRoutes);
@@ -1084,6 +1095,10 @@ if (process.argv.includes("__serve__")) {
     }, 200);
   }
 
+  // Child processes calling back into this server (the design MCP endpoint) need the
+  // port actually bound, which is not the configured one under the supervisor (port 0).
+  setServerListenAddress(Number(server.port), host);
+
   // Publish the port we actually bound so the edge forwarder knows where to
   // send traffic. Only meaningful when the supervisor spawned us with port 0
   // (OS-assigned); a dev server on a fixed port (e.g. `bun dev:server` on 8081)

package/src/server/routes/chat.ts

@@ -5,13 +5,14 @@ import { unlink } from "node:fs/promises";
 import { countLines } from "../../services/file-lines.ts";
 import { ensureUploadsDir, resolveUploadPath } from "../../services/chat-upload-storage.service.ts";
 import { chatService } from "../../services/chat.service.ts";
+import { isValidDesignSlug } from "../../services/design/design-slug.ts";
 import { draftService } from "../../services/draft.service.ts";
 import { providerRegistry } from "../../providers/registry.ts";
 import { renameSession as sdkRenameSession } from "@anthropic-ai/claude-agent-sdk";
 import { listSlashItems, searchSlashItems, invalidateCache } from "../../services/slash-items.service.ts";
 import type { SlashItem } from "../../services/slash-discovery/types.ts";
 import { ensureSdkCommands, invalidateSdkCommands } from "../../services/slash-discovery/sdk-commands.ts";
-import { upsertSlashRecent, getSlashRecents, setSessionClearedFrom, listTurnUsage, getSessionAccount, getSessionProvider, resolveMigratedSession } from "../../services/db.service.ts";
+import { upsertSlashRecent, getSlashRecents, setSessionClearedFrom, listTurnUsage, getSessionAccount, getSessionProvider, resolveMigratedSession, getSessionDesignSlugs, setSessionDesignSlug, copySessionDesignSettings } from "../../services/db.service.ts";
 import type { TurnUsage } from "../../shared/turn-usage.ts";
 import { getCachedUsage, refreshUsageNow } from "../../services/claude-usage.service.ts";
 import { bindPickedAccount, bindRefusalReason } from "../../services/picked-account-binding.ts";
@@ -166,7 +167,12 @@ chatRoutes.get("/usage", async (c) => {
 /** GET /chat/providers — list available AI providers */
 chatRoutes.get("/providers", (c) => {
   try {
-    return c.json(ok(providerRegistry.list()));
+    // The capability rides along so a client offering design sessions can list only the
+    // providers that will actually deliver the instructions.
+    return c.json(ok(providerRegistry.list().map((p) => ({
+      ...p,
+      supportsDesignInstructions: !!providerRegistry.get(p.id)?.supportsDesignInstructions,
+    }))));
   } catch (e) {
     return c.json(err((e as Error).message), 500);
   }
@@ -221,7 +227,10 @@ chatRoutes.get("/sessions", async (c) => {
     const seen = new Set<string>();
     const deduped = merged.filter((s) => { if (seen.has(s.id)) return false; seen.add(s.id); return true; });
     const tagMap = getSessionTags(deduped.map((s) => s.id));
-    const enriched = deduped.map((s) => ({ ...s, pinned: pinnedIds.has(s.id), tag: tagMap[s.id] ?? null }));
+    const designSlugs = getSessionDesignSlugs(deduped.map((s) => s.id));
+    const enriched = deduped.map((s) => ({
+      ...s, pinned: pinnedIds.has(s.id), tag: tagMap[s.id] ?? null, designSlug: designSlugs[s.id] ?? null,
+    }));
 
     // Collapse edit-message branch trees: each tree shows a single row (its
     // most recently active node). Pinned sessions are never collapsed.
@@ -314,6 +323,9 @@ chatRoutes.get("/search", async (c) => {
       });
     }
 
+    const designSlugs = getSessionDesignSlugs(results.map((r) => r.sessionId));
+    for (const r of results) r.designSlug = designSlugs[r.sessionId] ?? null;
+
     // Pinned first, then title matches above content, then most-recent within group.
     results.sort((a, b) => {
       if (a.pinned !== b.pinned) return a.pinned ? -1 : 1;
@@ -328,6 +340,16 @@ chatRoutes.get("/search", async (c) => {
 });
 
 /** GET /chat/sessions/:id/messages — get message history */
+/**
+ * The design a session belongs to, if any. A chat tab asks on open: every surface that opens
+ * sessions as plain chats (a notification, a search hit, a link) would otherwise take a design
+ * session out of design mode, and this lets the tab hand itself over to the design tab.
+ */
+chatRoutes.get("/sessions/:id/design", (c) => {
+  const id = c.req.param("id");
+  return c.json(ok({ designSlug: getSessionDesignSlugs([id])[id] ?? null }));
+});
+
 chatRoutes.get("/sessions/:id/messages", async (c) => {
   try {
     const requestedId = c.req.param("id");
@@ -371,13 +393,25 @@ chatRoutes.post("/sessions", async (c) => {
   try {
     const projectName = c.get("projectName");
     const projectPath = c.get("projectPath");
-    const body = await c.req.json<{ providerId?: string; title?: string; clearedFrom?: string; accountId?: string }>();
+    const body = await c.req.json<{ providerId?: string; title?: string; clearedFrom?: string; accountId?: string; designSlug?: unknown }>();
+    // A design session is only created on a provider that will carry its instructions;
+    // anywhere else it would silently be an ordinary chat that believes it is not.
+    const designSlug = body.designSlug;
+    if (designSlug !== undefined && designSlug !== null) {
+      if (!isValidDesignSlug(designSlug)) return c.json(err("Invalid designSlug"), 400);
+      const provider = body.providerId ? providerRegistry.get(body.providerId) : providerRegistry.getDefault();
+      if (!provider) return c.json(err(`Provider "${body.providerId}" not found`), 400);
+      if (!provider.supportsDesignInstructions) {
+        return c.json(err(`Provider "${provider.id}" does not support design sessions`), 400);
+      }
+    }
     const session = await chatService.createSession(body.providerId, {
       projectName,
       projectPath,
       title: body.title,
     });
     if (body.clearedFrom) setSessionClearedFrom(session.id, body.clearedFrom);
+    if (isValidDesignSlug(designSlug)) setSessionDesignSlug(session.id, designSlug);
     // The tab claimed an account when it opened and showed its name; honour that here so
     // the first message runs on the account the user was actually looking at. Advisory,
     // never authoritative: bindPickedAccount re-checks the id against the server's own
@@ -687,6 +721,8 @@ chatRoutes.post("/sessions/:id/fork", async (c) => {
         });
         // Register forked session with provider + DB so it's tracked in memory
         setSessionMetadata(result.sessionId, projectName, projectPath);
+        // Before the resume below: a fork of a design chat must stay a design chat.
+        copySessionDesignSettings(sourceId, result.sessionId);
         // Persist the inherited user-set title so the collapsed-tree head shows
         // it regardless of the SDK-derived summary.
         if (inheritedTitle) setSessionTitle(result.sessionId, inheritedTitle);
@@ -750,6 +786,7 @@ chatRoutes.post("/sessions/:id/fork", async (c) => {
         projectName, projectPath, title: inheritedTitle ?? "Forked Chat",
       });
       if (inheritedTitle) setSessionTitle(session.id, inheritedTitle);
+      copySessionDesignSettings(sourceId, session.id);
       return c.json(ok({ ...session, forkedFrom: sourceId }), 201);
     }
   } catch (e) {