@frockbot/plugin-shell 0.0.0 → 0.1.1

package/src/agent.ts

@@ -0,0 +1,335 @@
+// The Shell's runtime Contribution: the Bot's voice to its User, and a child
+// Turn's hand-off to its parent.
+//
+// Two tools, and no authority of its own:
+//
+//  1. `send_to_user` (legacy alias `send_message`) — parity register row 57b.
+//     One tool carrying the typed payload union, admitted on chat turns only,
+//     recording each send as `send/to-user` on the durable log. Row 57c: a
+//     `widget` payload ends the Turn; row 53's `approval` payload is the only
+//     other one that does, and for the same reason — the Bot has nothing left
+//     to do until a person answers.
+//  3. One `agent/request` handler, which is where the transcript seam is: a
+//     chat Turn's request carries only chat Turns, and an automation Turn's
+//     carries its own Turn and a pointer to the parent it may not read. See
+//     `history.ts`.
+//
+//  2. `wake_parent` — row 40 / §2.13. One required `message`, a complete
+//     hand-off, admitted on automation and subagent turns only, and always
+//     ending the Turn. Delivering the hand-off into the parent's next
+//     conversational Turn is a later slice; this records it durably.
+//
+// It lives in `plugin-shell` because the Shell already owns the run DTO and
+// the WebUI that renders a send, so there is no cross-Package seam to cross.
+// Nothing here reaches the kernel: admission is a declaration the tool
+// registry enforces, and `endsTurn` is a boolean the Agent loop carries.
+import {
+  decodeSendToUserPayloadV1,
+  decodeTurnTypeV1,
+  type SendToUserPayloadV1,
+  type Session,
+  type ToolDefinition,
+  type ToolExecutionContext,
+  type ToolExecutionResult,
+  type TurnTypeV1,
+} from "@frockbot/kernel-contracts";
+// Merges the Agent loop's event declarations into the cordis Context type.
+import type {} from "@frockbot/kernel-agent-loop/agent";
+import { automationParentPointerV1, turnScopedMessagesV1 } from "./history.js";
+import type { Plugin } from "cordis";
+import manifest from "../frockbot.json" with { type: "json" };
+
+export const SEND_TO_USER_TOOL_V1 = "send_to_user";
+/** `SAND_LEGACY_SEND_MESSAGE_TOOL_NAME`: an alias, not a second tool. */
+export const SEND_MESSAGE_ALIAS_V1 = "send_message";
+export const WAKE_PARENT_TOOL_V1 = "wake_parent";
+
+/** The manifest Capability each tool is contributed under. */
+export const USER_VOICE_CAPABILITY_V1 = "user-voice";
+export const PARENT_HANDOFF_CAPABILITY_V1 = "parent-handoff";
+
+/**
+ * The durable ceiling the Shell's own manifest puts on a Capability, read back
+ * out of the manifest rather than restated here. A registration that drifts
+ * from the manifest is narrowed to the manifest, so the two cannot disagree
+ * about what a turn type admits.
+ */
+export function shellAdmissionCeilingV1(
+  capabilityId: string,
+): readonly TurnTypeV1[] | undefined {
+  const capabilities = (
+    manifest as {
+      configuration?: {
+        capabilities?: Array<{
+          id: string;
+          admission?: { turnTypes: string[] };
+        }>;
+      };
+    }
+  ).configuration?.capabilities;
+  const capability = capabilities?.find(
+    (candidate) => candidate.id === capabilityId,
+  );
+  const turnTypes = capability?.admission?.turnTypes;
+  if (!turnTypes) return undefined;
+  return turnTypes.map((turnType) =>
+    decodeTurnTypeV1(turnType, `shell capability "${capabilityId}" admission`),
+  );
+}
+
+function refusal(reason: string): ToolExecutionResult {
+  return { content: reason, isError: true };
+}
+
+/**
+ * The open step a Shell event belongs to. The session log is the
+ * reconstruction surface, so a send without its turn and step would not
+ * replay in place.
+ */
+function openStepPositionV1(
+  session: Session,
+  tool: string,
+): { turn: number; step: number } {
+  const started = session.events.findLast(
+    (event) => event.type === "step/start",
+  );
+  const ended = session.events.findLast((event) => event.type === "step/end");
+  if (started?.type !== "step/start") {
+    throw new Error(`${tool} has no open step to record against`);
+  }
+  if (
+    ended?.type === "step/end" &&
+    ended.turn === started.turn &&
+    ended.step === started.step
+  ) {
+    throw new Error(`${tool} has no open step to record against`);
+  }
+  return { turn: started.turn, step: started.step };
+}
+
+/** What a recorded send tells the model it did. */
+function sendAcknowledgement(payload: SendToUserPayloadV1): string {
+  switch (payload.type) {
+    case "text":
+      return "Sent to the user.";
+    case "attachment":
+      return "Attachment sent to the user.";
+    case "widget":
+      return "Question sent to the user. This Turn is over; their answer arrives as a new Turn.";
+    case "secret-request":
+      return "Secret request sent to the user.";
+    case "agent-card":
+      return "Agent card sent to the user.";
+    case "connect-card":
+      return "Connect card sent to the user. Only they can complete the authorization; you have recorded the request, not granted it.";
+    case "approval":
+      // Deliberately not "requested permission": nothing has been granted, and
+      // the Turn is over whatever the answer turns out to be.
+      return "Approval requested. This Turn is over; the decision reaches you as durable input on a later Turn.";
+  }
+}
+
+const SEND_TO_USER_DESCRIPTION = [
+  "Speak to the user. This is the only way to say anything the user sees.",
+  "The payload is one of:",
+  '{"type":"text","text":"…"}',
+  '{"type":"attachment","url":"https://…","name":"…","mediaType":"…"}',
+  '{"type":"widget","widget":{"prompt":"…","helpText":"…","options":["…"],"allowCustom":false,"dismissOnMoveOn":false}}',
+  '{"type":"secret-request","prompt":"…","secretName":"…"}',
+  '{"type":"agent-card","agentId":"…","title":"…","body":"…"}',
+  '{"type":"connect-card","connectionId":"…","title":"…","body":"…"}',
+  '{"type":"approval","approvalId":"…","action":"…","rationale":"…","risk":"low|medium|high","expiresInSeconds":86400}',
+  "A widget asks the user a question with 1 to 6 options and ends your Turn;",
+  "their answer arrives as a new Turn. An approval asks the user to allow one",
+  "action you must not take without them; it also ends your Turn, and their",
+  "decision — or its expiry — reaches you as input on a later Turn.",
+  "Every other payload leaves the Turn running.",
+].join(" ");
+
+const SEND_TO_USER_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    payload: {
+      type: "object",
+      description: "One typed send payload, as described by this tool.",
+    },
+  },
+  required: ["payload"],
+  additionalProperties: false,
+} as const;
+
+function createSendToUserTool(
+  name: string,
+  sessions: { get(sessionId: string): Session | undefined },
+): ToolDefinition {
+  return {
+    name,
+    description: SEND_TO_USER_DESCRIPTION,
+    inputSchema: structuredClone(SEND_TO_USER_INPUT_SCHEMA) as Record<
+      string,
+      unknown
+    >,
+    admission: { turnTypes: ["chat"] },
+    validate: (input: unknown) =>
+      typeof input === "object" && input !== null && !Array.isArray(input),
+    execute: async (
+      input: unknown,
+      context: ToolExecutionContext,
+    ): Promise<ToolExecutionResult> => {
+      const record = input as Record<string, unknown>;
+      let payload: SendToUserPayloadV1;
+      try {
+        payload = decodeSendToUserPayloadV1(record.payload, `${name}.payload`);
+      } catch (error) {
+        return refusal(
+          `${name} was refused: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      const session = sessions.get(context.sessionId);
+      if (!session) {
+        return refusal(
+          `${name} was refused: session "${context.sessionId}" is unavailable, so the send cannot be recorded`,
+        );
+      }
+      let position: { turn: number; step: number };
+      try {
+        position = openStepPositionV1(session, name);
+      } catch (error) {
+        return refusal(
+          `${name} was refused: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      session.append({
+        type: "send/to-user",
+        ...position,
+        occurrenceId: context.effectId,
+        payload,
+      });
+      await session.flush();
+      return {
+        content: sendAcknowledgement(payload),
+        isError: false,
+        // Row 57c: a widget ends the Turn, and row 53's approval card is the
+        // only other payload that does. The decision is per result, so the
+        // same tool leaves a text send running.
+        ...(payload.type === "widget" || payload.type === "approval"
+          ? { endsTurn: true }
+          : {}),
+      };
+    },
+  };
+}
+
+function createWakeParentTool(sessions: {
+  get(sessionId: string): Session | undefined;
+}): ToolDefinition {
+  return {
+    name: WAKE_PARENT_TOOL_V1,
+    description:
+      "Hand off to your parent conversation and end this Turn. `message` must be a complete hand-off: the parent sees only what you write here.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        message: {
+          type: "string",
+          description: "The complete hand-off the parent Turn receives.",
+        },
+      },
+      required: ["message"],
+      additionalProperties: false,
+    },
+    admission: { turnTypes: ["automation", "subagent"] },
+    validate: (input: unknown) =>
+      typeof input === "object" && input !== null && !Array.isArray(input),
+    execute: async (
+      input: unknown,
+      context: ToolExecutionContext,
+    ): Promise<ToolExecutionResult> => {
+      const message = (input as Record<string, unknown>).message;
+      if (typeof message !== "string" || message.trim().length === 0) {
+        return refusal(
+          `${WAKE_PARENT_TOOL_V1} was refused: message must be a non-empty string`,
+        );
+      }
+      if (message.length > WAKE_PARENT_MESSAGE_LIMIT_V1) {
+        return refusal(
+          `${WAKE_PARENT_TOOL_V1} was refused: message exceeds ${WAKE_PARENT_MESSAGE_LIMIT_V1} characters`,
+        );
+      }
+      const session = sessions.get(context.sessionId);
+      if (!session) {
+        return refusal(
+          `${WAKE_PARENT_TOOL_V1} was refused: session "${context.sessionId}" is unavailable, so the hand-off cannot be recorded`,
+        );
+      }
+      let position: { turn: number; step: number };
+      try {
+        position = openStepPositionV1(session, WAKE_PARENT_TOOL_V1);
+      } catch (error) {
+        return refusal(
+          `${WAKE_PARENT_TOOL_V1} was refused: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+      session.append({
+        type: "wake/parent",
+        ...position,
+        occurrenceId: context.effectId,
+        message,
+      });
+      await session.flush();
+      // §2.13: calling it ends the turn, whatever the parent later does with it.
+      return {
+        content: "Handed off to the parent conversation. This Turn is over.",
+        isError: false,
+        endsTurn: true,
+      };
+    },
+  };
+}
+
+export const WAKE_PARENT_MESSAGE_LIMIT_V1 = 32_000;
+
+/**
+ * The Shell's runtime Contribution. Registers the user-facing send tool, its
+ * legacy alias, and the parent hand-off, each bounded by the turn types its
+ * manifest Capability declares.
+ */
+export const shellAgentPlugin: Plugin.Function = (ctx) => {
+  const userVoice = shellAdmissionCeilingV1(USER_VOICE_CAPABILITY_V1);
+  const parentHandoff = shellAdmissionCeilingV1(PARENT_HANDOFF_CAPABILITY_V1);
+  const disposers = [
+    ctx.tools.register(
+      createSendToUserTool(SEND_TO_USER_TOOL_V1, ctx.sessions),
+      userVoice ? { admissionCeiling: userVoice } : undefined,
+    ),
+    ctx.tools.register(
+      createSendToUserTool(SEND_MESSAGE_ALIAS_V1, ctx.sessions),
+      userVoice ? { admissionCeiling: userVoice } : undefined,
+    ),
+    ctx.tools.register(
+      createWakeParentTool(ctx.sessions),
+      parentHandoff ? { admissionCeiling: parentHandoff } : undefined,
+    ),
+    // Applied after the rest of the chain, so this Package has the last word on
+    // what history a request carries — the one rule the visible transcript
+    // rests on.
+    ctx.on("agent/request", async (agent, _request, _signal, next) => {
+      const proposed = await next();
+      return {
+        ...proposed,
+        messages: turnScopedMessagesV1({
+          events: agent.session.events,
+          messages: proposed.messages,
+          pointer: automationParentPointerV1,
+          sessionId: agent.session.id,
+        }),
+      };
+    }),
+  ];
+  return () => {
+    for (const dispose of disposers.toReversed()) dispose();
+  };
+};
+shellAgentPlugin.inject = ["tools", "sessions"];
+
+export default shellAgentPlugin;

package/src/approvals.test.ts

@@ -0,0 +1,224 @@
+// The approval record: what a Turn writes, what a decision may say, and how
+// long a question may go unanswered.
+import { describe, expect, test } from "bun:test";
+import {
+  approvalExpiresAtV1,
+  approvalKeyV1,
+  approvalNotificationBodyV1,
+  approvalSendsV1,
+  approvalTerminalRecordsV1,
+  decodeApprovalDecisionCommandV1,
+  decodeApprovalListViewV1,
+  decodeApprovalRecordV1,
+  projectApprovalCardV1,
+  trimmableApprovalKeysV1,
+  APPROVAL_DEFAULT_EXPIRY_SECONDS,
+  APPROVAL_MAX_EXPIRY_SECONDS,
+  APPROVAL_MIN_EXPIRY_SECONDS,
+  APPROVAL_RETENTION_LIMIT,
+  type ApprovalRecordV1,
+} from "./approvals.js";
+
+const NOW = "2026-08-31T00:00:00.000Z";
+
+function send(overrides: Record<string, unknown> = {}) {
+  return {
+    type: "send/to-user",
+    payload: {
+      type: "approval",
+      approvalId: "ap-1",
+      action: "Delete the staging database",
+      risk: "high",
+      ...overrides,
+    },
+  };
+}
+
+function record(overrides: Partial<ApprovalRecordV1> = {}): ApprovalRecordV1 {
+  return {
+    schemaVersion: 1,
+    approvalId: "ap-1",
+    runId: "run-1",
+    sessionId: "user-1:bot-1",
+    action: "Delete the staging database",
+    risk: "high",
+    createdAt: NOW,
+    expiresAt: approvalExpiresAtV1(NOW),
+    decision: "pending",
+    decidedBy: "pending",
+    ...overrides,
+  };
+}
+
+describe("the expiry window", () => {
+  test("defaults to a day and clamps a Bot's request to five minutes and a week", () => {
+    const day = Date.parse(approvalExpiresAtV1(NOW)) - Date.parse(NOW);
+    expect(day).toBe(APPROVAL_DEFAULT_EXPIRY_SECONDS * 1_000);
+    // A card that expires before anyone could reach it is a refusal dressed as
+    // a question, so a one-second window becomes the floor.
+    expect(Date.parse(approvalExpiresAtV1(NOW, 1)) - Date.parse(NOW)).toBe(
+      APPROVAL_MIN_EXPIRY_SECONDS * 1_000,
+    );
+    expect(
+      Date.parse(approvalExpiresAtV1(NOW, 400 * 24 * 60 * 60)) -
+        Date.parse(NOW),
+    ).toBe(APPROVAL_MAX_EXPIRY_SECONDS * 1_000);
+    // Inside the range the Bot's own number survives untouched.
+    expect(Date.parse(approvalExpiresAtV1(NOW, 3_600)) - Date.parse(NOW)).toBe(
+      3_600_000,
+    );
+  });
+
+  test("refuses a createdAt that is not a timestamp", () => {
+    expect(() => approvalExpiresAtV1("whenever")).toThrow("not a timestamp");
+  });
+});
+
+describe("the records a settled Turn writes", () => {
+  test("one pending record per approval send, keyed by the Bot's own id", async () => {
+    const records = await approvalTerminalRecordsV1({
+      run: {
+        runId: "run-1",
+        sessionId: "user-1:bot-1",
+        events: [
+          { type: "assistant/message" },
+          send(),
+          send({ approvalId: "ap-2", action: "Restart the host", risk: "low" }),
+        ],
+      },
+      now: NOW,
+      read: () => Promise.resolve(undefined),
+    });
+
+    expect(Object.keys(records).sort()).toEqual([
+      approvalKeyV1("ap-1"),
+      approvalKeyV1("ap-2"),
+    ]);
+    const first = decodeApprovalRecordV1(records[approvalKeyV1("ap-1")]);
+    expect(first).toMatchObject({
+      approvalId: "ap-1",
+      runId: "run-1",
+      sessionId: "user-1:bot-1",
+      decision: "pending",
+      decidedBy: "pending",
+      risk: "high",
+    });
+    expect(first.expiresAt).toBe(approvalExpiresAtV1(NOW));
+  });
+
+  test("a Turn with no approval send writes nothing", async () => {
+    expect(
+      await approvalTerminalRecordsV1({
+        run: {
+          runId: "run-1",
+          sessionId: "s",
+          events: [
+            { type: "send/to-user", payload: { type: "text" } } as never,
+          ],
+        },
+        now: NOW,
+        read: () => Promise.resolve(undefined),
+      }),
+    ).toEqual({});
+  });
+
+  test("a re-settled Turn leaves a decision somebody already made alone", async () => {
+    const decided = record({ decision: "approved", decidedBy: "user" });
+    const records = await approvalTerminalRecordsV1({
+      run: { runId: "run-1", sessionId: "s", events: [send()] },
+      now: NOW,
+      // A recovered Turn re-reads its own log; the record it would write is
+      // already there, and overwriting it would erase the answer.
+      read: <T>(key: string) =>
+        Promise.resolve(
+          (key === approvalKeyV1("ap-1") ? decided : undefined) as
+            T | undefined,
+        ),
+    });
+
+    expect(records).toEqual({});
+  });
+
+  test("the same card sent twice in one Turn is one decision", () => {
+    expect(
+      approvalSendsV1([send(), send({ action: "Delete it, really" })]).map(
+        (asked) => asked.action,
+      ),
+    ).toEqual(["Delete the staging database"]);
+  });
+});
+
+describe("the codecs", () => {
+  test("a record round-trips and refuses an unexpected key", () => {
+    const stored = record();
+    expect(decodeApprovalRecordV1(stored)).toEqual(stored);
+    expect(() =>
+      decodeApprovalRecordV1({ ...stored, decidedBy: "somebody" }),
+    ).toThrow("decidedBy");
+    expect(() =>
+      decodeApprovalRecordV1({ ...stored, decision: "maybe" }),
+    ).toThrow("decision");
+    expect(() => decodeApprovalRecordV1({ ...stored, extra: 1 })).toThrow(
+      'unexpected key "extra"',
+    );
+    const { expiresAt: _expiresAt, ...withoutExpiry } = stored;
+    expect(() => decodeApprovalRecordV1(withoutExpiry)).toThrow(
+      'missing "expiresAt"',
+    );
+  });
+
+  test("a decision command carries exactly one of two answers", () => {
+    expect(
+      decodeApprovalDecisionCommandV1({ schemaVersion: 1, decision: "denied" }),
+    ).toEqual({ schemaVersion: 1, decision: "denied" });
+    // Expiry is what the clock does, never what a person submits.
+    expect(() =>
+      decodeApprovalDecisionCommandV1({
+        schemaVersion: 1,
+        decision: "expired",
+      }),
+    ).toThrow("approved or denied");
+    expect(() =>
+      decodeApprovalDecisionCommandV1({
+        schemaVersion: 1,
+        decision: "approved",
+        approvalId: "ap-1",
+      }),
+    ).toThrow('unexpected key "approvalId"');
+  });
+
+  test("a listing round-trips through its own decoder", () => {
+    const view = {
+      schemaVersion: 1 as const,
+      botId: "bot-1",
+      approvals: [projectApprovalCardV1(record())],
+      pending: 1,
+    };
+
+    expect(decodeApprovalListViewV1(view)).toEqual(view);
+    // The projection never carries the session the Turn ran in.
+    expect(Object.keys(view.approvals[0]!).includes("sessionId")).toBe(false);
+  });
+});
+
+describe("retention", () => {
+  test("nothing is trimmed under the bound, and the oldest go over it", () => {
+    const keys = Array.from({ length: APPROVAL_RETENTION_LIMIT + 3 }, (_, i) =>
+      approvalKeyV1(`ap-${String(i).padStart(4, "0")}`),
+    );
+
+    expect(trimmableApprovalKeysV1(keys.slice(0, 3))).toEqual([]);
+    expect(trimmableApprovalKeysV1(keys)).toEqual(keys.slice(0, 3));
+  });
+
+  test("a high-risk notification body says so before it says what", () => {
+    expect(approvalNotificationBodyV1(send().payload as never)).toBe(
+      "High risk. Delete the staging database",
+    );
+    expect(
+      approvalNotificationBodyV1(
+        send({ risk: "low", action: "Rename a file" }).payload as never,
+      ),
+    ).toBe("Rename a file");
+  });
+});