@uniqbit/mate-core 0.18.1-canary.4 → 0.18.1

package/src/cli/commands/studio/server.ts

@@ -1,14 +1,26 @@
 import {
   createStudioAccess,
   exchangeStudioToken,
+  normalizeOrigin,
+  readBearer,
   studioAddress,
   type StudioAccess,
   type StudioInvocation,
 } from "./access";
 import { collectStudioInventory, type StudioInventory } from "./inventory";
 import { assembleCompanionPayload, type StudioCompanionResponse } from "./payload";
-import { STUDIO_HOSTNAME } from "./routes";
+import { createReportStore, isReportId, REPORT_LIMITS, type ReportStore } from "./reports";
 import {
+  REPORTS_ROUTE,
+  REPORT_VIEW_PREFIX,
+  STUDIO_HOSTNAME,
+  VAULT_CHANGES_ROUTE,
+  VAULT_DIR_ROUTE,
+  VAULT_FILTER_ROUTE,
+} from "./routes";
+import {
+  COMPANION_DIGEST_PATTERN,
+  COMPANION_PARAM,
   companionDigest,
   parse,
   parseVaultSelection,
@@ -92,6 +104,7 @@ export interface StudioServerDeps {
   serve?: (options: StudioServeOptions) => StudioBoundServer;
   snapshots?: StudioSnapshotCache;
   vault?: VaultManager;
+  reports?: ReportStore;
   terminal?: Partial<TerminalRegistryOptions>;
   launchableAgents?: typeof launchableAgents;
 }
@@ -129,6 +142,16 @@ async function renderVaultView(page: StudioPage): Promise<string> {
   return views.renderVaultView(page);
 }
 
+async function renderVaultChildren(page: StudioPage): Promise<string | null> {
+  const views = await import("./views/document");
+  return views.renderVaultChildren(page);
+}
+
+async function renderVaultMatches(page: StudioPage, query: string): Promise<string> {
+  const views = await import("./views/document");
+  return views.renderVaultMatches(page, query);
+}
+
 /** Keep the CLI entry free of eager Studio view imports. */
 async function collectVaultState(
   vault: VaultManager,
@@ -166,6 +189,57 @@ function refused(reason: string, status: number): Response {
   });
 }
 
+/** Sent with every hosted report: opaque origin, no connections, no Studio cookie or storage. */
+const REPORT_CSP = [
+  "sandbox allow-scripts allow-modals",
+  "default-src 'none'",
+  "script-src 'unsafe-inline'",
+  "style-src 'unsafe-inline'",
+  "img-src data:",
+  "font-src data:",
+  "connect-src 'none'",
+].join("; ");
+
+/** Page-facing report announcement; carries no path and no content. */
+interface ReportPublishedEvent {
+  type: "report-published";
+  /** Digest of the companion the report belongs to. */
+  companion: string;
+  id: string;
+  title: string;
+  createdAt: number;
+}
+
+/**
+ * The body as text, or `null` over `limit`. An oversized body is drained unparsed
+ * and unbuffered (up to a hard bound): answering before the client finished
+ * sending wedges its keep-alive connection.
+ */
+async function readCapped(request: Request, limit: number): Promise<string | null> {
+  if (!request.body) return "";
+  const declared = Number(request.headers.get("content-length"));
+  const reader = request.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  let over = Number.isFinite(declared) && declared > limit;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) over = true;
+    if (over) {
+      chunks.length = 0;
+      if (size > limit * 4) {
+        await reader.cancel();
+        break;
+      }
+    } else {
+      chunks.push(value);
+    }
+  }
+  return over ? null : Buffer.concat(chunks).toString("utf8");
+}
+
 const TOKEN_REASON =
   "Studio's access token is required; open the address Studio printed when it started";
 
@@ -187,6 +261,10 @@ export interface StudioFetchOptions extends Pick<
   "writable" | "launchCompanion" | "noGit" | "detachMinutes"
 > {
   access?: StudioAccess;
+  /** Loopback origin the terminal's processes publish to; read at spawn. */
+  reportOrigin?: () => string | null;
+  /** The only origin an absolute report URL is built from. */
+  publicOrigin?: string | null;
   /** Enables the terminal; the invocation sets its default detach window. */
   terminal?: boolean;
 }
@@ -219,6 +297,10 @@ export function createStudioFetch(
       hostname: STUDIO_HOSTNAME,
       port: () => 80,
     });
+  const reports = deps.reports ?? createReportStore();
+  void reports.cleanup().catch(() => {});
+  const publicOrigin = options.publicOrigin ? normalizeOrigin(options.publicOrigin) : null;
+  const reportListeners = new Map<string, Set<(event: ReportPublishedEvent) => void>>();
   const launchCompanion = options.launchCompanion ?? null;
   const agentsFor = deps.launchableAgents ?? launchableAgents;
   const terminal = options.terminal
@@ -231,10 +313,55 @@ export function createStudioFetch(
         }),
         mateCommand: process.argv.slice(0, 2),
         noGit: options.noGit === true,
+        reportUrl: options.reportOrigin,
         ...deps.terminal,
       })
     : null;
 
+  /** Stores a report for the live terminal session holding the bearer credential. */
+  const publishReport = async (request: Request): Promise<Response> => {
+    const token = readBearer(request);
+    const companionPath = token ? (terminal?.reportCompanion(token) ?? null) : null;
+    if (!companionPath) return refused("a live Studio session's credential is required", 401);
+    const raw = await readCapped(request, REPORT_LIMITS.uploadBytes);
+    if (raw === null) return json({ reason: "the report exceeds the size limit" }, 413);
+    let body: { title?: unknown; html?: unknown };
+    try {
+      body = JSON.parse(raw) as typeof body;
+    } catch {
+      return json({ reason: "publishing requires a JSON body" }, 400);
+    }
+    if (
+      !body ||
+      typeof body !== "object" ||
+      typeof body.title !== "string" ||
+      typeof body.html !== "string" ||
+      !body.html
+    ) {
+      return json({ reason: "a report needs a string title and html" }, 400);
+    }
+    const digest = companionDigest(companionPath);
+    const stored = await reports.publish(digest, {
+      title: body.title.slice(0, 200),
+      html: body.html,
+    });
+    for (const notify of reportListeners.get(digest) ?? []) {
+      notify({
+        type: "report-published",
+        companion: digest,
+        id: stored.id,
+        title: stored.title,
+        createdAt: stored.createdAt,
+      });
+    }
+    const path = `${REPORT_VIEW_PREFIX}${stored.id}`;
+    return json({
+      id: stored.id,
+      path,
+      ...(publicOrigin ? { url: `${publicOrigin}${path}` } : {}),
+    });
+  };
+
   const handler = async (
     request: Request,
     server?: StudioUpgrader,
@@ -246,6 +373,10 @@ export function createStudioFetch(
     const exchanged = exchangeStudioToken(request, access, acceptedOrigin);
     if (exchanged) return exchanged;
 
+    if (url.pathname === REPORTS_ROUTE && request.method === "POST") {
+      return publishReport(request);
+    }
+
     const isSave = url.pathname === "/api/vault/save";
     const isEnd = url.pathname === "/api/terminal/sessions/end";
     const isPost = isSave || isEnd;
@@ -275,6 +406,31 @@ export function createStudioFetch(
       return respond(refused(TOKEN_REASON, 401));
     }
 
+    if (url.pathname === REPORTS_ROUTE) {
+      const digest = url.searchParams.get(COMPANION_PARAM) ?? "";
+      if (!COMPANION_DIGEST_PATTERN.test(digest)) {
+        return respond(json({ reason: "no registered companion was selected" }, 400));
+      }
+      return respond(json({ reports: await reports.list(digest) }));
+    }
+
+    if (url.pathname.startsWith(REPORT_VIEW_PREFIX)) {
+      const id = url.pathname.slice(REPORT_VIEW_PREFIX.length);
+      const stored = isReportId(id) ? await reports.read(id) : null;
+      if (stored === null) return respond(new Response("not found", { status: 404 }));
+      return respond(
+        new Response(stored, {
+          headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            "content-security-policy": REPORT_CSP,
+            "x-content-type-options": "nosniff",
+            "referrer-policy": "no-referrer",
+          },
+        }),
+      );
+    }
+
     if (url.pathname.startsWith("/studio/terminal/") && terminal) {
       const asset = await terminalAsset(url.pathname);
       if (asset) return respond(asset);
@@ -367,6 +523,74 @@ export function createStudioFetch(
       );
     }
 
+    if (url.pathname === VAULT_DIR_ROUTE || url.pathname === VAULT_FILTER_ROUTE) {
+      const selection = parseVaultSelection(url);
+      const selected = await selectedCompanion(selection.companionDigest, inventory);
+      if (!selected) return respond(json({ reason: "no registered companion was selected" }, 400));
+      let listed;
+      try {
+        listed = await vault.tree(selected.path);
+      } catch (error) {
+        return respond(
+          json({ reason: error instanceof Error ? error.message : String(error) }, 400),
+        );
+      }
+      const page: StudioPage = {
+        inventory: await inventory(),
+        selection,
+        companion: selected,
+        payload: null,
+        error: null,
+        collectedAt: null,
+        writable,
+        vault: {
+          tree: listed.tree,
+          open: null,
+          refusal: null,
+          incoming: null,
+          overwritten: null,
+          watching: listed.watching,
+          warning: listed.warning,
+          generation: listed.generation,
+        },
+        terminal: null,
+      };
+      const headers = {
+        "content-type": "text/html; charset=utf-8",
+        "cache-control": "no-store",
+        "x-vault-generation": String(listed.generation),
+      };
+      if (url.pathname === VAULT_FILTER_ROUTE) {
+        const matches = await renderVaultMatches(page, url.searchParams.get("q") ?? "");
+        return respond(new Response(matches, { headers }));
+      }
+      const children = await renderVaultChildren(page);
+      if (children === null) {
+        return respond(json({ reason: "that folder is not in the listed tree" }, 404));
+      }
+      return respond(new Response(children, { headers }));
+    }
+
+    if (url.pathname === VAULT_CHANGES_ROUTE) {
+      const selection = parseVaultSelection(url);
+      const selected = await selectedCompanion(selection.companionDigest, inventory);
+      if (!selected) return respond(json({ reason: "no registered companion was selected" }, 400));
+      server?.timeout?.(request, 0);
+      const reportsOnly = url.searchParams.get("scope") === "reports";
+      return respond(
+        changeStream(vault, selected.path, reportsOnly, (notify) => {
+          const digest = companionDigest(selected.path);
+          const set = reportListeners.get(digest) ?? new Set();
+          set.add(notify);
+          reportListeners.set(digest, set);
+          return () => {
+            set.delete(notify);
+            if (set.size === 0) reportListeners.delete(digest);
+          };
+        }),
+      );
+    }
+
     if (url.pathname === "/api/vault/file") {
       const selection = parseVaultSelection(url);
       const selected = await selectedCompanion(selection.companionDigest, inventory);
@@ -465,13 +689,17 @@ async function selectedCompanion(
   return resolveCompanion(await collectInventory(), digest);
 }
 
-function vaultEvents(vault: VaultManager, companionPath: string, requestedPath: string): Response {
+/** Server-sent events: `subscribe` gets a send function and returns its unsubscribe. */
+function eventStream(
+  greeting: string,
+  subscribe: (send: (event: unknown) => void) => () => void,
+): Response {
   const encoder = new TextEncoder();
   let unsubscribe = () => {};
   const stream = new ReadableStream<Uint8Array>({
     start(controller) {
-      controller.enqueue(encoder.encode(": studio vault events\n\n"));
-      unsubscribe = vault.subscribe(companionPath, requestedPath, (event) => {
+      controller.enqueue(encoder.encode(`: ${greeting}\n\n`));
+      unsubscribe = subscribe((event) => {
         try {
           controller.enqueue(encoder.encode(`data: ${JSON.stringify(event)}\n\n`));
         } catch {
@@ -492,6 +720,37 @@ function vaultEvents(vault: VaultManager, companionPath: string, requestedPath:
   });
 }
 
+function vaultEvents(vault: VaultManager, companionPath: string, requestedPath: string): Response {
+  return eventStream("studio vault events", (send) =>
+    vault.subscribe(companionPath, requestedPath, send),
+  );
+}
+
+/**
+ * Typed events for one companion: `vault-tree-changed` (a generation) and
+ * `report-published`. No paths and no file content leave through this stream.
+ * `reportsOnly` skips the vault subscription, which starts a watcher and listing.
+ */
+function changeStream(
+  vault: VaultManager,
+  companionPath: string,
+  reportsOnly: boolean,
+  subscribeReports: (notify: (event: ReportPublishedEvent) => void) => () => void,
+): Response {
+  return eventStream("studio changes", (send) => {
+    const stopReports = subscribeReports(send);
+    const stopTree = reportsOnly
+      ? () => {}
+      : vault.subscribeTree(companionPath, (generation) =>
+          send({ type: "vault-tree-changed", generation }),
+        );
+    return () => {
+      stopReports();
+      stopTree();
+    };
+  });
+}
+
 /**
  * One rendered document's worth of state. An absent or unresolvable companion
  * is not a failure: the page renders the selector and the server keeps serving.
@@ -563,6 +822,17 @@ function bunServe(options: StudioServeOptions): StudioBoundServer {
   return runtime.serve(options);
 }
 
+/** Where a process on this host reaches the server: loopback for wildcard binds. */
+function reportOrigin(hostname: string, port: number): string {
+  const wildcard = hostname === "0.0.0.0" || hostname === "::" || hostname === "[::]";
+  const host = wildcard
+    ? "127.0.0.1"
+    : hostname.includes(":") && !hostname.startsWith("[")
+      ? `[${hostname}]`
+      : hostname;
+  return `http://${host}:${port}`;
+}
+
 /**
  * A bind failure propagates: the caller reports it and exits rather than
  * opening a browser at a URL nothing answers.
@@ -587,6 +857,8 @@ export function startStudioServer(
   const fetchHandler = createStudioFetch(deps, {
     writable: options.writable,
     access,
+    publicOrigin: options.publicOrigin,
+    reportOrigin: () => reportOrigin(hostname, boundPort),
     terminal: options.terminal === true,
     detachMinutes: options.detachMinutes,
     launchCompanion: options.launchCompanion,

package/src/cli/commands/studio/terminal-launch.ts

@@ -4,10 +4,14 @@ import path from "node:path";
 import { FRAMEWORK_NAME } from "../../../framework";
 import { ConfigStore, mergeWithDefaults } from "../../../lib/orchestrator/config-store";
 import type { StudioInventory, StudioInventoryCompanion } from "./inventory";
+import { findAction, promptArgs, skillInstalledFor, SUBJECT_PATTERN } from "./actions";
+import { collectSkillInventory, type StudioSkillInventory } from "./mate-inventory";
+import { listSpecs } from "./openspec-cli";
 import { resolveCompanion } from "./selection";
 import {
   agentInstalled,
   TERMINAL_AGENTS,
+  type TerminalAction,
   type TerminalAgent,
   type TerminalLaunchResolution,
 } from "./terminal";
@@ -77,6 +81,14 @@ export interface LaunchResolverOptions {
   launchCompanion?: string | null;
   launchableAgents?: (companionPath: string) => Promise<TerminalAgent[]>;
   defaultAgent?: (companionPath: string, agent: TerminalAgent) => Promise<DefaultAgentOutcome>;
+  skillInventory?: (companionPath: string) => Promise<StudioSkillInventory>;
+  /** Whether the companion has a canonical spec for this capability, read at launch. */
+  specExists?: (companionPath: string, capability: string) => Promise<boolean>;
+}
+
+async function specInCompanion(companionPath: string, capability: string): Promise<boolean> {
+  const result = await listSpecs(companionPath);
+  return result.ok && (result.value.specs ?? []).some((spec) => spec.id === capability);
 }
 
 /** The companion a launch targets: the pinned one, else the page's, both read from the current inventory. */
@@ -94,10 +106,16 @@ export async function effectiveLaunchCompanion(
 /** Revalidates at launch time; the rendered page and its digest are never trusted. */
 export function createLaunchResolver(
   options: LaunchResolverOptions,
-): (agent: string, digest: string | null) => Promise<TerminalLaunchResolution> {
+): (
+  agent: string,
+  digest: string | null,
+  action?: TerminalAction,
+) => Promise<TerminalLaunchResolution> {
   const agents = options.launchableAgents ?? launchableAgents;
   const defaultAgent = options.defaultAgent ?? defaultAgentFor;
-  return async (agent, digest) => {
+  const skills = options.skillInventory ?? collectSkillInventory;
+  const specExists = options.specExists ?? specInCompanion;
+  return async (agent, digest, request) => {
     const companion = await effectiveLaunchCompanion(
       await options.collectInventory(),
       options.launchCompanion,
@@ -113,9 +131,26 @@ export function createLaunchResolver(
     if (!(await agents(companion.path)).includes(agent as TerminalAgent)) {
       return { reason: `${agent} is not allowed by this companion or is not installed` };
     }
-    return {
+    const launch = {
       companionPath: companion.path,
       ...(await defaultAgent(companion.path, agent as TerminalAgent)),
     };
+    if (!request) return launch;
+
+    const action = findAction(request.action);
+    if (!action) return { reason: "the requested action is not registered" };
+    const subject = request.subject;
+    if (typeof subject !== "string" || !SUBJECT_PATTERN.test(subject)) {
+      return { reason: "the action subject is not a valid spec name" };
+    }
+    if (!skillInstalledFor(await skills(companion.path), action.skill, agent as TerminalAgent)) {
+      return {
+        reason: `the ${action.skill} skill is not installed for ${agent} in this companion`,
+      };
+    }
+    if (!(await specExists(companion.path, subject))) {
+      return { reason: `this companion has no spec named ${subject}` };
+    }
+    return { ...launch, promptArgs: promptArgs(action, agent as TerminalAgent, subject) };
   };
 }

package/src/cli/commands/studio/terminal.ts

@@ -1,4 +1,6 @@
-import { randomUUID } from "node:crypto";
+import { randomBytes, randomUUID } from "node:crypto";
+
+import { tokensEqual } from "./access";
 
 export const TERMINAL_AGENTS = ["claude", "opencode"] as const;
 export type TerminalAgent = (typeof TERMINAL_AGENTS)[number];
@@ -177,11 +179,19 @@ export interface TerminalSessionInfo {
   startedAt: number;
 }
 
+/** A registered action and its subject; the client names them, the server builds the prompt. */
+export interface TerminalAction {
+  action: unknown;
+  subject: unknown;
+}
+
 export type TerminalLaunchResolution =
   | {
       companionPath: string;
       /** Extra argv entries for the managed launch; set only by companion configuration. */
       agentArgs?: string[];
+      /** The registry's first-turn prompt, appended after `agentArgs`; never from the client. */
+      promptArgs?: string[];
       /** Written to the terminal before the agent starts. */
       notice?: string;
     }
@@ -193,10 +203,13 @@ export interface TerminalRegistryOptions {
   resolveLaunch: (
     agent: string,
     companionDigest: string | null,
+    action?: TerminalAction,
   ) => Promise<TerminalLaunchResolution>;
   /** The Mate invocation prefix, e.g. `[bun, cli.mjs]`. */
   mateCommand: string[];
   noGit?: boolean;
+  /** Loopback origin of this server, read at spawn: the port is known only after bind. */
+  reportUrl?: () => string | null;
   env?: NodeJS.ProcessEnv;
   spawn?: TerminalSpawn;
   signalGroup?: (pid: number, signal: NodeJS.Signals) => void;
@@ -209,6 +222,8 @@ interface Session {
   agent: TerminalAgent;
   companionPath: string;
   startedAt: number;
+  /** In memory only; valid while the session is registered. */
+  reportToken: string;
   process: TerminalProcess;
   ring: RingBuffer;
   viewer: TerminalViewer | null;
@@ -273,6 +288,15 @@ export class TerminalRegistry {
     }));
   }
 
+  /** The companion of the live session holding this publish credential, else `null`. */
+  reportCompanion(token: string): string | null {
+    let found: string | null = null;
+    for (const session of this.sessions.values()) {
+      if (!session.ending && tokensEqual(token, session.reportToken)) found = session.companionPath;
+    }
+    return found;
+  }
+
   connect(viewer: TerminalViewer): TerminalConnection {
     const connection: Connection = { viewer, lastPong: this.now(), session: null };
     this.connections.add(connection);
@@ -370,7 +394,13 @@ export class TerminalRegistry {
     const viewer = connection.viewer;
     if (this.stopping) return send(viewer, { type: "error", reason: "Studio is stopping" });
     if (connection.session) {
-      return send(viewer, { type: "error", reason: "this connection already views a session" });
+      return send(viewer, {
+        type: "error",
+        reason:
+          message.action === undefined && message.subject === undefined
+            ? "this connection already views a session"
+            : "end the current session first",
+      });
     }
     const size = this.dimensions(message);
     if (!size) return send(viewer, { type: "error", reason: "terminal size out of range" });
@@ -379,7 +409,11 @@ export class TerminalRegistry {
     }
     const agent = message.agent as TerminalAgent;
     const digest = typeof message.companion === "string" ? message.companion : null;
-    const resolved = await this.options.resolveLaunch(agent, digest);
+    const action =
+      message.action === undefined && message.subject === undefined
+        ? undefined
+        : { action: message.action, subject: message.subject };
+    const resolved = await this.options.resolveLaunch(agent, digest, action);
     if ("reason" in resolved) return send(viewer, { type: "error", reason: resolved.reason });
     if (connection.session || !this.connections.has(connection)) return;
 
@@ -404,7 +438,7 @@ export class TerminalRegistry {
     agent: TerminalAgent,
     companionPath: string,
     size: { cols: number; rows: number },
-    extras: { agentArgs?: string[]; notice?: string } = {},
+    extras: { agentArgs?: string[]; promptArgs?: string[]; notice?: string } = {},
   ): Session {
     const env: Record<string, string> = {};
     for (const [key, value] of Object.entries(this.options.env ?? process.env)) {
@@ -413,6 +447,14 @@ export class TerminalRegistry {
     delete env.MATE_REPO_PATH;
     delete env.MATE_REPO_ID;
     delete env.MATE_STUDIO_TOKEN;
+    delete env.MATE_STUDIO_REPORT_URL;
+    delete env.MATE_STUDIO_REPORT_TOKEN;
+    const reportToken = randomBytes(32).toString("base64url");
+    const reportUrl = this.options.reportUrl?.() ?? null;
+    if (reportUrl) {
+      env.MATE_STUDIO_REPORT_URL = reportUrl;
+      env.MATE_STUDIO_REPORT_TOKEN = reportToken;
+    }
     env.MATE_ARTIFACT_PATH = companionPath;
     env.TERM = "xterm-256color";
     const argv = [
@@ -423,6 +465,7 @@ export class TerminalRegistry {
       "--yes",
       ...(this.options.noGit ? ["--no-git"] : []),
       ...(extras.agentArgs ?? []),
+      ...(extras.promptArgs ?? []),
     ];
 
     const session = {
@@ -430,6 +473,7 @@ export class TerminalRegistry {
       agent,
       companionPath,
       startedAt: this.now(),
+      reportToken,
       ring: new RingBuffer(this.limits.ringBytes),
       viewer: null,
       detachedAt: null,