@frockbot/plugin-shell 0.3.16 → 0.3.18

package/src/backend.ts

@@ -9,6 +9,7 @@ import {
   decodeIsolateWorkspaceListRequestV1,
   decodeIsolateWorkspacePathV1,
   decodeIsolateWorkspaceWriteRequestV1,
+  decodeSendToUserPayloadV1,
   decodeWorkspacePathV1,
   decodeWorkspaceRootV1,
   decodeSessionEvent,
@@ -134,6 +135,7 @@ import {
 import {
   createAppletCapabilityHostV1,
   createAppletInstanceBindingV1,
+  APPLET_DIST_FILES_V1,
   appletRpcSnapshotV1 as rpcJsonSnapshotV1,
   resolveAppletCompositionV1,
   type AppletCapabilityHostV1,
@@ -253,6 +255,7 @@ import {
   decodeSubagentSlotReceiptV1,
   type SubagentSlotBinding,
 } from "@frockbot/plugin-subagents/quota";
+import { decodeAgentTurnSlotReceiptV1 } from "@frockbot/plugin-flock/quota";
 import {
   subagentModelCatalogV1,
   type SubagentModelOptionV1,
@@ -406,6 +409,7 @@ import {
   decodeClientRunLookupQueryV1,
   decodeClientRunListQueryV1,
   decodeClientRunStopCommandV1,
+  decodeClientTurnV1,
   isVisibleRunV1,
   projectClientRunLookupV1,
   projectClientRunV1,
@@ -667,6 +671,16 @@ export interface ShellBotBackendHost {
   scheduledWorkInFlight?(): boolean;
   deferScheduledWork?(transaction: DurableObjectTransaction): Promise<void>;
   settleScheduledWork?(): Promise<void>;
+  /**
+   * A derived accounting projection after `turn/end` is durable. The host
+   * queues it before delivery, so failure never changes the Turn's outcome.
+   */
+  recordSettledUsage?(input: {
+    botId: string;
+    runId: string;
+    turn: number;
+    events: readonly SessionEvent[];
+  }): Promise<void>;
 }
 
 /** The narrow storage seam the Bot's announcement log is written through. */
@@ -769,6 +783,7 @@ export class ShellBotBackendContribution {
   private readonly hostScheduledWorkInFlight?: ShellBotBackendHost["scheduledWorkInFlight"];
   private readonly hostDeferScheduledWork?: ShellBotBackendHost["deferScheduledWork"];
   private readonly hostSettleScheduledWork?: ShellBotBackendHost["settleScheduledWork"];
+  private readonly recordSettledUsage?: ShellBotBackendHost["recordSettledUsage"];
 
   constructor(host: ShellBotBackendHost) {
     this.ctx = host.state;
@@ -784,6 +799,7 @@ export class ShellBotBackendContribution {
     this.hostScheduledWorkInFlight = host.scheduledWorkInFlight;
     this.hostDeferScheduledWork = host.deferScheduledWork;
     this.hostSettleScheduledWork = host.settleScheduledWork;
+    this.recordSettledUsage = host.recordSettledUsage;
     const routines = createBotRoutines(
       host.state.storage,
       createBotRoutineHookMinter(
@@ -1645,6 +1661,9 @@ export class ShellBotBackendContribution {
       // One admitted Turn is one run; the Turn ordinal lives in the session log.
       turnId: input.command.runId,
       sessionId: input.command.sessionId,
+      // The admitted configuration snapshot is durable, so a recovered
+      // bot_message reuses the same sender display name in its target command.
+      fromBotName: settings.profile.name,
       // The pin this Turn was admitted under, and the type it was admitted as.
       // A subagent dispatched from here runs on this generation, and the model
       // catalog it is offered is narrowed by this turn type.
@@ -1660,6 +1679,17 @@ export class ShellBotBackendContribution {
       ...(input.command.origin?.kind === "subagent"
         ? { subagentTaskId: input.command.origin.taskId }
         : {}),
+      ...(input.command.origin?.kind === "bot"
+        ? {
+            inboundAgent: {
+              kind: "bot" as const,
+              fromBotId: input.command.origin.fromBotId,
+              fromBotName: input.command.origin.fromBotName,
+            },
+          }
+        : input.command.origin?.kind === "voice"
+          ? { inboundAgent: { kind: "voice" as const } }
+          : {}),
     };
     let mountedRoot: ShellMountedComposition["root"] | undefined;
     let mountedGeneration: CompositionGenerationV1 | undefined;
@@ -1729,6 +1759,16 @@ export class ShellBotBackendContribution {
               input.command.sessionId,
               effect,
             ),
+          ...(this.recordSettledUsage
+            ? {
+                onTurnStopping: (settled) =>
+                  this.recordSettledUsage!({
+                    botId: input.identity.botId,
+                    runId: input.command.runId,
+                    ...settled,
+                  }),
+              }
+            : {}),
           ...(isolate ? { isolate } : {}),
           ...(appletRouting ? { applets: appletRouting } : {}),
         }).mount(mounting, signal);
@@ -2414,7 +2454,7 @@ export class ShellBotBackendContribution {
       // User with no Computer assignment has no root to pull, and the Bot that
       // just built on its Computer has it open already.
       syncSourceRootNow: active
-        ? async () => {
+        ? async (appletId) => {
             const root = active.mounted.runtime.root as unknown as {
               computers?: ComputerRegistry;
               sessions: typeof active.mounted.runtime.root.sessions;
@@ -2437,6 +2477,9 @@ export class ShellBotBackendContribution {
               sessionId: active.sessionId,
               turn,
               root: appletsSourceRootV1(identity.userId),
+              requiredPaths: APPLET_DIST_FILES_V1.map(
+                (path) => `${appletId}/${path}`,
+              ),
               signal: active.signal,
             });
           }
@@ -3251,6 +3294,22 @@ export class ShellBotBackendContribution {
     };
   }
 
+  /** Narrow RPC for the User-wide agent-lane concurrency lease. */
+  private agentTurnSlots(identity: BotIdentity) {
+    const id = this.env.USER_CONFIGURATIONS.idFromName(identity.userId);
+    const rpc = this.env.USER_CONFIGURATIONS.get(id) as unknown as {
+      reserveAgentTurnSlot(input: unknown): Promise<unknown>;
+      releaseAgentTurnSlot(input: unknown): Promise<unknown>;
+    };
+    return {
+      reserve: async (request: unknown) =>
+        decodeAgentTurnSlotReceiptV1(await rpc.reserveAgentTurnSlot(request)),
+      release: async (request: unknown) => {
+        await rpc.releaseAgentTurnSlot(request);
+      },
+    };
+  }
+
   /**
    * The User-wide `desktop-gui` lease, held at the Computer host.
    *
@@ -4333,6 +4392,7 @@ export class ShellBotBackendContribution {
       runId: string;
       turnId: string;
       sessionId: string;
+      fromBotName: string;
       /**
        * The generation this Turn pinned, and the type it was admitted as. A
        * dispatched subagent runs on the generation its parent pinned, and the
@@ -4522,6 +4582,39 @@ export class ShellBotBackendContribution {
                   this.userConfiguration(identity).listBots(userId),
                 createBot: (userId, command) =>
                   this.userConfiguration(identity).createBot(userId, command),
+                reserveAgentTurn: (request) =>
+                  this.agentTurnSlots(identity).reserve(request),
+                releaseAgentTurn: (request) =>
+                  this.agentTurnSlots(identity).release(request),
+                runAgent: async (request) => {
+                  if (!this.env.BOT_STATES) {
+                    throw new Error("Bot-to-Bot messaging is unavailable");
+                  }
+                  const id = this.env.BOT_STATES.idFromName(
+                    `${request.userId}:${request.botId}`,
+                  );
+                  const rpc = this.env.BOT_STATES.get(id) as unknown as {
+                    runAgent(input: unknown): Promise<unknown>;
+                  };
+                  const completed = decodeClientTurnV1(
+                    structuredClone(await rpc.runAgent(request)),
+                  );
+                  let sentText: string | undefined;
+                  for (const event of completed.events) {
+                    if (event.type !== "send/to-user") continue;
+                    const payload = decodeSendToUserPayloadV1(
+                      event.payload,
+                      "agent send/to-user payload",
+                    );
+                    if (payload.type === "text") {
+                      sentText = payload.text;
+                      break;
+                    }
+                  }
+                  return {
+                    text: sentText ?? completed.text,
+                  };
+                },
               }),
             }
           : {}),
@@ -5209,6 +5302,12 @@ export class ShellBotBackendContribution {
     };
   }
 
+  /** Count inputs waiting for the next conversational Turn without draining them. */
+  async pendingInputCount(identity: BotIdentity): Promise<number> {
+    await this.validateIdentity(identity);
+    return (await this.routineInbox.pending()).length;
+  }
+
   /**
    * Acknowledge inbox entries. An explicit command, never a side effect of
    * reading: a background poll must not clear the badge.

package/src/client/FrockBotApp.vue

@@ -1490,7 +1490,12 @@ function handleComposerKeydown(event: KeyboardEvent): void {
                 </div>
               </div>
             </template>
-            <div v-else class="message-bubble">{{ message.text }}</div>
+            <div v-else class="message-user-column">
+              <div class="message-bubble">{{ message.text }}</div>
+              <span v-if="message.via" class="message-via">
+                via {{ message.via.name }}
+              </span>
+            </div>
           </article>
           <!--
             The working row: the Bot's own avatar on its own line at the end of

package/src/client/index.test.ts

@@ -95,6 +95,40 @@ afterEach(() => {
   }
 });
 
+test("a degraded Computer sync is a notice beneath the Turn once", () => {
+  const state: Pick<
+    FrockBotWebData,
+    "messages" | "activeRunId" | "runningRunId" | "activeRun"
+  > = { messages: [] };
+
+  projectDurableRuns(
+    state,
+    [],
+    [
+      {
+        runId: "run-sync",
+        input: "build the applet",
+        status: "completed",
+        responseText: "The Applet is ready.",
+        events: [
+          {
+            type: "computer/sync",
+            status: "degraded",
+            message: "Excluded 1 reproducible Workspace item from sync.",
+          },
+        ],
+      },
+    ],
+  );
+
+  expect(state.messages).toHaveLength(2);
+  expect(state.messages[1]).toMatchObject({
+    role: "assistant",
+    text: "The Applet is ready.",
+    notice: "Excluded 1 reproducible Workspace item from sync.",
+  });
+});
+
 describe("application manifest protocol", () => {
   const emptyManifest = {
     schemaVersion: 1,
@@ -1451,6 +1485,33 @@ describe("active durable Turn projection", () => {
     expect(state.messages[1]).toMatchObject({ text: "", status: "streaming" });
   });
 
+  test("keeps the source marker on an agent-origin user bubble", () => {
+    const state: Pick<
+      FrockBotWebData,
+      "messages" | "activeRunId" | "activeRun"
+    > = { messages: [] };
+    projectDurableRuns(
+      state,
+      [],
+      [
+        {
+          runId: "run-agent",
+          input: "What changed?",
+          events: [],
+          status: "completed",
+          responseText: "The answer",
+          via: { kind: "bot", name: "Researcher", botId: "researcher" },
+        },
+      ],
+    );
+
+    expect(state.messages[0]).toMatchObject({
+      role: "user",
+      text: "What changed?",
+      via: { kind: "bot", name: "Researcher" },
+    });
+  });
+
   test("projects dispatched subagents as chips, and skips one it cannot draw", () => {
     const state: Pick<
       FrockBotWebData,

package/src/client/index.ts

@@ -363,6 +363,13 @@ function assistantMessage(
   run: ClientRun,
   notification: ClientNotificationIntent | undefined,
 ): WebChatMessage {
+  const syncNotice = run.events.find(
+    (event) => event.type === "computer/sync" && event.message,
+  )?.message;
+  const notice = (primary?: string): string | undefined =>
+    [primary, syncNotice]
+      .filter((part): part is string => Boolean(part))
+      .join(" ") || undefined;
   if (run.status === "running") {
     // A streaming Turn carries only the text the model has produced. Until
     // there is any, the thread shows the animated avatar and no bubble.
@@ -375,6 +382,7 @@ function assistantMessage(
       // A Turn that has not started shows nothing of its own: the greyed user
       // message is the whole of what the thread says about it.
       ...(run.queued ? { pending: true } : {}),
+      ...(syncNotice ? { notice: syncNotice } : {}),
       tools: toolsFrom(run.events),
       sends: [],
       tasks: tasksFrom(run.events),
@@ -391,6 +399,7 @@ function assistantMessage(
       role: "assistant",
       text: visibleAssistantText(run),
       status: "aborted",
+      ...(syncNotice ? { notice: syncNotice } : {}),
       tools: toolsFrom(run.events),
       sends: [],
       tasks: tasksFrom(run.events),
@@ -409,7 +418,7 @@ function assistantMessage(
        * exactly like the Bot speaking.
        */
       text: visibleAssistantText(run),
-      notice: "This reply stopped partway. Try again to continue it.",
+      notice: notice("This reply stopped partway. Try again to continue it."),
       status: "reconciliation-required",
       tools: toolsFrom(run.events),
       sends: [],
@@ -422,7 +431,7 @@ function assistantMessage(
       runId: run.runId,
       role: "assistant",
       text: visibleAssistantText(run),
-      notice: "You stopped this.",
+      notice: notice("You stopped this."),
       status: "aborted",
       tools: toolsFrom(run.events),
       sends: [],
@@ -447,7 +456,7 @@ function assistantMessage(
       // wire, so this keeps whatever that chose — the model-deadline copy says
       // something the outcome alone cannot — and falls back to the same line a
       // reply-less failure gets.
-      notice: knownFailureCopyV1(run.failure),
+      notice: notice(knownFailureCopyV1(run.failure)),
       status: "error",
       tools: toolsFrom(run.events),
       sends: [],
@@ -465,8 +474,10 @@ function assistantMessage(
     // Why the Turn ends there, under whatever it had already said — never as
     // the bubble's own text, which reads as the Bot saying it.
     ...(run.status === "failed"
-      ? { notice: knownFailureCopyV1(run.failure) }
-      : {}),
+      ? { notice: notice(knownFailureCopyV1(run.failure)) }
+      : syncNotice
+        ? { notice: syncNotice }
+        : {}),
     status: run.status === "failed" ? "error" : "completed",
     tools: toolsFrom(run.events),
     sends: [],
@@ -561,6 +572,7 @@ export function projectDurableRuns(
           ? { at: existingUser.at }
           : {}),
       status: "completed",
+      ...(run.via ? { via: run.via } : {}),
       // Greyed while its Turn waits, ordinary the moment it is running. The
       // flag comes from durable run state, so a reload draws the same thing.
       ...(run.queued ? { pending: true } : {}),
@@ -3070,6 +3082,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
    * and the one-bubble-per-send contract is untouched.
    */
   let stopRunChannel: (() => void) | undefined;
+  // The channel's own health, for the observation below: `fallback` means the
+  // socket is gone and the transcript is flying blind, and each return to
+  // `open` means it was gone for a while. Either is a reason to read the
+  // running Turn from authority rather than trust a POST that may have died
+  // with the same connection — which is how a phone kept drawing the working
+  // trail for a Turn the server had already settled (2026-09-04).
+  const channelFallback = ref(false);
+  const channelReconnects = ref(0);
   const stopRunChannelWatch = watch(
     () => web.value.activeBotId,
     (botId) => {
@@ -3096,10 +3116,14 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
           restoredWithoutRead = undefined;
           await deliverNotifications(botId, generation);
         },
-        status() {
+        status(status) {
           // The channel's health is not the transcript's: an unavailable
           // socket falls back to the observation below, which is what a
           // client without one uses anyway.
+          if (generation !== selectionGeneration) return;
+          const wasDown = channelFallback.value;
+          channelFallback.value = status === "fallback";
+          if (status === "open" && wasDown) channelReconnects.value += 1;
         },
       });
     },
@@ -3107,12 +3131,21 @@ export const shellClientPlugin: ClientPlugin = (ctx) => {
   );
 
   const stopRunObservation = watch(
-    () => [web.value.activeBotId, web.value.activeRunId] as const,
-    ([botId, runId]) => {
+    () =>
+      [
+        web.value.activeBotId,
+        web.value.activeRunId,
+        channelFallback.value,
+        channelReconnects.value,
+      ] as const,
+    ([botId, runId, fallback]) => {
       // The send path owns the run it started: its POST is the observation,
       // and `stopRun` starts its own. This is for every other way a client
-      // finds itself watching a Turn it is not holding open.
-      if (!botId || !runId || activeRequest || runObserver) return;
+      // finds itself watching a Turn it is not holding open — and, once the
+      // state channel has dropped or come back, for the Turn it *is* holding
+      // open, because that POST shared the connection that just failed.
+      if (!botId || !runId || runObserver) return;
+      if (activeRequest && !fallback && channelReconnects.value === 0) return;
       const generation = selectionGeneration;
       const observer = new AbortController();
       runObserver = observer;

package/src/client/mobile-safe-area.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+
+const styles = await Bun.file(new URL("./styles.css", import.meta.url)).text();
+
+describe("phone safe-area layout", () => {
+  test("keeps the conversation header and thread below the status bar", () => {
+    expect(styles).toContain(
+      "height: calc(var(--frock-titlebar-height) + var(--frock-safe-top));",
+    );
+    expect(styles).toContain("padding-top: calc(var(--frock-safe-top) + 0px);");
+    expect(styles).toContain(
+      "top: calc(var(--frock-titlebar-height) + var(--frock-safe-top));",
+    );
+  });
+
+  test("keeps drawers, Settings, and the composer clear of both bars", () => {
+    expect(styles).toContain(
+      "padding-bottom: calc(10px + var(--frock-safe-bottom));",
+    );
+    expect(styles).toContain(
+      "padding-bottom: calc(16px + var(--frock-safe-bottom));",
+    );
+    expect(styles).toContain("bottom: calc(10px + var(--frock-safe-bottom));");
+  });
+});

package/src/client/styles.css

@@ -499,6 +499,17 @@
   background: var(--frock-action-primary);
 }
 
+.message-user-column {
+  display: grid;
+  justify-items: end;
+  gap: 4px;
+}
+
+.message-via {
+  color: var(--frock-text-muted);
+  font-size: var(--frock-text-xs);
+}
+
 /*
  * User-facing sends. They stack under the Bot's avatar in the same column the
  * text bubble occupies, so a Turn that only sent a widget still reads as the
@@ -1118,6 +1129,7 @@
     /* `calc` so the declaration is a length the checker can type; `env` alone
        is not one it knows. */
     padding-top: calc(var(--frock-safe-top) + 0px);
+    padding-bottom: calc(10px + var(--frock-safe-bottom));
     box-shadow: var(--frock-shadow-panel);
     transform: translateX(-100%);
     visibility: hidden;
@@ -1189,12 +1201,27 @@
   /* No window chrome to clear, but the panel toggle still sits at the
      trailing edge, so the row ends before it rather than under it. */
   .topbar {
+    height: calc(var(--frock-titlebar-height) + var(--frock-safe-top));
     gap: 8px;
     padding: 0 52px 0 4px;
+    padding-top: calc(var(--frock-safe-top) + 0px);
   }
 
   .window-actions {
+    height: calc(var(--frock-titlebar-height) + var(--frock-safe-top));
     padding: 0 8px;
+    padding-top: calc(var(--frock-safe-top) + 0px);
+  }
+
+  .right-panel-header,
+  .panel-surface-header {
+    height: calc(var(--frock-titlebar-height) + var(--frock-safe-top));
+    padding-top: calc(var(--frock-safe-top) + 0px);
+  }
+
+  .right-panel-body,
+  .panel-surface-content {
+    padding-bottom: calc(16px + var(--frock-safe-bottom));
   }
 
   .brand-mark {
@@ -1211,6 +1238,7 @@
    * vertical anchors all clear the home indicator.
    */
   .thread {
+    top: calc(var(--frock-titlebar-height) + var(--frock-safe-top));
     bottom: calc(76px + var(--frock-safe-bottom));
     padding: 12px 12px 20px;
   }

package/src/client/voice-microphone.ts

@@ -21,10 +21,14 @@ export interface VoiceMicrophoneV1 {
 }
 
 export interface VoiceMicrophoneOptionsV1 {
-  /** One frame of PCM16, little-endian, mono, 24 kHz. */
+  /** One frame of PCM16, little-endian, mono, at `sampleRate`. */
   audio(pcm16: ArrayBuffer): void;
   /** Peak amplitude of the frame, 0…1, for the capture animation. */
   level(value: number): void;
+  /** Defaults to dictation's 24 kHz. Voice assistant input uses 16 kHz. */
+  sampleRate?: number;
+  /** Defaults to 32 ms at the selected sample rate. */
+  frameSamples?: number;
 }
 
 /** False on a platform with no microphone API at all; the button stays hidden. */
@@ -83,8 +87,14 @@ export async function startVoiceMicrophoneV1(
       numberOfOutputs: 1,
       outputChannelCount: [1],
       processorOptions: {
-        targetRate: VOICE_CAPTURE_SAMPLE_RATE_V1,
-        frameSamples: FRAME_SAMPLES,
+        targetRate: options.sampleRate ?? VOICE_CAPTURE_SAMPLE_RATE_V1,
+        frameSamples:
+          options.frameSamples ??
+          Math.round(
+            FRAME_SAMPLES *
+              ((options.sampleRate ?? VOICE_CAPTURE_SAMPLE_RATE_V1) /
+                VOICE_CAPTURE_SAMPLE_RATE_V1),
+          ),
       },
     });
     node.port.onmessage = (event: MessageEvent) => {

package/src/compaction.test.ts

@@ -15,6 +15,7 @@ import {
   parseCompactionSummaryV1,
   PRUNED_TOOL_RESULT_V1,
   pruneToolOutputsV1,
+  renderCompactionSummaryV1,
   runCompactionV1,
   COMPACTION_TRIGGER_RATIO_V1,
 } from "./compaction.js";
@@ -385,6 +386,31 @@ describe("injecting a compaction", () => {
 });
 
 describe("reading the summariser's answer", () => {
+  test("renders the validated fields into the durable heading format", () => {
+    expect(
+      renderCompactionSummaryV1({
+        summary: "Work on the Applet.",
+        decisions: ["Keep the first design."],
+        openItems: [],
+        identifiers: ["applet-9f2c"],
+      }),
+    ).toBe(
+      [
+        "## Summary",
+        "Work on the Applet.",
+        "",
+        "## Decisions",
+        "- Keep the first design.",
+        "",
+        "## Open items",
+        "- none",
+        "",
+        "## Identifiers mentioned",
+        "- applet-9f2c",
+      ].join("\n"),
+    );
+  });
+
   test("lifts the identifiers out of their heading", () => {
     const parsed = parseCompactionSummaryV1(
       [

package/src/compaction.ts

@@ -26,6 +26,7 @@ import {
   type ModelBindingSnapshot,
   type Session,
   type SessionEvent,
+  type StructuredOutputSchemaV1,
 } from "@frockbot/kernel-contracts";
 
 /**
@@ -262,27 +263,58 @@ export function assessCompactionV1(input: {
  * ids in passing, and the list is what the event stores.
  */
 export const COMPACTION_SYSTEM_PROMPT_V1 = [
-  "You are compressing the earlier part of a conversation so it can be carried forward in a smaller prompt. Write the summary, and nothing else.",
+  "You are compressing the earlier part of a conversation so it can be carried forward in a smaller prompt.",
   "",
   "CRITICAL: You MUST preserve ALL opaque identifiers exactly as they appear. That includes UUIDs, hashes, full URLs with their query parameters, file and Workspace paths, Package ids, Applet ids, Bot ids, Session ids, tool call ids, model names and version strings. Do NOT paraphrase, abbreviate, or generalise an identifier. Copy it exactly.",
   "",
-  "Use exactly these headings, in this order, and omit none of them:",
-  "",
-  "## Summary",
-  "What the conversation is about and what has happened, in a few short paragraphs or bullets.",
-  "",
-  "## Decisions",
-  "Decisions made and the reason for each. Where a decision was later changed, keep only the latest and say it superseded an earlier one.",
-  "",
-  "## Open items",
-  "Work that is pending, promised, or unfinished. Be specific about what is owed and by whom.",
-  "",
-  "## Identifiers mentioned",
-  "A bullet list of every opaque identifier that appeared, one per line, copied exactly. Write `- none` if there were none.",
+  "Put the gist in `summary`, decisions and their reasons in `decisions`, pending work in `openItems`, and every opaque identifier copied exactly in `identifiers`. Keep only the latest decision where one superseded another.",
   "",
   "Leave out pleasantries, repetition, and superseded detail. Do not invent anything that is not in the transcript. Do not address the user.",
 ].join("\n");
 
+export interface CompactionSummaryPayloadV1 {
+  summary: string;
+  decisions: string[];
+  openItems: string[];
+  identifiers: string[];
+}
+
+/** The actual production consumer of the shared structured-output seam. */
+export const COMPACTION_RESPONSE_SCHEMA_V1 = {
+  type: "object",
+  properties: {
+    summary: { type: "string" },
+    decisions: { type: "array", items: { type: "string" } },
+    openItems: { type: "array", items: { type: "string" } },
+    identifiers: { type: "array", items: { type: "string" } },
+  },
+  required: ["summary", "decisions", "openItems", "identifiers"],
+  additionalProperties: false,
+} as const satisfies StructuredOutputSchemaV1;
+
+/** Keeps the durable summary format readable while model I/O stays typed. */
+export function renderCompactionSummaryV1(
+  payload: CompactionSummaryPayloadV1,
+): string {
+  const bullets = (values: readonly string[]) =>
+    values.length > 0
+      ? values.map((value) => `- ${value}`).join("\n")
+      : "- none";
+  return [
+    "## Summary",
+    payload.summary,
+    "",
+    "## Decisions",
+    bullets(payload.decisions),
+    "",
+    "## Open items",
+    bullets(payload.openItems),
+    "",
+    "## Identifiers mentioned",
+    bullets(payload.identifiers),
+  ].join("\n");
+}
+
 /** The transcript one summariser call is given, flattened to plain text. */
 export function compactionTranscriptV1(
   messages: readonly LlmMessage[],