@frockbot/plugin-shell 0.0.0 → 0.1.1

package/src/composition-views.ts

@@ -0,0 +1,118 @@
+// The redacted hosted-client projection of the Bot's durable Composition
+// generations. The durable record is kernel authority; what a User may see of
+// it is Shell Package policy, so the projection lives here and never lets
+// artifact bytes, manifest hashes, or loader identities cross the seam.
+import {
+  decodeCompositionGenerationViewV1,
+  MAX_COMPOSITION_FAILURE_PAGE_V1,
+  type CompositionGenerationViewV1,
+  type CompositionMemberViewV1,
+  type CompositionProvenanceViewV1,
+} from "@frockbot/configuration-core";
+import type {
+  CompositionFailureV1,
+  CompositionQuarantineV1,
+} from "@frockbot/kernel-composition/activation";
+import type {
+  CompositionGenerationV1,
+  CompositionMemberV1,
+} from "@frockbot/kernel-composition/generation";
+
+/**
+ * SEAM — plan Step 5 (authoring). Once the Bot object holds
+ * `authorship:intent:<effectId>` / `artifact:<contentHash>` records, the Shell
+ * Contribution supplies a reader that returns the recorded TypeScript source
+ * for an isolate member. Until those records exist, no reader is supplied and a
+ * generation view carries its member list alone.
+ */
+export type CompositionMemberSourceReaderV1 = (
+  member: CompositionMemberV1,
+) => Promise<string | undefined>;
+
+function provenanceView(
+  member: CompositionMemberV1,
+): CompositionProvenanceViewV1 {
+  const provenance = member.provenance;
+  if (provenance.kind === "first-party") return { kind: "first-party" };
+  if (provenance.kind === "user") {
+    return {
+      kind: "user",
+      userId: provenance.userId,
+      authoredAt: provenance.authoredAt,
+    };
+  }
+  return {
+    kind: "bot",
+    botId: provenance.botId,
+    sessionId: provenance.sessionId,
+    turnId: provenance.turnId,
+    runId: provenance.runId,
+    authoredAt: provenance.authoredAt,
+  };
+}
+
+export interface ProjectCompositionGenerationInput {
+  botId: string;
+  generation: CompositionGenerationV1;
+  currentGenerationId: string;
+  /** Omitted for the list projection: only a single generation carries source. */
+  readMemberSource?: CompositionMemberSourceReaderV1;
+  /** Recorded activation failures for this generation, oldest attempt first. */
+  failures?: readonly CompositionFailureV1[];
+  /** Present once three consecutive failures quarantined this generation. */
+  quarantine?: CompositionQuarantineV1;
+}
+
+/** One durable generation as the hosted client may see it. */
+export async function projectCompositionGenerationV1(
+  input: ProjectCompositionGenerationInput,
+): Promise<CompositionGenerationViewV1> {
+  const members: CompositionMemberViewV1[] = [];
+  for (const member of input.generation.members) {
+    const source = member.artifact
+      ? await input.readMemberSource?.(member)
+      : undefined;
+    members.push({
+      packageId: member.packageId,
+      version: member.version,
+      provenance: provenanceView(member),
+      ...(member.artifact ? { contentHash: member.artifact.contentHash } : {}),
+      ...(source === undefined ? {} : { source }),
+    });
+  }
+  // Diagnostics carry artifact content hashes and loader identities, so the
+  // view keeps only the repairable half of a failure: when, where, and why.
+  const failures = (input.failures ?? [])
+    .slice(-MAX_COMPOSITION_FAILURE_PAGE_V1)
+    .map((failure) => ({
+      attempt: failure.attempt,
+      at: failure.at,
+      phase: failure.phase,
+      message: failure.message,
+    }));
+  // Decoding the projection is the seam check: a field the view does not
+  // declare cannot reach a client through this function.
+  return decodeCompositionGenerationViewV1({
+    schemaVersion: 1,
+    botId: input.botId,
+    generationId: input.generation.generationId,
+    createdAt: input.generation.createdAt,
+    status: input.generation.status,
+    origin: input.generation.origin,
+    isCurrent: input.generation.generationId === input.currentGenerationId,
+    members,
+    failures,
+    ...(input.quarantine === undefined
+      ? {}
+      : {
+          quarantine: {
+            quarantinedAt: input.quarantine.quarantinedAt,
+            reason: input.quarantine.reason,
+            failures: input.quarantine.failures,
+          },
+        }),
+    ...(input.generation.parentGenerationId === undefined
+      ? {}
+      : { parentGenerationId: input.generation.parentGenerationId }),
+  });
+}

package/src/debug-protocol.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, test } from "bun:test";
+import {
+  BOT_DEBUG_RUN_LIMIT_V1,
+  boundDebugEventsV1,
+  decodeBotDebugQueryV1,
+} from "./debug-protocol.js";
+
+describe("debug query", () => {
+  test("accepts the empty query", () => {
+    expect(decodeBotDebugQueryV1({ schemaVersion: 1 })).toEqual({
+      schemaVersion: 1,
+    });
+  });
+
+  test("carries a run lookup, a page bound, a cursor, and an events flag", () => {
+    expect(
+      decodeBotDebugQueryV1({
+        schemaVersion: 1,
+        runId: "run-1",
+        limit: 3,
+        before: "run-index:2026-08-28T00:00:00.000Z:run-0",
+        events: true,
+      }),
+    ).toEqual({
+      schemaVersion: 1,
+      runId: "run-1",
+      limit: 3,
+      before: "run-index:2026-08-28T00:00:00.000Z:run-0",
+      events: true,
+    });
+  });
+
+  test("rejects an unknown field", () => {
+    expect(() =>
+      decodeBotDebugQueryV1({ schemaVersion: 1, sql: "select 1" }),
+    ).toThrow("debug query has invalid fields");
+  });
+
+  test("rejects a limit past the page bound", () => {
+    expect(() =>
+      decodeBotDebugQueryV1({
+        schemaVersion: 1,
+        limit: BOT_DEBUG_RUN_LIMIT_V1 + 1,
+      }),
+    ).toThrow("debug query limit is invalid");
+  });
+
+  test("rejects a wrong schema version", () => {
+    expect(() => decodeBotDebugQueryV1({ schemaVersion: 2 })).toThrow(
+      "debug query schemaVersion is invalid",
+    );
+  });
+});
+
+describe("event bounding", () => {
+  test("keeps everything inside the budget", () => {
+    const events = [{ seq: 1 }, { seq: 2 }];
+    expect(boundDebugEventsV1(events, 1_000)).toMatchObject({
+      events,
+      omittedEvents: 0,
+    });
+  });
+
+  test("drops the oldest events, because a failure is described by the tail", () => {
+    const events = [{ seq: 1 }, { seq: 2 }, { seq: 3 }];
+    const size = new TextEncoder().encode(JSON.stringify(events[0])).byteLength;
+    const bounded = boundDebugEventsV1(events, size * 2);
+
+    expect(bounded.events).toEqual([{ seq: 2 }, { seq: 3 }]);
+    expect(bounded.omittedEvents).toBe(1);
+  });
+
+  test("keeps the newest event even when it alone exceeds the budget", () => {
+    const events = [{ seq: 1 }, { seq: 2 }];
+    const bounded = boundDebugEventsV1(events, 1);
+
+    expect(bounded.events).toEqual([{ seq: 2 }]);
+    expect(bounded.omittedEvents).toBe(1);
+  });
+});

package/src/debug-protocol.ts

@@ -0,0 +1,165 @@
+/**
+ * The operator's view of a Bot's durable state: the runs as the authority
+ * actually stored them, the Composition generations they pinned, and the
+ * failures recorded against those generations.
+ *
+ * This is deliberately *not* the client run protocol. `run-protocol.ts`
+ * projects a transcript for a person reading their conversation: it hides
+ * non-visible runs, drops `model/request`, drops tool-call inputs, and
+ * collapses anything it cannot show into `run/events-truncated`. Every one of
+ * those omissions is the thing an operator needs when the agent loop
+ * misbehaves — which prompt went to the model, what the tool was asked to do,
+ * why the turn failed, which generation it was admitted under.
+ *
+ * Nothing here mutates. In particular a debug read never recovers an active
+ * run or settles an uncertain effect: a stuck Bot must still be stuck after
+ * you have looked at it.
+ */
+
+export const BOT_DEBUG_RUN_LIMIT_V1 = 20;
+export const BOT_DEBUG_DEFAULT_RUN_LIMIT_V1 = 5;
+export const BOT_DEBUG_GENERATION_LIMIT_V1 = 5;
+/**
+ * The event budget one snapshot spends. Session events carry whole prompts, so
+ * a handful of runs can be megabytes; past this the *oldest* events of a run
+ * are dropped, because a failure is described by the tail of its log.
+ */
+export const BOT_DEBUG_EVENT_BYTES_V1 = 512_000;
+
+export interface BotDebugQueryV1 {
+  schemaVersion: 1;
+  /** One run, always with its events. Omitted: the newest page of runs. */
+  runId?: string;
+  limit?: number;
+  /** A run-index cursor from a previous snapshot's `nextCursor`. */
+  before?: string;
+  /** Include session events in list mode. Single-run lookups always do. */
+  events?: boolean;
+}
+
+export interface BotDebugRunV1 {
+  runId: string;
+  sessionId: string;
+  acceptedAt: string;
+  status: string;
+  phase: string;
+  input: string;
+  commandFingerprint: string;
+  compositionGenerationId: string;
+  /** Events the session already held when this run was admitted. */
+  previousEventCount: number;
+  eventCount: number;
+  responseText?: string;
+  failure?: string;
+  events?: unknown[];
+  /** Oldest events dropped to stay inside the snapshot's byte budget. */
+  omittedEvents?: number;
+}
+
+export interface BotDebugGenerationV1 {
+  generationId: string;
+  createdAt: string;
+  status: string;
+  origin: string;
+  artifactSetHash: string;
+  parentGenerationId?: string;
+  memberCount: number;
+  failures: unknown[];
+  quarantined: boolean;
+}
+
+export interface BotDebugSnapshotV1 {
+  schemaVersion: 1;
+  botId: string;
+  capturedAt: string;
+  /**
+   * A run the object still considers in flight. A run that sits here across
+   * two snapshots, with its event tail unchanged, is the signature of a Bot
+   * that stopped mid-turn.
+   */
+  activeRunId?: string;
+  composition: {
+    currentGenerationId: string;
+    currentStatus: string;
+    lastKnownGoodGenerationId?: string;
+    generations: BotDebugGenerationV1[];
+  };
+  configuration?: unknown;
+  notifications: unknown[];
+  runs: BotDebugRunV1[];
+  nextCursor?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function boundedString(value: unknown, maximum: number, field: string): string {
+  if (typeof value !== "string" || value.length < 1 || value.length > maximum) {
+    throw new Error(`debug query ${field} is invalid`);
+  }
+  return value;
+}
+
+export function decodeBotDebugQueryV1(input: unknown): BotDebugQueryV1 {
+  if (!isRecord(input)) throw new Error("debug query is invalid");
+  if (input.schemaVersion !== 1) {
+    throw new Error("debug query schemaVersion is invalid");
+  }
+  const allowed = new Set([
+    "schemaVersion",
+    "runId",
+    "limit",
+    "before",
+    "events",
+  ]);
+  if (!Object.keys(input).every((key) => allowed.has(key))) {
+    throw new Error("debug query has invalid fields");
+  }
+  const query: BotDebugQueryV1 = { schemaVersion: 1 };
+  if (input.runId !== undefined) {
+    query.runId = boundedString(input.runId, 128, "runId");
+  }
+  if (input.before !== undefined) {
+    query.before = boundedString(input.before, 512, "before");
+  }
+  if (input.limit !== undefined) {
+    if (
+      !Number.isSafeInteger(input.limit) ||
+      (input.limit as number) < 1 ||
+      (input.limit as number) > BOT_DEBUG_RUN_LIMIT_V1
+    ) {
+      throw new Error("debug query limit is invalid");
+    }
+    query.limit = input.limit as number;
+  }
+  if (input.events !== undefined) {
+    if (typeof input.events !== "boolean") {
+      throw new Error("debug query events is invalid");
+    }
+    query.events = input.events;
+  }
+  return query;
+}
+
+/**
+ * Keeps the newest events that fit in `budget`, reporting how many older ones
+ * were dropped. The tail is what describes a failure, so the head is what goes.
+ */
+export function boundDebugEventsV1(
+  events: readonly unknown[],
+  budget: number,
+): { events: unknown[]; omittedEvents: number; spent: number } {
+  const encoder = new TextEncoder();
+  const kept: unknown[] = [];
+  let spent = 0;
+  for (let index = events.length - 1; index >= 0; index -= 1) {
+    const size = encoder.encode(JSON.stringify(events[index]) ?? "").byteLength;
+    if (spent + size > budget && kept.length > 0) {
+      return { events: kept, omittedEvents: index + 1, spent };
+    }
+    kept.unshift(events[index]);
+    spent += size;
+  }
+  return { events: kept, omittedEvents: 0, spent };
+}

package/src/env.d.ts

@@ -0,0 +1,10 @@
+declare module "*.vue" {
+  import type { DefineComponent } from "vue";
+
+  const component: DefineComponent<
+    Record<string, never>,
+    Record<string, never>,
+    unknown
+  >;
+  export default component;
+}

package/src/history.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, test } from "bun:test";
+import {
+  decodeSessionEvent,
+  type LlmMessage,
+  type SessionEvent,
+  type SessionEventInput,
+} from "@frockbot/kernel-contracts";
+import {
+  automationParentPointerV1,
+  currentTurnV1,
+  turnScopedMessagesV1,
+  turnTypesByTurnV1,
+} from "./history.js";
+
+function log(inputs: SessionEventInput[]): SessionEvent[] {
+  return inputs.map((input, index) =>
+    decodeSessionEvent({
+      ...input,
+      seq: index,
+      timestamp: new Date(1_700_000_000_000 + index).toISOString(),
+    }),
+  );
+}
+
+/** The same derivation `Session.deriveMessages` performs, over a fixed log. */
+function derive(events: readonly SessionEvent[]): LlmMessage[] {
+  const messages: LlmMessage[] = [];
+  for (const event of events) {
+    if (event.type === "user/message") {
+      messages.push({ role: "user", content: event.text });
+    } else if (event.type === "assistant/message") {
+      messages.push({
+        role: "assistant",
+        content: event.text,
+        toolCalls: event.toolCalls,
+      });
+    }
+  }
+  return messages;
+}
+
+function turn(
+  turnNumber: number,
+  turnType: "chat" | "automation",
+  text: string,
+  reply: string,
+): SessionEventInput[] {
+  return [
+    { type: "turn/start", turn: turnNumber },
+    { type: "turn/admission", turn: turnNumber, turnType },
+    { type: "step/start", turn: turnNumber, step: 1 },
+    {
+      type: "user/message",
+      turn: turnNumber,
+      step: 1,
+      messageId: `m-${turnNumber}`,
+      text,
+    },
+    {
+      type: "assistant/message",
+      turn: turnNumber,
+      step: 1,
+      requestId: `r-${turnNumber}`,
+      text: reply,
+      toolCalls: [],
+    },
+    { type: "step/end", turn: turnNumber, step: 1, outcome: "completed" },
+    { type: "turn/end", turn: turnNumber, outcome: "completed" },
+  ];
+}
+
+function scoped(events: SessionEvent[]): LlmMessage[] {
+  return turnScopedMessagesV1({
+    events,
+    messages: derive(events),
+    pointer: automationParentPointerV1,
+    sessionId: "bot:scout",
+  });
+}
+
+describe("turn-scoped prompt history", () => {
+  test("a chat Turn sees only the Turns admitted as chat", () => {
+    const events = log([
+      ...turn(1, "chat", "morning", "hello"),
+      ...turn(2, "automation", "Routine fired", "checked the inbox"),
+      ...turn(3, "chat", "anything new?", ""),
+    ]);
+    expect(scoped(events).map((message) => message.content)).toEqual([
+      "morning",
+      "hello",
+      "anything new?",
+      "",
+    ]);
+  });
+
+  test("an automation Turn starts from a pointer and its own Turn only", () => {
+    const events = log([
+      ...turn(1, "chat", "morning", "hello"),
+      ...turn(2, "chat", "and again", "hi"),
+      { type: "turn/start", turn: 3 },
+      { type: "turn/admission", turn: 3, turnType: "automation" },
+      { type: "step/start", turn: 3, step: 1 },
+      {
+        type: "user/message",
+        turn: 3,
+        step: 1,
+        messageId: "m-3",
+        text: "Routine fired",
+      },
+    ]);
+    const messages = scoped(events);
+    expect(messages).toHaveLength(2);
+    expect(messages[0]!.content).toContain('session "bot:scout"');
+    expect(messages[0]!.content).toContain("2 conversational Turns");
+    expect(messages[0]!.content).toContain("wake_parent");
+    expect(messages[0]!.content).not.toContain("morning");
+    expect(messages[1]!.content).toBe("Routine fired");
+  });
+
+  test("a Turn recorded before turn admission existed replays as chat", () => {
+    const events = log([
+      { type: "turn/start", turn: 1 },
+      { type: "step/start", turn: 1, step: 1 },
+      {
+        type: "user/message",
+        turn: 1,
+        step: 1,
+        messageId: "m-1",
+        text: "legacy",
+      },
+      { type: "step/end", turn: 1, step: 1, outcome: "completed" },
+      { type: "turn/end", turn: 1, outcome: "completed" },
+      ...turn(2, "chat", "now", "then"),
+    ]);
+    expect(scoped(events).map((message) => message.content)).toEqual([
+      "legacy",
+      "now",
+      "then",
+    ]);
+  });
+
+  test("the admission markers and the open turn are read off the log", () => {
+    const events = log([
+      ...turn(1, "chat", "one", "two"),
+      { type: "turn/start", turn: 2 },
+      { type: "turn/admission", turn: 2, turnType: "automation" },
+    ]);
+    expect(turnTypesByTurnV1(events).get(2)).toBe("automation");
+    expect(currentTurnV1(events)).toBe(2);
+  });
+
+  test("a derivation that disagrees with the log is a visible failure", () => {
+    const events = log(turn(1, "chat", "one", "two"));
+    expect(() =>
+      turnScopedMessagesV1({
+        events,
+        messages: [],
+        pointer: automationParentPointerV1,
+        sessionId: "bot:scout",
+      }),
+    ).toThrow("disagree about their length");
+  });
+});

package/src/history.ts

@@ -0,0 +1,108 @@
+// What history a Turn's model request is allowed to see.
+//
+// The Bot Durable Object keeps one ordered event log per Bot — the kernel's
+// reconstruction surface, and not something a Package may partition. But "what
+// enters a model request is Package policy", and this is that policy:
+//
+//  1. **A chat Turn sees only chat Turns.** Every event belonging to a Turn
+//     whose `turn/admission` records a turn type other than `chat` is dropped
+//     before the request is assembled. An automation firing therefore cannot
+//     mutate the visible conversation even though its events share the log.
+//
+//  2. **An automation Turn starts fresh.** It sees its own Turn and one
+//     pointer line naming the parent transcript — GrokBot's "fresh subagent…
+//     the parent transcript is a pointer, not copied into the prompt". The
+//     parent's messages are never copied, at any length.
+//
+// Memory is deliberately untouched by both rules. "The parent agent's shared
+// durable memories are available": Memory is injected as a prompt section, not
+// as history, so a firing keeps every tier the parent has.
+import {
+  currentTurnV1,
+  messageTurnsV1,
+  type LlmMessage,
+  type SessionEvent,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+
+export { currentTurnV1 };
+
+/**
+ * The turn type each Turn was admitted as. A Turn recorded before turn
+ * admission existed has no marker and replays as `chat`, which is what it was.
+ */
+export function turnTypesByTurnV1(
+  events: readonly SessionEvent[],
+): Map<number, TurnTypeV1> {
+  const types = new Map<number, TurnTypeV1>();
+  for (const event of events) {
+    if (event.type === "turn/admission") types.set(event.turn, event.turnType);
+  }
+  return types;
+}
+
+/**
+ * The pointer an automation Turn is given in place of the transcript.
+ *
+ * It names the conversation and says plainly that nothing from it is here, so
+ * the model does not infer that the parent had nothing to say. `wake_parent` is
+ * named because it is the only way back.
+ */
+export function automationParentPointerV1(input: {
+  sessionId: string;
+  chatTurns: number;
+}): string {
+  return [
+    "You are running as an automation Turn, not inside the conversation with your user.",
+    `The parent conversation is session "${input.sessionId}"; it has ${input.chatTurns} conversational ${
+      input.chatTurns === 1 ? "Turn" : "Turns"
+    } so far, and none of it has been copied into this prompt.`,
+    "Your shared durable memories, Skills and work tools are the parent's.",
+    "You cannot speak to the user from here. Call `wake_parent` with a complete hand-off when you are done; that message is the only thing the parent will see.",
+  ].join(" ");
+}
+
+export interface TurnScopedMessagesInputV1 {
+  events: readonly SessionEvent[];
+  messages: readonly LlmMessage[];
+  /** The parent-transcript pointer, used only on a non-chat Turn. */
+  pointer(input: { sessionId: string; chatTurns: number }): string;
+  sessionId: string;
+}
+
+/**
+ * The messages one Turn's request may carry, given the whole session log and
+ * the messages derived from it.
+ *
+ * Filtering happens here rather than at derivation because the durable log is
+ * one ordered sequence whose contiguity the kernel enforces: the Turn is seeded
+ * with the full history so its events keep their sequence, and only the request
+ * is narrowed.
+ */
+export function turnScopedMessagesV1(
+  input: TurnScopedMessagesInputV1,
+): LlmMessage[] {
+  const turns = messageTurnsV1(input.events);
+  if (turns.length !== input.messages.length) {
+    throw new Error(
+      "session history and derived messages disagree about their length",
+    );
+  }
+  const types = turnTypesByTurnV1(input.events);
+  const current = currentTurnV1(input.events);
+  const chatTurn = (turn: number) => (types.get(turn) ?? "chat") === "chat";
+  if (chatTurn(current)) {
+    return input.messages.filter((_, index) => chatTurn(turns[index]!));
+  }
+  const own = input.messages.filter((_, index) => turns[index] === current);
+  const chatTurns = new Set(
+    turns.filter((turn) => turn !== current && chatTurn(turn)),
+  ).size;
+  return [
+    {
+      role: "user",
+      content: input.pointer({ sessionId: input.sessionId, chatTurns }),
+    },
+    ...own,
+  ];
+}

package/src/host.ts

@@ -0,0 +1,20 @@
+import type { Entry } from "@cordisjs/plugin-webui";
+import type { Context } from "cordis";
+import type { FrockBotWebData } from "./shared.ts";
+
+export function addFrockBotWebEntry(
+  ctx: Context,
+  data: FrockBotWebData,
+): Entry<FrockBotWebData> {
+  const packageUrl = import.meta.resolve("@frockbot/plugin-shell/package.json");
+  return ctx.webui.addEntry<FrockBotWebData>(
+    {
+      modulePath: "@frockbot/plugin-shell",
+      baseUrl: packageUrl,
+      source: "./src/client/index.ts",
+      manifest: "./dist/manifest.json",
+      routes: ["/"],
+    },
+    data,
+  );
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./host.ts";
+export * from "./shared.ts";

package/src/manifest.ts

@@ -0,0 +1,3 @@
+import manifest from "../frockbot.json" with { type: "json" };
+
+export default manifest;