@frockbot/plugin-shell 0.3.8 → 0.3.10

package/src/notification-id.ts

@@ -0,0 +1,58 @@
+import { isPublicIdentifier } from "@frockbot/configuration-core";
+
+/**
+ * The acknowledge decoder's ceiling: `isPublicIdentifier` admits a leading
+ * alphanumeric plus at most 127 more characters.
+ */
+const MAX_NOTIFICATION_ID_LENGTH = 128;
+
+/** How much of a folded id the digest suffix costs: `-` plus eight hex. */
+const DIGEST_SUFFIX_LENGTH = 9;
+
+/**
+ * A notification is only useful if it can be acknowledged, and acknowledgement
+ * decodes the id through `isPublicIdentifier`
+ * (`/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/`) — which admits no colons. Delivery
+ * only bounds the length, so an id minted by hand out of a generation id
+ * (`2026-09-03T23:49:00.416Z:dc03a32d9b717619`) or a package request went out,
+ * came back, and was refused with `400` on every poll for the life of the Bot.
+ *
+ * Every notification id is minted here instead, so the two sides cannot drift:
+ * the parts are joined with `-`, anything outside the admitted alphabet
+ * becomes `-`, and an over-long id keeps its readable head and folds the rest
+ * into a digest so distinct inputs stay distinct ids. Ids are stable for the
+ * same parts, which is what makes one firing one intent however many times a
+ * retry re-mints it.
+ */
+export function notificationIdV1(
+  ...parts: readonly (string | number)[]
+): string {
+  const raw = parts.map((part) => String(part)).join("-");
+  const sanitized = raw
+    .replace(/[^a-zA-Z0-9._-]/g, "-")
+    .replace(/^[^a-zA-Z0-9]+/, "");
+  const seeded =
+    sanitized.length === 0 ? `notification-${digest(raw)}` : sanitized;
+  const bounded =
+    seeded.length <= MAX_NOTIFICATION_ID_LENGTH
+      ? seeded
+      : `${seeded.slice(0, MAX_NOTIFICATION_ID_LENGTH - DIGEST_SUFFIX_LENGTH)}-${digest(raw)}`;
+  if (!isPublicIdentifier(bounded)) {
+    // Unreachable by construction; a mint that cannot be acknowledged is a
+    // bug, never something to ship to a client that will 400 on it forever.
+    throw new Error(
+      `minted notification id "${bounded}" is not acknowledgeable`,
+    );
+  }
+  return bounded;
+}
+
+/** FNV-1a, eight hex digits — an id disambiguator, not a security claim. */
+function digest(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}

package/src/run-protocol.test.ts

@@ -1476,6 +1476,87 @@ describe("dispatched subagents in the run projection", () => {
     }
   });
 
+  test("a running Turn projects the words it has written so far", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "Half a",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: " thought",
+      }),
+    ];
+
+    const projected = projectClientRunV1(storedRun(streamed, "running"));
+    expect(projected.partialText).toBe("Half a thought");
+    expect(projected.outcome).toBeUndefined();
+
+    // And it survives the wire, so the thread draws it while the Turn runs.
+    const decoded = decodeClientRunPageV1(
+      createClientRunListV1([projected], { truncated: false }),
+    ).runs[0];
+    expect(decoded?.partialText).toBe("Half a thought");
+    expect(decoded?.responseText).toBeUndefined();
+  });
+
+  test("a running Turn that has said nothing carries no partial text", () => {
+    expect(projectClientRunV1(storedRun([], "running")).partialText).toBe(
+      undefined,
+    );
+  });
+
+  test("a later request restarts the partial answer", () => {
+    const streamed: SessionEvent[] = [
+      event({
+        type: "assistant/chunk",
+        seq: 0,
+        timestamp,
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        text: "scratch",
+      }),
+      event({
+        type: "assistant/chunk",
+        seq: 1,
+        timestamp,
+        turn: 1,
+        step: 2,
+        requestId: "request-2",
+        text: "the answer",
+      }),
+    ];
+    expect(projectClientRunV1(storedRun(streamed, "running")).partialText).toBe(
+      "the answer",
+    );
+  });
+
+  test("a settled Turn carries its answer once, as an outcome", () => {
+    const projected = projectClientRunV1(storedRun([], "completed"));
+    expect(projected.partialText).toBeUndefined();
+    expect(projected.outcome).toMatchObject({ type: "completed" });
+
+    const page = createClientRunListV1([projected], { truncated: false });
+    const tampered = structuredClone(page) as unknown as {
+      runs: Array<Record<string, unknown>>;
+    };
+    tampered.runs[0]!.partialText = "words";
+    expect(() => decodeClientRunPageV1(tampered)).toThrow(
+      "only a running run may carry partial text",
+    );
+  });
+
   test("refuses a chip whose background flag is not a boolean", () => {
     const page = createClientRunListV1(
       [projectClientRunV1(storedRun([dispatched]))],

package/src/run-protocol.ts

@@ -220,6 +220,14 @@ export interface ClientRunV1 {
    * the flag is durable state, so a reload draws the same thing.
    */
   queued?: true;
+  /**
+   * The answer the Bot has written so far, present only while the run is still
+   * running and has produced text. The thread draws it in the bubble it is
+   * already drawing for the Turn, so a reply appears as it is written instead
+   * of arriving whole at settlement. A settled run carries its answer in
+   * `outcome` instead, and never both.
+   */
+  partialText?: string;
   outcome?: ClientRunOutcomeV1;
   recovery?: ClientRunRecoveryV1;
 }
@@ -738,10 +746,13 @@ function visibleEvents(
  * fact about what the person watched arrive, not a claim that the Turn
  * succeeded, and the thread keeps it instead of replacing it with a notice.
  */
-function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
+export function assistantTextSoFarV1(
+  events: readonly SessionEvent[],
+  responseText = "",
+): string {
   let requestId: string | undefined;
-  let text = run.responseText ?? "";
-  for (const event of run.events) {
+  let text = responseText;
+  for (const event of events) {
     if (event.type === "assistant/chunk") {
       if (event.requestId !== requestId) {
         requestId = event.requestId;
@@ -753,9 +764,31 @@ function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
       text = event.text;
     }
   }
+  return text;
+}
+
+function interruptedOutcomeTextV1(run: StoredRun): { text?: string } {
+  const text = assistantTextSoFarV1(run.events, run.responseText ?? "");
   return text ? { text: truncateWireString(text, MAX_OUTCOME_BYTES) } : {};
 }
 
+/**
+ * What a still-running Turn has said so far, read out of the same journal an
+ * interrupted one is read from.
+ *
+ * The kernel appends an `assistant/chunk` per provider text delta and each
+ * append lands on the run record, so the words are already durable while the
+ * Turn runs; nothing here is a second copy and nothing crosses the channel.
+ * Bounded exactly as an outcome is, because a long answer must not be able to
+ * grow the run list past its wire budget.
+ */
+function partialTextV1(run: StoredRun): { partialText?: string } {
+  const text = assistantTextSoFarV1(run.events);
+  return text
+    ? { partialText: truncateWireString(text, MAX_OUTCOME_BYTES) }
+    : {};
+}
+
 function runStatus(run: StoredRun): ClientRunStatusV1 {
   return requireStoredRunV1(run).status;
 }
@@ -810,6 +843,7 @@ export function projectClientRunV1(run: StoredRun): ClientRunV1 {
     input: truncateWireString(run.input, MAX_INPUT_BYTES),
     status,
     events: visibleEvents(run.events, status),
+    ...(status === "running" ? partialTextV1(run) : {}),
     ...(run.stopRequestedAt
       ? {
           stopRequestedAt: truncate(run.stopRequestedAt, MAX_TIMESTAMP_LENGTH),
@@ -1300,6 +1334,7 @@ function decodeRun(value: unknown): ClientRun {
       "events",
       "stopRequestedAt",
       "queued",
+      "partialText",
       "outcome",
       "recovery",
     ],
@@ -1347,6 +1382,16 @@ function decodeRun(value: unknown): ClientRun {
   if (run.queued === true && runStatus !== "running") {
     throw new Error("only a running run may be queued");
   }
+  let partialText: string | undefined;
+  if (run.partialText !== undefined) {
+    // A settled run's answer is its outcome. Carrying both would give the
+    // thread two sources for one bubble, which is the duplication the
+    // one-bubble contract exists to prevent.
+    if (runStatus !== "running") {
+      throw new Error("only a running run may carry partial text");
+    }
+    partialText = wireString(run, "partialText", MAX_OUTCOME_BYTES, "run");
+  }
   return {
     runId,
     admittedAt,
@@ -1355,6 +1400,7 @@ function decodeRun(value: unknown): ClientRun {
     events: decodeEvents(run.events),
     ...(stopRequestedAt ? { stopRequestedAt } : {}),
     ...(run.queued === true ? { queued: true as const } : {}),
+    ...(partialText ? { partialText } : {}),
     ...(outcome?.type === "completed" ? { responseText: outcome.text } : {}),
     ...(outcome?.type === "failed"
       ? {

package/src/unread.test.ts

@@ -236,6 +236,33 @@ describe("the unread projection", () => {
     expect(view).toMatchObject({ count: 0, capped: false, unread: false });
   });
 
+  // A Routine failing every minute left the badge at zero, because an
+  // automation Turn never advances the activity cursor.
+  test("badges a Bot whose Routine is failing, with nothing else unread", () => {
+    const view = projectBotUnreadViewV1(
+      "alpha",
+      emptyUnreadStateV1(),
+      index(3),
+      undefined,
+      2,
+    );
+    expect(view).toMatchObject({ count: 2, unread: true, capped: false });
+  });
+
+  test("adds Routine failures to the unread chat Turns", () => {
+    const state: UnreadStateV1 = {
+      schemaVersion: 1,
+      lastActivityCursor: cursor(3),
+      lastActivityAt: "2026-08-31T00:03:00.000Z",
+      lastSeenCursor: cursor(1),
+      lastViewedAt: "2026-08-31T00:01:00.000Z",
+      manuallyUnread: false,
+    };
+    expect(
+      projectBotUnreadViewV1("alpha", state, index(4), undefined, 1),
+    ).toMatchObject({ count: 3, unread: true });
+  });
+
   test("carries the already-bounded latest message without deriving it", () => {
     const preview = decodeSidebarMessagePreviewV1({
       schemaVersion: 1,

package/src/unread.ts

@@ -406,9 +406,17 @@ export function projectBotUnreadViewV1(
   state: UnreadStateV1,
   cursors: readonly string[],
   lastMessage?: SidebarMessagePreviewV1,
+  /**
+   * Unacknowledged Routine failures. An automation Turn deliberately does not
+   * advance the activity cursor, so a Routine failing every minute badged
+   * nothing at all — the one Bot the User most needed to look at was the one
+   * the sidebar stayed quiet about. A failure is the Bot addressing its User,
+   * so it counts here even though the firing that produced it does not.
+   */
+  automationFailures = 0,
 ): BotUnreadViewV1 {
   const ceiling = state.lastActivityCursor;
-  let counted = 0;
+  let counted = Math.max(0, automationFailures);
   if (ceiling !== undefined) {
     for (const cursor of cursors) {
       if (cursor > ceiling) continue;