@prismshadow/penguin-server 0.1.1 → 0.1.2

package/dist/index.js

@@ -6,7 +6,7 @@ import { serve } from "@hono/node-server";
 import fs16 from "fs";
 import fsp from "fs/promises";
 import path15 from "path";
-import { Hono as Hono19 } from "hono";
+import { Hono as Hono20 } from "hono";
 
 // src/db/database.ts
 import { mkdirSync } from "fs";
@@ -1154,6 +1154,12 @@ function optionalNumber(obj, key, rule = {}) {
   if (rule.nonNegative && v < 0) throw badRequest(`${label} must not be negative.`);
   return v;
 }
+function optionalBoolean(obj, key, label = key) {
+  const v = obj[key];
+  if (v === void 0) return void 0;
+  if (typeof v !== "boolean") throw badRequest(`${label} must be a boolean.`);
+  return v;
+}
 function optionalDateParam(value, label) {
   if (value === void 0 || value === "") return void 0;
   const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
@@ -1233,10 +1239,111 @@ function authRoutes(deps2) {
 
 // src/http/routes/me.ts
 import { Hono as Hono3 } from "hono";
+
+// src/services/preview-token.ts
+import { createHmac, randomBytes as randomBytes3, timingSafeEqual as timingSafeEqual2 } from "crypto";
+var PREVIEW_TOKEN_TTL_MS = 10 * 60 * 1e3;
+function b64url(buf) {
+  return buf.toString("base64url");
+}
+function createPreviewTokenSigner(secret = randomBytes3(32)) {
+  const mac = (body) => createHmac("sha256", secret).update(body).digest();
+  return {
+    sign(payload) {
+      const body = b64url(Buffer.from(JSON.stringify(payload), "utf8"));
+      return `${body}.${b64url(mac(body))}`;
+    },
+    verify(token) {
+      const dot = token.indexOf(".");
+      if (dot <= 0 || dot === token.length - 1) return null;
+      const body = token.slice(0, dot);
+      const provided = Buffer.from(token.slice(dot + 1), "base64url");
+      const expected = mac(body);
+      if (provided.length !== expected.length || !timingSafeEqual2(provided, expected)) return null;
+      let payload;
+      try {
+        payload = JSON.parse(
+          Buffer.from(body, "base64url").toString("utf8")
+        );
+      } catch {
+        return null;
+      }
+      if (typeof payload?.sessionId !== "string" || typeof payload?.host !== "string" || typeof payload?.expiresAt !== "number") {
+        return null;
+      }
+      if (Date.now() >= payload.expiresAt) return null;
+      return payload;
+    }
+  };
+}
+function hostOnly(hostHeader) {
+  const trimmed = hostHeader.trim();
+  if (trimmed.startsWith("[")) {
+    const end = trimmed.indexOf("]");
+    return end === -1 ? trimmed : trimmed.slice(0, end + 1);
+  }
+  const colon = trimmed.lastIndexOf(":");
+  return colon === -1 ? trimmed : trimmed.slice(0, colon);
+}
+function loopbackCounterpart(host) {
+  const h = host.toLowerCase();
+  if (h === "127.0.0.1") return "localhost";
+  if (h === "localhost") return "127.0.0.1";
+  if (h === "[::1]") return "127.0.0.1";
+  return null;
+}
+function loopbackHostRoles(bindHost) {
+  const h = bindHost.trim().toLowerCase();
+  if (h !== "127.0.0.1" && h !== "localhost") return null;
+  const app2 = "localhost";
+  const preview = loopbackCounterpart(app2);
+  if (!preview) return null;
+  return { app: app2, preview };
+}
+function requestAuthority(requestUrl, hostHeader) {
+  const header = (hostHeader ?? "").trim();
+  if (header !== "") return header;
+  try {
+    return new URL(requestUrl).host;
+  } catch {
+    return "";
+  }
+}
+function resolvePreviewTarget(requestUrl, hostHeader, configuredOrigin, serverBind) {
+  const requestHost = hostOnly(requestAuthority(requestUrl, hostHeader)).toLowerCase();
+  if (configuredOrigin) {
+    const url = new URL(configuredOrigin);
+    if (url.hostname.toLowerCase() === requestHost) return null;
+    return { origin: url.origin, host: url.hostname };
+  }
+  if (requestHost === "") return null;
+  const counterpart = loopbackCounterpart(requestHost);
+  if (!counterpart) return null;
+  if (!loopbackHostRoles(serverBind.host)) return null;
+  let protocol;
+  try {
+    protocol = new URL(requestUrl).protocol;
+  } catch {
+    protocol = "http:";
+  }
+  const suffix = protocol === "http:" && serverBind.port === 80 || protocol === "https:" && serverBind.port === 443 ? "" : `:${serverBind.port}`;
+  return { origin: `${protocol}//${counterpart}${suffix}`, host: counterpart };
+}
+
+// src/http/routes/me.ts
 function meRoutes(deps2) {
   const app2 = new Hono3();
   app2.get("/", (c) => {
-    return c.json({ user: toUserInfo(c.var.user) });
+    const target = resolvePreviewTarget(
+      c.req.url,
+      c.req.header("host"),
+      deps2.config.previewOrigin,
+      deps2.config
+    );
+    return c.json({
+      user: toUserInfo(c.var.user),
+      previewIsolated: target !== null
+    });
   });
   app2.put("/password", async (c) => {
     const body = await readJson(c);
@@ -2287,6 +2394,17 @@ function agentConfigRoutes(deps2) {
       activeSessionCount: deps2.manager.activeCountForAgent(projectId, agentId)
     });
   });
+  app2.post("/reset", async (c) => {
+    const projectId = requireValidId(c, "projectId");
+    const agentId = requireValidId(c, "agentId");
+    deps2.projectService.requireProjectAccess(c.var.user.userId, projectId);
+    await deps2.agentConfigService.resetConfig(projectId, agentId);
+    const view = await deps2.agentConfigService.getConfig(projectId, agentId);
+    return c.json({
+      ...view,
+      activeSessionCount: deps2.manager.activeCountForAgent(projectId, agentId)
+    });
+  });
   return app2;
 }
 
@@ -2647,6 +2765,13 @@ var APPROVAL_MODES = [
   "read-only",
   "always-ask"
 ];
+var THINKING_LEVELS = ["none", "low", "medium", "high", "xhigh"];
+var SESSION_CATEGORIES = [
+  "active",
+  "subagent",
+  "schedule",
+  "archived"
+];
 function parseTaskInput(body) {
   const input = body.input;
   if (!Array.isArray(input) || input.length === 0) {
@@ -2681,12 +2806,26 @@ function agentSessionsRoutes(deps2) {
     deps2.projectService.requireProjectAccess(c.var.user.userId, projectId);
     await deps2.agentConfigService.requireExists(projectId, agentId);
     const paging = optionalPagingQuery(c);
-    const sessions = await deps2.sessionService.listSessions(
+    const rawCategory = c.req.query("category");
+    if (rawCategory !== void 0 && !SESSION_CATEGORIES.includes(rawCategory)) {
+      throw badRequest(`category must be one of ${SESSION_CATEGORIES.join(" / ")}.`);
+    }
+    const rawCounts = c.req.query("counts");
+    if (rawCounts !== void 0 && rawCounts !== "1") throw badRequest("counts only accepts 1.");
+    const { sessions, counts, workspaceCounts } = await deps2.sessionService.listSessions(
       projectId,
       agentId,
-      ...paging ? [paging] : []
+      {
+        ...paging ? { paging } : {},
+        ...rawCategory !== void 0 ? { category: rawCategory } : {},
+        ...rawCounts !== void 0 ? { withCounts: true } : {}
+      }
     );
-    return c.json({ sessions });
+    return c.json({
+      sessions,
+      ...counts ? { counts } : {},
+      ...workspaceCounts ? { workspaceCounts } : {}
+    });
   });
   app2.post("/", async (c) => {
     const projectId = requireValidId(c, "projectId");
@@ -2744,8 +2883,10 @@ function sessionsRoutes(deps2) {
   app2.get("/:sessionId", async (c) => {
     const row = resolveSession(c);
     const hasTrace = await deps2.sessionService.hasTrace(row);
+    const info = await deps2.sessionService.toInfo(row, hasTrace);
+    const tracePath = hasTrace ? await deps2.sessionService.latestTracePath(row) : void 0;
     return c.json({
-      session: await deps2.sessionService.toInfo(row, hasTrace)
+      session: { ...info, ...tracePath !== void 0 ? { tracePath } : {} }
     });
   });
   app2.patch("/:sessionId", async (c) => {
@@ -2860,7 +3001,11 @@ function sessionsRoutes(deps2) {
     const row = resolveSession(c);
     const channel = deps2.channels.get(row.sessionId);
     const initialEvents = [
-      { type: "task_state", state: deps2.manager.statusOf(row.sessionId) },
+      {
+        type: "task_state",
+        state: deps2.manager.statusOf(row.sessionId),
+        queued: deps2.manager.pendingFollowUpCount(row.sessionId)
+      },
       ...deps2.manager.pendingApprovals(row.sessionId).map((p) => ({
         type: "approval_request",
         toolCall: p.toolCall,
@@ -2871,9 +3016,23 @@ function sessionsRoutes(deps2) {
   });
   app2.post("/:sessionId/tasks", async (c) => {
     const row = resolveSession(c);
-    const input = parseTaskInput(await readJson(c));
-    const { sessionId } = await deps2.manager.startTask(row.sessionId, input);
-    return c.json({ sessionId }, 202);
+    const body = await readJson(c);
+    const input = parseTaskInput(body);
+    const thinkingLevel = optionalEnum(body, "thinkingLevel", THINKING_LEVELS);
+    const queueIfBusy = body.queueIfBusy === true;
+    const { sessionId, queued } = await deps2.manager.startTask(row.sessionId, input, {
+      ...thinkingLevel !== void 0 ? { thinkingLevel } : {},
+      queueIfBusy
+    });
+    return c.json({ sessionId, queued }, 202);
+  });
+  app2.post("/:sessionId/steer", async (c) => {
+    const row = resolveSession(c);
+    const body = await readJson(c);
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    if (!text) throw badRequest("text must be a non-empty string.");
+    deps2.manager.steer(row.sessionId, text);
+    return c.body(null, 202);
   });
   app2.post("/:sessionId/approvals/:toolCallId", async (c) => {
     const row = resolveSession(c);
@@ -2927,6 +3086,31 @@ function sessionsRoutes(deps2) {
       }
     });
   });
+  app2.get("/:sessionId/files/preview-redirect", async (c) => {
+    const row = resolveSession(c);
+    const rel = c.req.query("path") ?? "";
+    const [exists] = await deps2.workspaceFiles.statExisting(row.workspace, [rel]);
+    if (!exists) throw new HttpError(404, "file_not_found", "File does not exist.");
+    const target = resolvePreviewTarget(
+      c.req.url,
+      c.req.header("host"),
+      deps2.config.previewOrigin,
+      deps2.config
+    );
+    if (!target) {
+      return c.redirect(
+        `/api/sessions/${row.sessionId}/files/content?path=${encodeURIComponent(rel)}&preview=1`,
+        302
+      );
+    }
+    const token = deps2.previewTokens.sign({
+      sessionId: row.sessionId,
+      host: target.host,
+      expiresAt: Date.now() + PREVIEW_TOKEN_TTL_MS
+    });
+    const encoded = rel.split("/").map(encodeURIComponent).join("/");
+    return c.redirect(`${target.origin}/preview/${token}/${encoded}`, 302);
+  });
   app2.post("/:sessionId/files/stat", async (c) => {
     const row = resolveSession(c);
     const body = await readJson(c);
@@ -3575,6 +3759,10 @@ var SessionManager = class {
   pendingApprovals(sessionId) {
     return this.entries.get(sessionId)?.approvals.list() ?? [];
   }
+  /** Number of queued follow-up tasks (`queueIfBusy`) awaiting auto-start. */
+  pendingFollowUpCount(sessionId) {
+    return this.entries.get(sessionId)?.followUps.length ?? 0;
+  }
   /** Number of Sessions for this Agent that are currently running / compacting. */
   activeCountForAgent(projectId, agentId) {
     let n = 0;
@@ -3597,6 +3785,7 @@ var SessionManager = class {
       abort: null,
       running: null,
       generation: this.generationOf(row.projectId, row.agentId),
+      followUps: [],
       lastActivityMs: Date.now()
     });
   }
@@ -3618,38 +3807,84 @@ var SessionManager = class {
    * Start a Task: get-or-load → 409
    * mutual-exclusion check → publish the input messages first → drive run in the
    * background. Returns the current actual session_id (the new id after self-heal).
+   * `opts.thinkingLevel` (optional, validated by the route) rides into this run's
+   * `session.run` options — a per-turn parameter, applied to this Task only.
+   * With `queueIfBusy`, a busy session (running/compacting) enqueues the input as a
+   * follow-up instead of 409: it auto-starts as an ordinary next task once the session
+   * returns to idle (`queued: true` in the result; see startQueuedFollowUp), keeping its
+   * thinkingLevel for that auto-start.
    */
-  async startTask(sessionId, input) {
+  async startTask(sessionId, input, opts) {
     return this.withLock(sessionId, async () => {
       this.assertOpen();
       this.assertAgentNotDeleting(sessionId);
       this.assertSessionNotDeleting(sessionId);
       const entry = await this.ensureEntry(sessionId);
+      if (entry.status !== "idle" && opts?.queueIfBusy) {
+        entry.followUps.push({
+          input,
+          ...opts.thinkingLevel !== void 0 ? { thinkingLevel: opts.thinkingLevel } : {}
+        });
+        entry.lastActivityMs = Date.now();
+        this.publishState(entry, entry.status);
+        return { sessionId: entry.sessionId, queued: true };
+      }
       this.assertIdle(entry);
-      const channel = this.deps.channels.get(entry.sessionId);
-      const ac = new AbortController();
-      entry.status = "running";
-      entry.abort = ac;
-      entry.lastActivityMs = Date.now();
-      for (const msg of input) channel.publish(msg);
-      this.publishState(entry, "running");
-      const approve = makeApprove({
-        // Re-reads approval_mode from the DB on every decision (a PATCH takes effect immediately).
-        getMode: () => this.deps.sessions.findById(entry.sessionId)?.approvalMode ?? "always-ask",
-        toolPermission: (name) => entry.session.toolPermission(name),
-        registry: entry.approvals,
-        publishRequest: (pending) => this.publishEvent(entry, {
-          type: "approval_request",
-          toolCall: pending.toolCall,
-          ...pending.origin !== void 0 ? { origin: pending.origin } : {}
-        })
-      });
-      const gen = entry.session.run(input, { approve, signal: ac.signal });
-      const userExcerpt = input.filter(isPlainText("user")).map((m) => m.payload.text).join("\n");
-      entry.running = this.drive(entry, gen, { userExcerpt });
-      return { sessionId: entry.sessionId };
+      this.launchTask(entry, input, opts?.thinkingLevel);
+      return { sessionId: entry.sessionId, queued: false };
     });
   }
+  /** Shared task launch (fresh tasks and auto-started follow-ups): flips to running, publishes the input, and drives the run with the per-turn thinking level (if any). Caller holds the session lock and has verified idle. */
+  launchTask(entry, input, thinkingLevel) {
+    const channel = this.deps.channels.get(entry.sessionId);
+    const ac = new AbortController();
+    entry.status = "running";
+    entry.abort = ac;
+    entry.lastActivityMs = Date.now();
+    for (const msg of input) channel.publish(msg);
+    this.publishState(entry, "running");
+    const approve = makeApprove({
+      // Re-reads approval_mode from the DB on every decision (a PATCH takes effect immediately).
+      getMode: () => this.deps.sessions.findById(entry.sessionId)?.approvalMode ?? "always-ask",
+      toolPermission: (name) => entry.session.toolPermission(name),
+      registry: entry.approvals,
+      publishRequest: (pending) => this.publishEvent(entry, {
+        type: "approval_request",
+        toolCall: pending.toolCall,
+        ...pending.origin !== void 0 ? { origin: pending.origin } : {}
+      })
+    });
+    const gen = entry.session.run(input, {
+      approve,
+      signal: ac.signal,
+      ...thinkingLevel !== void 0 ? { thinkingLevel } : {}
+    });
+    const userExcerpt = input.filter(isPlainText("user")).map((m) => m.payload.text).join("\n");
+    entry.running = this.drive(entry, gen, { userExcerpt });
+  }
+  /**
+   * Auto-start of queued follow-ups: called from drive's finally whenever a Task or
+   * compaction finishes (abort included — follow-ups are future tasks the user queued, so
+   * an abort of the current run does not discard them). Re-validates everything under the
+   * session lock (another task may have snuck in, the server may be shutting down, the
+   * session may be getting deleted) and launches exactly one queued input — the next
+   * finish picks up the one after, keeping order and one-at-a-time semantics.
+   */
+  async startQueuedFollowUp(sessionId) {
+    try {
+      await this.withLock(sessionId, async () => {
+        if (this.closed || this.deletingSessions.has(sessionId)) return;
+        const row = this.deps.sessions.findById(sessionId);
+        if (row && this.deletingAgents.has(agentKey(row.projectId, row.agentId))) return;
+        const entry = this.entries.get(sessionId);
+        if (!entry || entry.status !== "idle" || entry.followUps.length === 0) return;
+        const next = entry.followUps.shift();
+        this.launchTask(entry, next.input, next.thinkingLevel);
+      });
+    } catch (err) {
+      this.log(`[followup] auto-start failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
   /** Manually compact the context: 409 if already running; compaction output also flows into the SSE channel. */
   async startCompact(sessionId) {
     return this.withLock(sessionId, async () => {
@@ -3676,6 +3911,24 @@ var SessionManager = class {
     if (!entry) return false;
     return entry.approvals.decide(toolCallId, decision);
   }
+  /**
+   * Mid-run steering: forward the text to the running Session (core delivers it between
+   * turns as a standalone `[user_steering]` user message — no SSE event of its own; the
+   * message arrives through the stream the drive loop already publishes). 409 when the
+   * Session isn't running a Task (idle / compacting / not loaded) or the run finished in the
+   * race window — the caller falls back to submitting a normal task.
+   */
+  steer(sessionId, text) {
+    const entry = this.entries.get(sessionId);
+    if (!entry || entry.status !== "running" || !entry.session.steer(text)) {
+      throw new HttpError(
+        409,
+        "not_running",
+        "This Session has no Task in progress; send the message as a new task instead."
+      );
+    }
+    entry.lastActivityMs = Date.now();
+  }
   /**
    * Interrupt the current Task/compaction: pending approvals converge to deny first,
    * then the AbortSignal fires. Returns false if nothing is in progress (the route
@@ -3781,6 +4034,7 @@ var SessionManager = class {
   sweepIdle(now = Date.now(), idleMs = ENTRY_IDLE_MS) {
     for (const [key, entry] of this.entries) {
       if (entry.status !== "idle" || entry.approvals.size !== 0 || entry.running !== null) continue;
+      if (entry.followUps.length > 0) continue;
       if (now - entry.lastActivityMs <= idleMs) continue;
       this.entries.delete(key);
     }
@@ -3872,6 +4126,7 @@ var SessionManager = class {
       abort: null,
       running: null,
       generation,
+      followUps: [],
       lastActivityMs: Date.now()
     };
     this.entries.set(currentId, entry);
@@ -3976,6 +4231,7 @@ var SessionManager = class {
           fallbackText: titleSource.userExcerpt
         });
       }
+      if (entry.followUps.length > 0) void this.startQueuedFollowUp(entry.sessionId);
       for (const child of children.values()) {
         if (!child.prompt.trim()) continue;
         this.deps.titles?.maybeGenerate(
@@ -4046,7 +4302,7 @@ var SessionManager = class {
     return child;
   }
   publishState(entry, state) {
-    this.publishEvent(entry, { type: "task_state", state });
+    this.publishEvent(entry, { type: "task_state", state, queued: entry.followUps.length });
   }
   publishEvent(entry, event) {
     this.deps.channels.get(entry.sessionId).publish(event, "server_event");
@@ -4069,19 +4325,9 @@ var SessionManager = class {
 // src/runtime/scheduler.ts
 import { createHash as createHash3 } from "crypto";
 import { readdir } from "fs/promises";
-import { agentsDir, userText as userText2 } from "@prismshadow/penguin-core";
+import { agentsDir, buildScheduledMessage, userText as userText2 } from "@prismshadow/penguin-core";
 var TICK_INTERVAL_MS = 3e4;
-function scheduledMessage(name, firedAt, prompt) {
-  return [
-    "<scheduled_task>",
-    "This message was sent automatically by a scheduled task; its origin is listed below and the task prompt follows.",
-    `schedule: ${name}`,
-    `fired_at: ${firedAt}`,
-    "</scheduled_task>",
-    "",
-    prompt
-  ].join("\n");
-}
+var scheduledMessage = buildScheduledMessage;
 var Scheduler = class {
   constructor(deps2) {
     this.deps = deps2;
@@ -4500,7 +4746,7 @@ var UsageRecorder = class {
 };
 
 // src/services/ids.ts
-import { randomBytes as randomBytes3 } from "crypto";
+import { randomBytes as randomBytes4 } from "crypto";
 var SEMANTIC_ID_PATTERN = /^[a-z][a-z0-9_]{1,63}$/;
 var USERNAME_PATTERN = /^[a-z][a-z0-9_]{1,31}$/;
 var PROJECT_SUFFIX_PATTERN = /^[a-z0-9_]+$/;
@@ -4585,6 +4831,7 @@ import {
   VAULT_VALUE_MAX_LENGTH,
   isValidVaultKey,
   loadAgentVault,
+  resetSystemConfigToDefaults,
   saveAgentVault,
   systemConfigPath
 } from "@prismshadow/penguin-core";
@@ -5013,7 +5260,7 @@ function probeTps(outputTokens, windowMs) {
 }
 
 // src/services/agent-config-service.ts
-var THINKING_LEVELS = ["none", "low", "medium", "high", "xhigh"];
+var THINKING_LEVELS2 = ["none", "low", "medium", "high", "xhigh"];
 var COMPACTION_MODES = ["summarize", "discard"];
 function asRecord(v) {
   return v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
@@ -5115,6 +5362,18 @@ var AgentConfigService = class {
       await fs10.writeFile(agentsMdPath(this.root, projectId, agentId), req.agentsMd, "utf8");
     }
   }
+  /**
+   * Overwrites system_config.yaml with the current code defaults (core's
+   * resetSystemConfigToDefaults) — same semantics as updating an installed skill:
+   * only the identity fields (name / description / version) survive; the system
+   * prompt, max_turns, model/compaction settings and the tool list (incl. MCP
+   * servers) become the current defaults. AGENTS.md, skills and the vault are
+   * untouched.
+   */
+  async resetConfig(projectId, agentId) {
+    await this.requireExists(projectId, agentId);
+    await resetSystemConfigToDefaults(this.root, projectId, agentId);
+  }
   async applyConfigUpdate(projectId, agentId, config2) {
     const cfg = config2;
     const yamlPath = systemConfigPath(this.root, projectId, agentId);
@@ -5143,7 +5402,7 @@ var AgentConfigService = class {
       );
       setIfProvided(
         ["model", "thinking_level"],
-        optionalEnum(model, "thinkingLevel", THINKING_LEVELS)
+        optionalEnum(model, "thinkingLevel", THINKING_LEVELS2)
       );
       setIfProvided(
         ["model", "timeoutMs"],
@@ -5237,6 +5496,7 @@ function validateToolsBuiltin(value) {
     if (t.forModel !== void 0 && t.forModel !== "vision" && t.forModel !== "text-only") {
       throw badRequest(`toolsBuiltin[${i}].forModel must be one of vision / text-only.`);
     }
+    optionalBoolean(t, "call_description", `toolsBuiltin[${i}].call_description`);
     optionalNumber(t, "timeoutMs", {
       integer: true,
       positiveOrMinusOne: true,
@@ -5615,7 +5875,7 @@ var BenchmarkService = class {
 };
 
 // src/services/snapshot-service.ts
-import { randomBytes as randomBytes4 } from "crypto";
+import { randomBytes as randomBytes5 } from "crypto";
 import fs13 from "fs/promises";
 import path12 from "path";
 import * as tar from "tar";
@@ -5661,7 +5921,7 @@ var SnapshotService = class {
     } catch {
     }
     await fs13.mkdir(dir, { recursive: true });
-    const tmp = `${file}.tmp-${randomBytes4(4).toString("hex")}`;
+    const tmp = `${file}.tmp-${randomBytes5(4).toString("hex")}`;
     await tar.create(
       {
         gzip: true,
@@ -5689,7 +5949,7 @@ var SnapshotService = class {
   async importArchive(projectId, agentId, archive, confirm) {
     const current = await this.currentVersion(projectId, agentId);
     const base = agentDir2(this.root, projectId, agentId);
-    const staging = path12.join(base, `.import-${randomBytes4(6).toString("hex")}`);
+    const staging = path12.join(base, `.import-${randomBytes5(6).toString("hex")}`);
     await fs13.mkdir(staging, { recursive: true });
     try {
       const archiveFile = path12.join(staging, "archive.tar.gz");
@@ -6043,15 +6303,39 @@ var ProjectService = class {
 
 // src/services/session-service.ts
 import path13 from "path";
-import { readdir as readdir2 } from "fs/promises";
+import { open, readdir as readdir2 } from "fs/promises";
 import {
   createAgent as createAgent2,
+  findLatestTraceFile as findLatestTraceFile2,
   isSessionMeta as isSessionMeta4,
+  parseTraceLines,
   readTraceTolerant,
   tracesDir as tracesDir2
 } from "@prismshadow/penguin-core";
 var TRACE_FILE_RE = /^(.+)_(\d{3})\.jsonl$/;
 var SESSION_ID_TS_RE = /^session-(\d{4})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-(\d{2})-[0-9a-f]{8}$/;
+var TRACE_HEAD_BYTES = 256 * 1024;
+async function readTraceHead(filePath) {
+  const fh = await open(filePath, "r");
+  let text;
+  let truncated;
+  try {
+    const { buffer, bytesRead } = await fh.read(
+      Buffer.allocUnsafe(TRACE_HEAD_BYTES),
+      0,
+      TRACE_HEAD_BYTES,
+      0
+    );
+    text = buffer.subarray(0, bytesRead).toString("utf8");
+    truncated = bytesRead === TRACE_HEAD_BYTES;
+  } finally {
+    await fh.close();
+  }
+  if (!truncated) return parseTraceLines(text);
+  const nl = text.lastIndexOf("\n");
+  if (nl === -1) return readTraceTolerant(filePath);
+  return parseTraceLines(text.slice(0, nl + 1));
+}
 function sessionIdCreatedAt(sessionId) {
   const m = SESSION_ID_TS_RE.exec(sessionId);
   if (!m) return null;
@@ -6067,10 +6351,11 @@ var SessionService = class {
   /**
    * DB row -> SessionInfo (run status and pending approval count come from session-manager).
    * Async because `source` is derived from session_meta: a registry miss (Session predating
-   * this process) falls back to reading the Trace head once (see sourceOf).
+   * this process) falls back to reading the Trace head once (see sourceOf). `traces` is the
+   * list flow's one-walk discovery result; without it a miss locates the shard itself.
    */
-  async toInfo(row, hasTrace) {
-    const source = await this.sourceOf(row, hasTrace);
+  async toInfo(row, hasTrace, traces) {
+    const source = await this.sourceOf(row, hasTrace, traces);
     return {
       sessionId: row.sessionId,
       projectId: row.projectId,
@@ -6084,6 +6369,7 @@ var SessionService = class {
       createdAt: row.createdAt,
       status: this.deps.manager.statusOf(row.sessionId),
       pendingApprovalCount: this.deps.manager.pendingApprovalCount(row.sessionId),
+      pendingFollowUpCount: this.deps.manager.pendingFollowUpCount(row.sessionId),
       hasTrace,
       archived: (row.archivedAt ?? null) !== null
     };
@@ -6095,11 +6381,13 @@ var SessionService = class {
    * session_meta is read once and cached. A Session with no Trace yet stays unknown and
    * is NOT cached negatively — its meta may appear with the first run.
    */
-  async sourceOf(row, hasTrace) {
+  async sourceOf(row, hasTrace, traces) {
     const known = this.deps.sources.get(row.sessionId);
     if (known !== void 0) return known ?? void 0;
     if (!hasTrace) return void 0;
-    const meta = await this.readTraceMeta(row.projectId, row.agentId, row.sessionId);
+    const location = traces?.get(row.sessionId) ?? (await this.discoverTraces(row.projectId, row.agentId)).get(row.sessionId);
+    if (!location) return void 0;
+    const meta = await this.readTraceMeta(location);
     if (!meta) return void 0;
     const source = asSessionSource(meta.payload.source) ?? null;
     this.deps.sources.set(row.sessionId, source);
@@ -6107,8 +6395,17 @@ var SessionService = class {
   }
   /** Whether this Session already has a Trace record (a Task has been run). */
   async hasTrace(row) {
-    const ids = await this.discoverTraceSessionIds(row.projectId, row.agentId);
-    return ids.has(row.sessionId);
+    return (await this.discoverTraces(row.projectId, row.agentId)).has(row.sessionId);
+  }
+  /**
+   * The list category of a row: archived wins (an explicit user action), then the
+   * origin's bucket, and no/unknown source is `active` — the same precedence the
+   * sidebar's partition applies to loaded rows, so server filtering and client
+   * rendering can never disagree.
+   */
+  async categoryOf(row, hasTrace, traces) {
+    if ((row.archivedAt ?? null) !== null) return "archived";
+    return await this.sourceOf(row, hasTrace, traces) ?? "active";
   }
   /**
    * List: DB ∪ Trace directory discovery, sorted by createdAt descending. Optional
@@ -6116,22 +6413,58 @@ var SessionService = class {
    * more"); slicing happens before toInfo, so per-request source derivation (lazy
    * Trace-head reads) stays bounded by the page size. Discovery/adoption still scans
    * the whole directory — the union and global ordering need every id.
+   *
+   * `category` filters to one sidebar bucket **before** paging, so offset/limit page
+   * within the category. Filtering needs each walked row's category (a possible
+   * Trace-head read per row, cached in the sources registry); without `withCounts`
+   * the walk stops as soon as the requested page is complete. `withCounts` classifies
+   * every row and returns per-category totals over the whole list — plus the same
+   * totals broken down by Workspace path — so the sidebar can label the collapsed
+   * folders (and a workspace group can know its own share) without loading them.
    */
-  async listSessions(projectId, agentId, paging) {
-    const traceIds = await this.discoverTraceSessionIds(projectId, agentId);
+  async listSessions(projectId, agentId, opts = {}) {
+    const { paging, category, withCounts } = opts;
+    const traces = await this.discoverTraces(projectId, agentId);
     const rows = new Map(
       this.deps.sessions.listByAgent(projectId, agentId).map((r) => [r.sessionId, r])
     );
-    for (const sessionId of traceIds) {
+    for (const [sessionId, location] of traces) {
       if (rows.has(sessionId)) continue;
-      const discovered = await this.adoptTraceSession(projectId, agentId, sessionId);
+      const discovered = await this.adoptTraceSession(projectId, agentId, sessionId, location);
       if (discovered) rows.set(sessionId, discovered);
     }
     const sorted = [...rows.values()].sort(
       (a, b) => b.createdAt.localeCompare(a.createdAt) || b.sessionId.localeCompare(a.sessionId)
     );
-    const page = paging ? sorted.slice(paging.offset, paging.offset + paging.limit) : sorted;
-    return Promise.all(page.map((row) => this.toInfo(row, traceIds.has(row.sessionId))));
+    const toPage = (page) => Promise.all(page.map((row) => this.toInfo(row, traces.has(row.sessionId), traces)));
+    if (category === void 0 && !withCounts) {
+      return {
+        sessions: await toPage(
+          paging ? sorted.slice(paging.offset, paging.offset + paging.limit) : sorted
+        )
+      };
+    }
+    const want = paging ? paging.offset + paging.limit : Infinity;
+    const counts = { active: 0, subagent: 0, schedule: 0, archived: 0 };
+    const workspaceCounts = {};
+    const matched = [];
+    for (const row of sorted) {
+      if (!withCounts && matched.length >= want) break;
+      const cat = await this.categoryOf(row, traces.has(row.sessionId), traces);
+      counts[cat] += 1;
+      if (withCounts) {
+        const ws = workspaceCounts[row.workspace] ??= {
+          active: 0,
+          subagent: 0,
+          schedule: 0,
+          archived: 0
+        };
+        ws[cat] += 1;
+      }
+      if ((category === void 0 || cat === category) && matched.length < want) matched.push(row);
+    }
+    const sessions = await toPage(paging ? matched.slice(paging.offset, want) : matched);
+    return withCounts ? { sessions, counts, workspaceCounts } : { sessions };
   }
   /**
    * Session stats (Agents list card): total count = size of the union of DB index
@@ -6243,48 +6576,59 @@ var SessionService = class {
     this.deps.manager.adopt(row, session);
     return this.toInfo(row, false);
   }
-  /** Scans the Trace directory to get the set of session_ids with records. */
-  async discoverTraceSessionIds(projectId, agentId) {
-    const dir = tracesDir2(this.deps.root, projectId, agentId);
-    const ids = /* @__PURE__ */ new Set();
-    for (const dateDir of await listDirsSafe(dir)) {
-      for (const file of await listFilesSafe(path13.join(dir, dateDir))) {
-        const match = TRACE_FILE_RE.exec(file);
-        if (match) ids.add(match[1]);
-      }
-    }
-    return ids;
+  /**
+   * Absolute path of a Session's **latest** Trace file (the current context shard);
+   * undefined when no Trace exists. Costs a directory walk, so only the single-session
+   * GET includes it in the DTO (see SessionInfo.tracePath) — the web's `/model` switch
+   * hands it to the new session's `[model_switch_from]` block so the model can read the
+   * source history itself when it needs it.
+   */
+  async latestTracePath(row) {
+    const located = await findLatestTraceFile2(
+      tracesDir2(this.deps.root, row.projectId, row.agentId),
+      row.sessionId
+    );
+    return located?.path;
   }
   /**
-   * session_meta from the earliest Trace shard of a Session (the shard whose head carries
-   * the original meta); null when there is no readable Trace or it has no meta. Shared by
-   * adoption backfill and lazy `source` resolution.
+   * One walk over the Trace directory: session_id → its **earliest** shard (the shard
+   * whose head carries the original session_meta). Discovery (which Sessions have
+   * records) and the meta-read location come out of a single pass, so classifying every
+   * row (`counts=1`) costs one directory walk total instead of one per Session.
    */
-  async readTraceMeta(projectId, agentId, sessionId) {
+  async discoverTraces(projectId, agentId) {
     const dir = tracesDir2(this.deps.root, projectId, agentId);
-    let earliest = null;
+    const out = /* @__PURE__ */ new Map();
     for (const dateDir of await listDirsSafe(dir)) {
       for (const file of await listFilesSafe(path13.join(dir, dateDir))) {
         const match = TRACE_FILE_RE.exec(file);
-        if (!match || match[1] !== sessionId) continue;
+        if (!match) continue;
+        const sessionId = match[1];
         const index = Number(match[2]);
-        if (!earliest || index < earliest.index) {
-          earliest = { path: path13.join(dir, dateDir, file), index };
+        const cur = out.get(sessionId);
+        if (!cur || index < cur.index) {
+          out.set(sessionId, { path: path13.join(dir, dateDir, file), index });
         }
       }
     }
-    if (!earliest) return null;
+    return out;
+  }
+  /**
+   * session_meta from a located Trace shard head; null when unreadable or it has no
+   * meta. Shared by adoption backfill and lazy `source` resolution.
+   */
+  async readTraceMeta(location) {
     let messages;
     try {
-      messages = await readTraceTolerant(earliest.path);
+      messages = await readTraceHead(location.path);
     } catch {
       return null;
     }
     return messages.find(isSessionMeta4) ?? null;
   }
   /** Adopts a Session that exists only in the Trace directory: reads session_meta from the first line of the earliest index file. */
-  async adoptTraceSession(projectId, agentId, sessionId) {
-    const meta = await this.readTraceMeta(projectId, agentId, sessionId);
+  async adoptTraceSession(projectId, agentId, sessionId, location) {
+    const meta = await this.readTraceMeta(location);
     if (!meta) return null;
     if (typeof meta.payload.provider !== "string") return null;
     this.deps.sources.set(sessionId, asSessionSource(meta.payload.source) ?? null);
@@ -6328,7 +6672,12 @@ async function listFilesSafe(dir) {
 // src/services/trace-service.ts
 import fs15 from "fs/promises";
 import path14 from "path";
-import { agentsDir as agentsDir3, readTraceTolerant as readTraceTolerant2, tracesDir as tracesDir3 } from "@prismshadow/penguin-core";
+import {
+  agentsDir as agentsDir3,
+  parseUserSteeringText,
+  readTraceTolerant as readTraceTolerant2,
+  tracesDir as tracesDir3
+} from "@prismshadow/penguin-core";
 var TRACE_FILE_RE2 = /^(.+)_(\d{3})\.jsonl$/;
 var MAX_SUBAGENT_DEPTH = 4;
 function subagentPointer(msg) {
@@ -6519,7 +6868,9 @@ var TraceService = class {
       const msg = messages[mi];
       const p = msg.payload;
       const hasOrigin = msg.origin !== void 0 && msg.origin.length > 0;
-      const startsUserTurn = !hasOrigin && !compactionActive && msg.type === "model_msg" && (p.type === "text" && p.role === "user" || p.type === "image_url");
+      const isSteeringText = !hasOrigin && msg.type === "model_msg" && p.type === "text" && p.role === "user" && typeof p.text === "string" && parseUserSteeringText(p.text) !== null;
+      if (isSteeringText) continuation = true;
+      const startsUserTurn = !hasOrigin && !compactionActive && !isSteeringText && msg.type === "model_msg" && (p.type === "text" && p.role === "user" || p.type === "image_url");
       const startsCompactionTurn = !hasOrigin && msg.type === "event_msg" && p.type === "compaction_begin";
       if (startsUserTurn || startsCompactionTurn) {
         if (pendingFrom === null) pendingFrom = mi;
@@ -6918,6 +7269,53 @@ var UsageService = class {
   }
 };
 
+// src/http/routes/preview.ts
+import { Hono as Hono19 } from "hono";
+var DIRECTORY_INDEX = "index.html";
+function previewRoutes(deps2) {
+  const app2 = new Hono19();
+  app2.get("/:token/*", async (c) => {
+    const token = c.req.param("token");
+    const payload = token ? deps2.previewTokens.verify(token) : null;
+    if (!payload) return c.text("Not found", 404);
+    const authority = requestAuthority(c.req.url, c.req.header("host"));
+    if (hostOnly(authority).toLowerCase() !== payload.host.toLowerCase()) {
+      return c.text("Not found", 404);
+    }
+    const row = deps2.sessionsRepo.findById(payload.sessionId);
+    if (!row) return c.text("Not found", 404);
+    const prefix = `/preview/${token}/`;
+    const raw = c.req.path.startsWith(prefix) ? c.req.path.slice(prefix.length) : "";
+    let rel;
+    try {
+      rel = decodeURIComponent(raw);
+    } catch {
+      return c.text("Not found", 404);
+    }
+    if (rel === "" || rel.endsWith("/")) rel += DIRECTORY_INDEX;
+    let file;
+    try {
+      file = await deps2.workspaceFiles.read(row.workspace, rel);
+    } catch {
+      return c.text("Not found", 404);
+    }
+    return new Response(new Uint8Array(file.data), {
+      status: 200,
+      headers: {
+        "Content-Type": file.contentType,
+        "X-Content-Type-Options": "nosniff",
+        // Without this, third-party requests made by the page leak the token-bearing
+        // URL through Referer — a risk that only exists because this origin exists to
+        // let third-party embeds run.
+        "Referrer-Policy": "no-referrer",
+        // Previews are per-token and short-lived; never let a shared cache keep them.
+        "Cache-Control": "no-store"
+      }
+    });
+  });
+  return app2;
+}
+
 // src/app.ts
 var MAX_BODY_BYTES = 20 * 1024 * 1024;
 function buildAppDeps(config2, overrides = {}) {
@@ -6938,6 +7336,7 @@ function buildAppDeps(config2, overrides = {}) {
   const agentService = new AgentService(config2.root, agentsRepo, agentConfigService);
   const traceService = new TraceService(config2.root);
   const workspaceFiles = new WorkspaceFilesService();
+  const previewTokens = createPreviewTokenSigner();
   const benchmarks = new BenchmarkService(config2.root);
   const snapshots = new SnapshotService(config2.root);
   const usageService = new UsageService(
@@ -7028,6 +7427,7 @@ function buildAppDeps(config2, overrides = {}) {
     traceService,
     usageService,
     workspaceFiles,
+    previewTokens,
     benchmarks,
     snapshots,
     schedulesRepo,
@@ -7040,7 +7440,7 @@ function buildAppDeps(config2, overrides = {}) {
   };
 }
 function createApp(deps2) {
-  const app2 = new Hono19();
+  const app2 = new Hono20();
   app2.onError((err, c) => {
     const projectId = attributedProjectId(c, deps2);
     deps2.errors.record({
@@ -7057,6 +7457,21 @@ function createApp(deps2) {
     const ms = Math.round(performance.now() - start);
     deps2.log(`${c.req.method} ${c.req.path} ${c.res.status} ${ms}ms`);
   });
+  const previewRoles = deps2.config.previewOrigin ? null : loopbackHostRoles(deps2.config.host);
+  if (previewRoles) {
+    app2.use("*", async (c, next) => {
+      const host = hostOnly(requestAuthority(c.req.url, c.req.header("host"))).toLowerCase();
+      if (host === previewRoles.preview && !c.req.path.startsWith("/preview/")) {
+        if (c.req.path.startsWith("/api/")) {
+          throw new HttpError(401, "unauthorized", "The API is not served on the preview host.");
+        }
+        const url = new URL(c.req.url);
+        url.hostname = previewRoles.app;
+        return c.redirect(url.toString(), 302);
+      }
+      await next();
+    });
+  }
   app2.use("/api/*", async (c, next) => {
     const contentLength = Number(c.req.header("content-length") ?? 0);
     if (contentLength > MAX_BODY_BYTES) {
@@ -7087,6 +7502,7 @@ function createApp(deps2) {
   app2.route("/api/projects/:projectId/agents/:agentId/sessions", agentSessionsRoutes(deps2));
   app2.route("/api/projects/:projectId/usage", usageRoutes(deps2));
   app2.route("/api/sessions", sessionsRoutes(deps2));
+  app2.route("/preview", previewRoutes(deps2));
   if (fs16.existsSync(deps2.config.webDist)) {
     registerStaticRoutes(app2, deps2.config.webDist);
   }
@@ -7160,6 +7576,19 @@ function defaultWebDist() {
   if (fs17.existsSync(bundled)) return bundled;
   return path16.resolve(here, "..", "..", "web", "dist");
 }
+function normalizePreviewOrigin(raw) {
+  if (!raw || raw.trim() === "") return null;
+  let url;
+  try {
+    url = new URL(raw.trim());
+  } catch {
+    throw new Error(`Invalid PENGUIN_PREVIEW_ORIGIN=${raw} (expected an absolute origin)`);
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(`Invalid PENGUIN_PREVIEW_ORIGIN=${raw} (only http/https are supported)`);
+  }
+  return url.origin;
+}
 function resolveServerConfig(env = process.env) {
   const root = env.PENGUIN_HOME ?? resolveRoot();
   const port = Number(env.PORT || DEFAULT_SERVER_PORT);
@@ -7172,6 +7601,7 @@ function resolveServerConfig(env = process.env) {
     port,
     dbPath: env.PENGUIN_WEB_DB ?? path16.join(root, "web.db"),
     webDist: env.PENGUIN_WEB_DIST ?? defaultWebDist(),
+    previewOrigin: normalizePreviewOrigin(env.PENGUIN_PREVIEW_ORIGIN),
     authSessionTtlMs: 7 * DAY_MS,
     authSessionRenewMs: 6 * DAY_MS
   };
@@ -7184,11 +7614,18 @@ var deps = buildAppDeps(config);
 var app = createApp(deps);
 await deps.authService.seedAdmin();
 await deps.scheduler.start();
+var appHost = loopbackHostRoles(config.host)?.app ?? config.host;
 var server = serve({ fetch: app.fetch, hostname: config.host, port: config.port }, (info) => {
-  console.log(`penguin-server started: http://${config.host}:${info.port}`);
+  console.log(`penguin-server started: http://${appHost}:${info.port}`);
   console.log(`Data root: ${config.root}`);
   console.log(`SQLite: ${config.dbPath}`);
 });
+var ipv6Loopback = config.host === "127.0.0.1" || config.host === "localhost" ? serve({ fetch: app.fetch, hostname: "::1", port: config.port }) : null;
+ipv6Loopback?.on("error", (err) => {
+  console.warn(
+    `[server] IPv6 loopback listener unavailable (${err.code ?? err.message}); previews via localhost may not resolve.`
+  );
+});
 var shuttingDown = false;
 async function shutdown(signal, exitCode = 0) {
   if (shuttingDown) return;
@@ -7197,6 +7634,7 @@ async function shutdown(signal, exitCode = 0) {
   deps.scheduler.stop();
   await deps.manager.shutdown(5e3);
   deps.channels.dispose();
+  ipv6Loopback?.close();
   server.close(() => {
     deps.db.close();
     process.exit(exitCode);