@hienlh/ppm 0.23.10 → 0.23.12

package/src/services/android/sdk-discovery.ts

@@ -0,0 +1,178 @@
+/**
+ * Where the Android SDK is, and which of its tools this host actually has.
+ *
+ * Resolution order (plan §5): the path the user configured -> the standard Android env vars ->
+ * the per-OS default location -> whatever is on PATH. Everything here is read-only and safe to
+ * call when no SDK exists; the answer then carries the reasons, which is what the setup screen
+ * renders instead of an indefinite spinner.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join, resolve } from "node:path";
+
+export interface SdkTool {
+  /** Absolute path to the binary, or null when this host does not have it. */
+  path: string | null;
+  /** Version string as the tool itself reports it, when it could be run. */
+  version: string | null;
+}
+
+export interface AndroidSdk {
+  root: string | null;
+  /** Which step of the resolution order answered, for the setup screen to explain itself. */
+  source: "configured" | "env" | "default-location" | "path" | "not-found";
+  emulator: SdkTool;
+  adb: SdkTool;
+  avdmanager: SdkTool;
+  sdkmanager: SdkTool;
+  /** AVD home in force for this process, and whether it came from the environment. */
+  avdHome: string;
+  avdHomeFromEnv: boolean;
+}
+
+const exe = (name: string) => (platform() === "win32" ? `${name}.exe` : name);
+const bat = (name: string) => (platform() === "win32" ? `${name}.bat` : name);
+
+/** Per-OS default SDK locations, in the order Android's own tooling looks. */
+function defaultSdkLocations(): string[] {
+  const home = homedir();
+  switch (platform()) {
+    case "darwin":
+      return [join(home, "Library", "Android", "sdk")];
+    case "win32":
+      return [
+        join(process.env.LOCALAPPDATA ?? join(home, "AppData", "Local"), "Android", "Sdk"),
+      ];
+    default:
+      return [join(home, "Android", "Sdk"), join(home, "android-sdk")];
+  }
+}
+
+function looksLikeSdk(dir: string): boolean {
+  // An SDK root always has at least one of these; a bare directory that merely exists does not.
+  return existsSync(join(dir, "emulator")) || existsSync(join(dir, "platform-tools"));
+}
+
+/**
+ * The AVD home this process would use.
+ *
+ * `ANDROID_AVD_HOME` **replaces** the default rather than adding to it — measured: with it set,
+ * `emulator -list-avds` shows only the AVDs under it and the user's own disappear entirely. So
+ * PPM must never set it process-wide; it is read here only to report what is in force.
+ */
+export function resolveAvdHome(): { dir: string; fromEnv: boolean } {
+  const env = process.env.ANDROID_AVD_HOME?.trim();
+  if (env) return { dir: resolve(env), fromEnv: true };
+  return { dir: join(homedir(), ".android", "avd"), fromEnv: false };
+}
+
+/**
+ * The env an SDK **child process** needs to work in a given AVD home.
+ *
+ * `ANDROID_AVD_HOME` **replaces** the default rather than adding to it (measured in Phase 0), so
+ * PPM must never set it process-wide — but a child that is meant to act on a non-default home
+ * has no other way to be told. Measured the hard way: `avdmanager create avd` without this
+ * writes into **`~/.android/avd`**, i.e. straight into the user's own AVDs, whatever home PPM
+ * was asked to use.
+ *
+ * Left unset when the home already *is* the default, so the common case runs with the exact
+ * environment the tools expect.
+ */
+export function avdHomeEnv(avdHome: string): NodeJS.ProcessEnv {
+  const env = { ...process.env };
+  const defaultHome = join(homedir(), ".android", "avd");
+  if (avdHome && resolve(avdHome) !== defaultHome) env.ANDROID_AVD_HOME = resolve(avdHome);
+  return env;
+}
+
+async function toolVersion(path: string, args: string[], pick: (out: string) => string | null): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([path, ...args], { stdout: "pipe", stderr: "pipe", windowsHide: true });
+    const [out, errOut] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    await proc.exited;
+    return pick(`${out}\n${errOut}`);
+  } catch {
+    // Bun.spawn THROWS synchronously on a missing binary rather than reporting it (see
+    // `host-info/spawn-runner.ts`), and the throw escapes an awaited try placed further out.
+    return null;
+  }
+}
+
+function firstLine(out: string): string | null {
+  const line = out.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  return line ?? null;
+}
+
+async function describeTool(
+  candidate: string | null,
+  args: string[],
+  pick: (out: string) => string | null,
+): Promise<SdkTool> {
+  if (!candidate || !existsSync(candidate)) return { path: null, version: null };
+  return { path: candidate, version: await toolVersion(candidate, args, pick) };
+}
+
+/** Resolve the SDK and probe its tools. Never throws: a host with no SDK gets a populated shape. */
+export async function discoverSdk(configuredRoot?: string | null): Promise<AndroidSdk> {
+  let root: string | null = null;
+  let source: AndroidSdk["source"] = "not-found";
+
+  const configured = configuredRoot?.trim();
+  if (configured && looksLikeSdk(configured)) {
+    root = resolve(configured);
+    source = "configured";
+  }
+  if (!root) {
+    for (const key of ["ANDROID_HOME", "ANDROID_SDK_ROOT"]) {
+      const v = process.env[key]?.trim();
+      if (v && looksLikeSdk(v)) { root = resolve(v); source = "env"; break; }
+    }
+  }
+  if (!root) {
+    for (const dir of defaultSdkLocations()) {
+      if (looksLikeSdk(dir)) { root = dir; source = "default-location"; break; }
+    }
+  }
+
+  // PATH is the last resort and only for adb: a loose `adb` on PATH (Linux distros package it
+  // separately from the SDK) is usable even when no SDK root exists.
+  const pathAdb = Bun.which("adb");
+  if (!root && pathAdb) source = "path";
+
+  const emulatorPath = root ? join(root, "emulator", exe("emulator")) : null;
+  const adbPath = root && existsSync(join(root, "platform-tools", exe("adb")))
+    ? join(root, "platform-tools", exe("adb"))
+    : pathAdb;
+  const cmdlineBin = root ? join(root, "cmdline-tools", "latest", "bin") : null;
+
+  const [emulator, adb, avdmanager, sdkmanager] = await Promise.all([
+    describeTool(emulatorPath, ["-version"], (o) =>
+      o.split("\n").find((l) => l.includes("Android emulator version"))?.trim() ?? null),
+    describeTool(adbPath, ["version"], firstLine),
+    describeTool(cmdlineBin ? join(cmdlineBin, bat("avdmanager")) : null, ["list", "target"],
+      () => "present"),
+    describeTool(cmdlineBin ? join(cmdlineBin, bat("sdkmanager")) : null, ["--version"], firstLine),
+  ]);
+
+  const avdHome = resolveAvdHome();
+  return {
+    root, source, emulator, adb, avdmanager, sdkmanager,
+    avdHome: avdHome.dir, avdHomeFromEnv: avdHome.fromEnv,
+  };
+}
+
+/** Whether an AVD's config.ini enables the hardware keyboard. */
+export function avdHasHardwareKeyboard(avdConfigIni: string): boolean {
+  try {
+    for (const line of readFileSync(avdConfigIni, "utf8").split("\n")) {
+      const t = line.trim();
+      if (t.startsWith("hw.keyboard=")) return t.slice("hw.keyboard=".length).trim() === "yes";
+    }
+  } catch {
+    // An unreadable config is reported as "no" so the UI warns rather than promising a keyboard.
+  }
+  return false;
+}

package/src/services/android/system-images.ts

@@ -0,0 +1,124 @@
+/**
+ * Which Android system images this host already has.
+ *
+ * Read from **disk**, not from `sdkmanager --list_installed`. Three reasons, all measured:
+ *
+ *  - `sdkmanager` takes seconds ("Loading local repository…") and prints a progress bar into
+ *    stdout that any parser has to strip; a tab that lists images on open would stall on it.
+ *  - Every installed image ships a `source.properties` carrying exactly what is needed — API
+ *    level, ABI, tag, a display description — so the subprocess buys nothing.
+ *  - A host with the images but no `cmdline-tools` (they are a separate SDK package) can still
+ *    create an AVD, and going through `sdkmanager` would report "no images" there.
+ *
+ * Installing a *new* image is deliberately not here: the plan is explicit that PPM must not
+ * accept an SDK licence or start a multi-gigabyte download on its own.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+export interface SystemImage {
+  /** The sdkmanager package path, e.g. `system-images;android-35;google_apis_playstore;x86_64`. */
+  id: string;
+  apiLevel: number | null;
+  abi: string;
+  /** `google_apis_playstore`, `default`, `android-automotive`… */
+  tag: string;
+  /** What Google calls it, e.g. "Google APIs PlayStore,Tablet". */
+  tagDisplay: string;
+  description: string;
+  /** `image.sysdir.1` wants this exact relative form, trailing slash included. */
+  sysdir: string;
+  /** True when the image carries Play Store — such an AVD cannot be rooted. */
+  playStore: boolean;
+  bytes: number;
+}
+
+function parseProperties(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq <= 0) continue;
+    out[trimmed.slice(0, eq).trim()] = trimmed.slice(eq + 1).trim();
+  }
+  return out;
+}
+
+/** Recursive size of an image directory, so the UI can say what a delete would free. */
+function directoryBytes(dir: string, depth = 0): number {
+  if (depth > 4) return 0;
+  let total = 0;
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return 0; }
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    try {
+      if (entry.isDirectory()) total += directoryBytes(full, depth + 1);
+      else if (entry.isFile()) total += statSync(full).size;
+    } catch { /* it went away mid-walk */ }
+  }
+  return total;
+}
+
+/**
+ * The tree is `system-images/<api>/<tag>/<abi>/`, and only a directory with a
+ * `source.properties` counts — a half-deleted package leaves the directories behind.
+ */
+export function listSystemImages(sdkRoot: string | null): SystemImage[] {
+  if (!sdkRoot) return [];
+  const root = join(sdkRoot, "system-images");
+  if (!existsSync(root)) return [];
+
+  const images: SystemImage[] = [];
+  for (const api of safeList(root)) {
+    for (const tagDir of safeList(join(root, api))) {
+      for (const abi of safeList(join(root, api, tagDir))) {
+        const dir = join(root, api, tagDir, abi);
+        const propsPath = join(dir, "source.properties");
+        if (!existsSync(propsPath)) continue;
+
+        let props: Record<string, string>;
+        try { props = parseProperties(readFileSync(propsPath, "utf8")); } catch { continue; }
+
+        const apiLevel = Number(props["AndroidVersion.ApiLevel"]);
+        // `SystemImage.TagId` can be a comma list (`google_apis_playstore,tablet`); the first is
+        // the one the package path uses, and the rest are extra traits.
+        const tag = (props["SystemImage.TagId"] ?? tagDir).split(",")[0]!.trim();
+        images.push({
+          id: `system-images;${api};${tagDir};${abi}`,
+          apiLevel: Number.isFinite(apiLevel) ? apiLevel : null,
+          abi: props["SystemImage.Abi"] ?? abi,
+          tag,
+          tagDisplay: props["SystemImage.TagDisplay"] ?? tag,
+          description: props["Pkg.Desc"] ?? "",
+          sysdir: `system-images/${api}/${tagDir}/${abi}/`,
+          playStore: tagDir.includes("playstore") || tag.includes("playstore"),
+          bytes: directoryBytes(dir),
+        });
+      }
+    }
+  }
+  // Newest API first: that is almost always the one being reached for.
+  return images.sort((a, b) => (b.apiLevel ?? 0) - (a.apiLevel ?? 0) || a.id.localeCompare(b.id));
+}
+
+function safeList(dir: string): string[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Whether an image can run on this host without full-system emulation.
+ *
+ * An arm64 image on an x86_64 host boots, and then takes minutes per screen — which reads as a
+ * broken emulator rather than the wrong ABI, so the picker says so before the AVD exists.
+ */
+export function abiMatchesHost(abi: string, hostArch = process.arch): boolean {
+  if (hostArch === "x64") return abi === "x86_64" || abi === "x86";
+  if (hostArch === "arm64") return abi === "arm64-v8a" || abi === "armeabi-v7a";
+  return true;
+}

package/src/services/chat.service.ts

@@ -10,14 +10,23 @@ import type {
   ChatEvent,
   ChatMessage,
   SendMessageOpts,
+  PrewarmInput,
 } from "../providers/provider.interface.ts";
 import { compareSessionsByActivity } from "../types/chat.ts";
 import { buildDesignInstructions } from "./design/design-instructions.ts";
+import { resolveSystemForDesign } from "./design/design-systems.service.ts";
+import { ensureShowcaseDesign } from "./design/design-systems-showcase.ts";
+import { userDesignSectionFor } from "./design/design-user-section.ts";
 import { isValidDesignSlug } from "./design/design-slug.ts";
 import { scheduleTurnSnapshot } from "./design/design-turn-snapshot.ts";
 import { designMcpAccessFor } from "./design/mcp/design-mcp-access.ts";
 import { designMcpTokens } from "./design/mcp/design-mcp-tokens.ts";
 import { isTerminalAgentStatus } from "../shared/background-agent-status.ts";
+import { TraceRun, traceAbort, traceApproval, traceFollowUp } from "./session-trace/trace-recorder.ts";
+import type { TraceOrigin } from "../shared/session-trace.ts";
+
+/** What a caller passes to send: the provider's options plus which door the run came through. */
+export type ChatSendOpts = SendMessageOpts & { origin?: TraceOrigin };
 
 /**
  * Events after which a design session's files may have settled: the end of a turn, and a
@@ -62,6 +71,12 @@ class ChatService {
     return session;
   }
 
+  /** Start the process the next new chat in a project will run on, where the provider can. */
+  async prewarm(providerId: string | undefined, input: PrewarmInput): Promise<void> {
+    const provider = providerId ? providerRegistry.get(providerId) : providerRegistry.getDefault();
+    await provider?.prewarm?.(input);
+  }
+
   async resumeSession(
     providerId: string,
     sessionId: string,
@@ -107,18 +122,48 @@ class ChatService {
     return provider.deleteSession(sessionId);
   }
 
+  /**
+   * The one door every run goes through — WebSocket, scheduler, bots, group chat, Jira, CLI —
+   * which is why it is also where a run is written to the session trace. The trace observes
+   * and never alters: every event is yielded exactly as the provider produced it.
+   */
   async *sendMessage(
     providerId: string,
     sessionId: string,
     message: string,
-    opts?: SendMessageOpts,
+    opts?: ChatSendOpts,
+  ): AsyncIterable<ChatEvent> {
+    const { origin, ...sendOpts } = opts ?? {};
+    const run = new TraceRun({ sessionId, providerId, origin, message, opts: sendOpts });
+    let outcome: "completed" | "consumer_closed" | "failed" = "consumer_closed";
+    try {
+      yield* this.streamRun(run, providerId, sessionId, message, sendOpts);
+      outcome = "completed";
+    } catch (e) {
+      run.fail(e);
+      outcome = "failed";
+      throw e;
+    } finally {
+      run.end(outcome);
+    }
+  }
+
+  private async *streamRun(
+    run: TraceRun,
+    providerId: string,
+    sessionId: string,
+    message: string,
+    opts: SendMessageOpts,
   ): AsyncIterable<ChatEvent> {
     const provider = providerRegistry.get(providerId);
     if (!provider) {
-      yield { type: "error", message: `Provider "${providerId}" not found` };
+      const event: ChatEvent = { type: "error", message: `Provider "${providerId}" not found` };
+      run.observe(event);
+      yield event;
       return;
     }
     const prepared = await this.prepareSendOptions(providerId, sessionId, message, opts);
+    run.contextAdded(prepared.sharedContext, provider.supportsSharedContext ? "provider" : "message");
     this.rememberSharedContext(providerId, sessionId, prepared.sharedContext);
     let finished = false;
     let activeSessionId = sessionId;
@@ -153,6 +198,7 @@ class ChatService {
           // Not awaited: the snapshot is debounced and must never hold up or fail the turn.
           scheduleTurnSnapshot(activeSessionId, this.getSession(activeSessionId)?.projectPath);
         }
+        run.observe(event);
         yield event;
       }
       finished = true;
@@ -169,7 +215,7 @@ class ChatService {
     opts?: SendMessageOpts,
   ): Promise<SendMessageOpts> {
     if (!providerRegistry.get(providerId)) throw new Error(`Provider "${providerId}" not found`);
-    const design = await this.resolveDesignOptions(sessionId, opts);
+    const design = await this.resolveDesignOptions(providerId, sessionId, opts);
     let sharedContext: string | undefined;
     if (configService.get("ai").share_provider_context === false || /^\s*\/(compact|clear|new)(\s|$)/i.test(message)) {
       this.invalidateSharedContext(providerId, sessionId);
@@ -197,14 +243,16 @@ class ChatService {
    * CLI, the scheduler, group chat, the bots — sends through this service, and a design
    * session reached by any of them must get its instructions.
    *
-   * Instruction text is only ever built from the stored slug: anything a caller put in
-   * `designInstructions`/`designSession` is discarded, so no client text reaches the
-   * system prompt. A design session has no permission default of its own — an agent that
+   * Instruction text is only ever built from the stored slug and the owner's saved design
+   * instructions: anything a caller put in `designInstructions`/`designSession` is
+   * discarded, so no per-message client text reaches the system prompt. The saved
+   * instructions' skill mentions are resolved against the skills this provider can load for
+   * this project. A design session has no permission default of its own — an agent that
    * has to read and search the project to design for it would otherwise ask on every file.
    * An explicit caller mode wins (the user picked it), then the mode stored for the session,
    * then the provider's configured default, exactly as for any other chat.
    */
-  private async resolveDesignOptions(sessionId: string, opts?: SendMessageOpts): Promise<SendMessageOpts> {
+  private async resolveDesignOptions(providerId: string, sessionId: string, opts?: SendMessageOpts): Promise<SendMessageOpts> {
     const { designInstructions: _instructions, designSession: _flag, designMcp: _mcp, ...rest } = opts ?? {};
     const { getSessionDesignSlug, getSessionPermissionMode, getSessionProjectPath } = await import("./db.service.ts");
     const slug = getSessionDesignSlug(sessionId);
@@ -212,9 +260,23 @@ class ChatService {
     const permissionMode = opts?.permissionMode ?? getSessionPermissionMode(sessionId) ?? undefined;
     const projectPath = this.getSession(sessionId)?.projectPath ?? getSessionProjectPath(sessionId);
     const designMcp = designMcpAccessFor(sessionId, projectPath, slug);
+    const userSection = await userDesignSectionFor({ providerId, sessionId, projectPath, slug });
+    const system = projectPath
+      ? await resolveSystemForDesign(projectPath, slug)
+      : { id: "default", label: "Default", root: ".", platform: "web" as const, hasDesignMd: true };
+    if (projectPath && !system.hasDesignMd) {
+      // The instructions below are about to tell the agent it may write the showcase's
+      // index.html: make sure that design's folder and manifest exist first, server-side,
+      // so the agent only ever has to write the page itself.
+      try {
+        await ensureShowcaseDesign(projectPath, system.id);
+      } catch (e) {
+        console.warn(`[design] could not prepare the showcase for ${system.id}: ${(e as Error).message}`);
+      }
+    }
     return {
       ...rest,
-      designInstructions: buildDesignInstructions(slug, { checkTool: !!designMcp }),
+      designInstructions: buildDesignInstructions(slug, system, { checkTool: !!designMcp, userSection }),
       designSession: true,
       ...(designMcp ? { designMcp } : {}),
       ...(permissionMode ? { permissionMode } : {}),
@@ -222,20 +284,54 @@ class ChatService {
   }
 
   /** Push a live follow-up through the same context policy as sendMessage. */
-  async pushMessage(providerId: string, sessionId: string, message: string, opts?: SendMessageOpts): Promise<void> {
+  async pushMessage(providerId: string, sessionId: string, message: string, opts?: ChatSendOpts): Promise<void> {
     const provider = providerRegistry.get(providerId);
     if (!provider) throw new Error(`Provider "${providerId}" not found`);
     const streaming = provider as typeof provider & {
       pushMessage?: (id: string, content: string, options: SendMessageOpts) => void;
     };
     if (!streaming.pushMessage) return;
-    const prepared = await this.prepareSendOptions(providerId, sessionId, message, opts);
+    const { origin, ...sendOpts } = opts ?? {};
+    const prepared = await this.prepareSendOptions(providerId, sessionId, message, sendOpts);
+    // Written before the push, so the input precedes every event it causes in the trace.
+    traceFollowUp(sessionId, providerId, message, {
+      ...sendOpts,
+      origin,
+      sharedContext: prepared.sharedContext,
+      contextVia: provider.supportsSharedContext ? "provider" : "message",
+    });
     streaming.pushMessage(sessionId,
       provider.supportsSharedContext ? message : withSharedContext(message, prepared.sharedContext),
       { ...prepared, sharedContext: provider.supportsSharedContext ? prepared.sharedContext : undefined });
     this.rememberSharedContext(providerId, sessionId, prepared.sharedContext);
   }
 
+  /**
+   * Stop a session's query. An input to the run like a message is, so it goes through here
+   * rather than straight to the provider — otherwise the trace shows a turn that just stops.
+   */
+  abortQuery(providerId: string, sessionId: string, reason: string, origin?: TraceOrigin): void {
+    const provider = providerRegistry.get(providerId);
+    if (!provider?.abortQuery) return;
+    traceAbort(sessionId, providerId, reason, origin);
+    provider.abortQuery(sessionId, reason);
+  }
+
+  /** Answer an approval request or a question, and record the answer in the trace. */
+  resolveApproval(
+    providerId: string,
+    sessionId: string,
+    requestId: string,
+    approved: boolean,
+    data?: unknown,
+    extra: { reason?: string; origin?: TraceOrigin } = {},
+  ): void {
+    const provider = providerRegistry.get(providerId);
+    if (typeof provider?.resolveApproval !== "function") return;
+    traceApproval(sessionId, providerId, requestId, approved, { data, ...extra });
+    provider.resolveApproval(requestId, approved, data);
+  }
+
   /** Look up a session across all providers (for WS handler) */
   getSession(sessionId: string): Session | null {
     for (const info of providerRegistry.listAll()) {

package/src/services/config.service.ts

@@ -16,7 +16,7 @@ import {
 
 /** Top-level config keys stored in the config table (not projects) */
 const CONFIG_TABLE_KEYS: (keyof PpmConfig)[] = [
-  "device_name", "port", "host", "theme", "auth", "ai", "telegram", "clawbot", "query_audit", "tunnel",
+  "device_name", "port", "host", "theme", "auth", "ai", "telegram", "clawbot", "query_audit", "session_trace", "tunnel",
 ];
 
 /** File filter config keys stored in the config table */

package/src/services/design/design-edit-undo-journal.ts

@@ -119,6 +119,15 @@ export async function undoEdit(projectPath: string, slug: string, undoId: unknow
   });
 }
 
+/**
+ * Forget one design's journal. For an operation that replaces whole files (choosing a
+ * variant): a span recorded against the old page could otherwise still match text at the
+ * same offset of the new one and be "undone" into a page it never touched.
+ */
+export function forgetDesignEdits(projectPath: string, slug: string): void {
+  journals.delete(designLockKey(projectPath, slug));
+}
+
 /** Forget every journal; for tests. */
 export function resetDesignUndoJournals(): void {
   journals.clear();

package/src/services/design/design-instructions-auto-setup-block.ts

@@ -0,0 +1,36 @@
+import { DEFAULT_SYSTEM_ID } from "./design-systems-paths.ts";
+import { buildDesignSystemInitPrompt, type DesignSystemInitTarget } from "../../shared/design-system-init-prompt.ts";
+
+/**
+ * Added to a design's per-turn instructions only while its app has no `DESIGN.md` yet: most
+ * users do not know what a design system is, so nothing should ask them — the agent sets it
+ * up itself, in this same turn, before building what was actually asked for.
+ *
+ * The setup steps are `buildDesignSystemInitPrompt`'s own text, embedded verbatim (never
+ * copied into prose here), so the brief a user gets from the canvas "Set up design system"
+ * button and the one an agent follows here can never drift apart. This wrapper only adds the
+ * one-line user notice, the turn order (`design-instructions.ts` places it after the
+ * clarifying-questions guidance and before anything about building), and the one explicit
+ * exception to "Where to work" this turn needs — that section otherwise restricts an
+ * unprompted write to outside the design's own folder.
+ *
+ * Gone for good once `DESIGN.md` exists: `buildDesignInstructions` stops calling this the
+ * moment `hasDesignMd` is true, so a later turn — even a small edit — never sees it again,
+ * and the stale "Refresh design system" flow (re-running the same brief by hand from the
+ * showcase chat or the canvas More menu) is untouched by it.
+ */
+export function designAutoSetupBlock(target: DesignSystemInitTarget): string {
+  const outDir = target.id === DEFAULT_SYSTEM_ID ? "designs/" : `designs/systems/${target.id}/`;
+  const showcaseDir = `designs/system-${target.id}/`;
+  return `## This app has no design system yet
+Before your first build, set it up yourself, in this one turn — do not ask the user whether
+to do this, and do not wait for them to run it separately.
+- Tell the user, in one short line, that you are first setting up "${target.label}"'s design
+  system (a one-time step); then do the setup below; then build what they actually asked for,
+  using what you just set up.
+- The one exception to "Where to work" for this turn: \`${outDir}\` and
+  \`${showcaseDir}index.html\` are both writable, with no need to ask first — they are
+  outside this design's own folder, but setting the system up is what this turn is for.
+
+${buildDesignSystemInitPrompt(target)}`;
+}

package/src/services/design/design-instructions-system-block.ts

@@ -0,0 +1,49 @@
+import { DEFAULT_SYSTEM_ID } from "./design-systems-paths.ts";
+
+/** The subset of a design's app the instructions need; kept narrow so a caller need not load the rest. */
+export interface DesignInstructionsSystem {
+  id: string;
+  label: string;
+  root: string;
+  platform: "web" | "mobile";
+  /** False is what makes this design's own first turn set the system up itself (see `design-instructions.ts`). */
+  hasDesignMd: boolean;
+}
+
+/**
+ * The "design system" section of a design session's instructions, aimed at the design's own
+ * app: where to read its `DESIGN.md`/`tokens.css`/kit on disk (the legacy `designs/` root for
+ * `default`, `designs/systems/<id>/` for every other app), the `../systems/<id>/…` form to
+ * link them from the canvas, where the app's real source lives, and whether it is mobile.
+ */
+export function designSystemInstructionsBlock(system: DesignInstructionsSystem): string {
+  const fsPrefix = system.id === DEFAULT_SYSTEM_ID ? "designs/" : `designs/systems/${system.id}/`;
+  const previewPrefix = `../systems/${system.id}`;
+  const rootHint = system.root === "." ? "the project root" : `\`${system.root}\` (relative to the project root)`;
+  const platformHint = system.platform === "mobile"
+    ? "This app is mobile (React Native or similar): show the design in the phone frame and build it with native-looking components, not web chrome."
+    : "This app is a web app.";
+
+  return `## The design system (${system.label})
+- Before your first change, read \`${fsPrefix}DESIGN.md\` if it exists. It describes this
+  app's visual language (colours, type, spacing, components) and, once set up, a
+  \`## Screens and components\` map from each screen or component to its real source files.
+  Follow it.
+- If \`${fsPrefix}tokens.css\` exists, link it from the page with a relative path
+  (\`<link rel="stylesheet" href="${previewPrefix}/tokens.css">\`) and use its custom
+  properties rather than hard-coding the same values again.
+- If \`${fsPrefix}kit/app.css\` exists, link it too (\`<link rel="stylesheet" href="${previewPrefix}/kit/app.css">\`)
+  and build the markup with the app's own class names, not new utility classes the compiled
+  CSS does not have; use \`${previewPrefix}/kit/icons/<name>.svg\` for icons rather than
+  inventing your own. When the request is, or touches, a screen that already exists in the
+  app, read the source files the component map lists for it first and reproduce that
+  structure faithfully before changing anything — do not invent app chrome (navigation,
+  headers, layout) that is not in the source. For something genuinely new the kit has no
+  classes for, add a small \`<style>\` block in the design rather than a class the compiled
+  CSS lacks.
+- This app's real source lives at ${rootHint} — read it there to check how a screen is
+  really built, or anything else that helps the design match the product. ${platformHint}
+- If the user attached a screenshot of the real app, treat it as the target: after checking
+  your work (see below), compare its own screenshot against the one attached and fix visible
+  differences — layout, spacing, icons, type — before saying you are done.`;
+}