@frockbot/kernel-contracts 0.0.0 → 0.1.1

package/src/skills.ts

@@ -0,0 +1,164 @@
+// How a Turn names one Skill.
+//
+// A `SkillRefV1` is the wire identity of a Skill: it crosses the client's turn
+// command, the Bot Durable Object's run RPC, the Agent loop's queued input, and
+// the durable session log. That is why it lives in the kernel rather than in
+// `plugin-skills` — "Cross-runtime communication uses narrow, versioned DTOs,
+// and every inbound value is decoded at its seam", and the seam here is a
+// kernel event. What a ref *resolves to* is Package policy and stays in
+// `plugin-skills`: the kernel holds the name and no opinion about the file.
+//
+// All four sources are declared at once even though only `bot` has a producer
+// today. The value is durable — it is recorded in `input/queued` and in
+// `skill/invoked` — so admitting a new source later would be a wire change in
+// every decoder between the composer and the event log. Declaring them now
+// means the Skills reach that adds User-global, managed and plugin-borne
+// Skills adds no codec change at all.
+
+/** Where a Skill comes from. Only `bot` has a producer today. */
+export type SkillRefSourceV1 = "bot" | "user" | "managed" | "plugin";
+
+/** The declared sources, in the catalog's canonical ordering. */
+export const SKILL_REF_SOURCES_V1: readonly SkillRefSourceV1[] = [
+  "bot",
+  "user",
+  "managed",
+  "plugin",
+];
+
+/**
+ * One Skill named for invocation.
+ *
+ * `packageId` is present exactly when `source` is `plugin`: a plugin-borne
+ * Skill is only unique within the Package that ships it, and every other
+ * source is unique on its slug alone. Refs are therefore globally unique and
+ * there is no shadowing rule.
+ */
+export interface SkillRefV1 {
+  schemaVersion: 1;
+  source: SkillRefSourceV1;
+  slug: string;
+  packageId?: string;
+}
+
+/** Most Skills one Turn may invoke. */
+export const MAX_INVOKED_SKILLS_V1 = 3;
+
+const SKILL_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const SKILL_PACKAGE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+/** True when a slug is well formed. Total; never throws. */
+export function isSkillRefSlugV1(value: unknown): value is string {
+  return typeof value === "string" && SKILL_SLUG_PATTERN.test(value);
+}
+
+/** The canonical string form: `bot/<slug>`, `plugin/<packageId>/<slug>`. */
+export function formatSkillRefV1(ref: SkillRefV1): string {
+  return ref.source === "plugin"
+    ? `plugin/${ref.packageId}/${ref.slug}`
+    : `${ref.source}/${ref.slug}`;
+}
+
+/**
+ * Reads the canonical string form back. Returns `undefined` rather than
+ * throwing: a ref arriving as text is untrusted input like any other.
+ */
+export function parseSkillRefV1(value: unknown): SkillRefV1 | undefined {
+  if (typeof value !== "string") return undefined;
+  const segments = value.split("/");
+  const source = SKILL_REF_SOURCES_V1.find(
+    (candidate) => candidate === segments[0],
+  );
+  if (!source) return undefined;
+  if (source === "plugin") {
+    if (segments.length !== 3) return undefined;
+    const packageId = segments[1] ?? "";
+    const slug = segments[2] ?? "";
+    if (!SKILL_PACKAGE_ID_PATTERN.test(packageId)) return undefined;
+    if (!SKILL_SLUG_PATTERN.test(slug)) return undefined;
+    return { schemaVersion: 1, source, slug, packageId };
+  }
+  if (segments.length !== 2) return undefined;
+  const slug = segments[1] ?? "";
+  if (!SKILL_SLUG_PATTERN.test(slug)) return undefined;
+  return { schemaVersion: 1, source, slug };
+}
+
+/**
+ * The strict decoder for one ref crossing a seam. Exact keys: an unknown field
+ * is a refusal, never a value carried through to durable state.
+ */
+export function decodeSkillRefV1(
+  value: unknown,
+  label = "skill ref",
+): SkillRefV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  const candidate = value as Record<string, unknown>;
+  const allowed = new Set(["schemaVersion", "source", "slug", "packageId"]);
+  for (const key of Reflect.ownKeys(candidate)) {
+    if (typeof key !== "string" || !allowed.has(key)) {
+      throw new Error(`${label} has unknown fields`);
+    }
+  }
+  if (candidate.schemaVersion !== 1) {
+    throw new Error(`${label}.schemaVersion is invalid`);
+  }
+  const source = SKILL_REF_SOURCES_V1.find(
+    (declared) => declared === candidate.source,
+  );
+  if (!source) throw new Error(`${label}.source is invalid`);
+  if (!isSkillRefSlugV1(candidate.slug)) {
+    throw new Error(`${label}.slug is invalid`);
+  }
+  if (source === "plugin") {
+    if (
+      typeof candidate.packageId !== "string" ||
+      !SKILL_PACKAGE_ID_PATTERN.test(candidate.packageId)
+    ) {
+      throw new Error(`${label}.packageId is invalid`);
+    }
+    return {
+      schemaVersion: 1,
+      source,
+      slug: candidate.slug,
+      packageId: candidate.packageId,
+    };
+  }
+  if (candidate.packageId !== undefined) {
+    // A packageId on a non-plugin ref would name a Package that has nothing to
+    // do with the Skill, so it is a refusal rather than an ignored field.
+    throw new Error(`${label}.packageId is only valid on a plugin Skill`);
+  }
+  return { schemaVersion: 1, source, slug: candidate.slug };
+}
+
+/**
+ * The strict decoder for the list one Turn invokes. Bounded at
+ * {@link MAX_INVOKED_SKILLS_V1}, and duplicates are refused: invoking the same
+ * Skill twice would expand its body twice with no way to say which won.
+ */
+export function decodeSkillRefsV1(
+  value: unknown,
+  label = "skill refs",
+): SkillRefV1[] {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  if (value.length > MAX_INVOKED_SKILLS_V1) {
+    throw new Error(
+      `${label} may name at most ${MAX_INVOKED_SKILLS_V1} Skills`,
+    );
+  }
+  const refs = value.map((entry, index) =>
+    decodeSkillRefV1(entry, `${label}[${index}]`),
+  );
+  const seen = new Set<string>();
+  for (const ref of refs) {
+    const canonical = formatSkillRefV1(ref);
+    if (seen.has(canonical)) {
+      throw new Error(`${label} names "${canonical}" more than once`);
+    }
+    seen.add(canonical);
+  }
+  return refs;
+}

package/src/tool-attachments.test.ts

@@ -0,0 +1,100 @@
+// Tool result attachments: what may be recorded, and what may not.
+//
+// The one rule worth a suite of its own is that resolved bytes are never
+// durable. The session event log is one Durable Object value; a base64
+// screenshot recorded in it would be a record that grows past what the object
+// can hold, so the decoder refuses `dataBase64` on the durable side rather
+// than trimming it somewhere further down.
+import { describe, expect, test } from "bun:test";
+import {
+  decodeToolAttachmentsV1,
+  decodeSessionEvent,
+  type ToolAttachmentV1,
+} from "./types.js";
+
+const HASH = "a".repeat(64);
+
+const attachment: ToolAttachmentV1 = {
+  kind: "image",
+  mediaType: "image/png",
+  workspacePath: {
+    root: {
+      kind: "package-declared",
+      userId: "user-1",
+      packageId: "computer",
+      rootId: "screenshots",
+    },
+    path: "bot-1/run-9-1.png",
+  },
+  contentHash: HASH,
+  bytes: 2048,
+};
+
+describe("decodeToolAttachmentsV1", () => {
+  test("accepts an exact image reference", () => {
+    expect(decodeToolAttachmentsV1([attachment], "attachments", true)).toEqual([
+      attachment,
+    ]);
+  });
+
+  test("refuses resolved bytes on the durable side and accepts them in a request", () => {
+    const resolved = [{ ...attachment, dataBase64: "AAAA" }];
+    expect(() =>
+      decodeToolAttachmentsV1(resolved, "attachments", true),
+    ).toThrow(/never durable/);
+    expect(decodeToolAttachmentsV1(resolved, "attachments", false)).toEqual(
+      resolved,
+    );
+  });
+
+  test("refuses an unknown media type, a bad hash, and an unknown field", () => {
+    expect(() =>
+      decodeToolAttachmentsV1(
+        [{ ...attachment, mediaType: "application/pdf" }],
+        "attachments",
+        true,
+      ),
+    ).toThrow(/mediaType/);
+    expect(() =>
+      decodeToolAttachmentsV1(
+        [{ ...attachment, contentHash: "short" }],
+        "attachments",
+        true,
+      ),
+    ).toThrow(/sha-256/);
+    expect(() =>
+      decodeToolAttachmentsV1(
+        [{ ...attachment, extra: 1 }],
+        "attachments",
+        true,
+      ),
+    ).toThrow(/invalid fields/);
+  });
+});
+
+describe("a recorded tool result", () => {
+  test("carries its attachments through the session event decoder", () => {
+    const event = {
+      type: "tool/result" as const,
+      seq: 0,
+      timestamp: "2026-08-31T00:00:00.000Z",
+      turn: 1,
+      step: 1,
+      occurrenceId: "1:1:0",
+      name: "computer_screenshot",
+      content: "{}",
+      isError: false,
+      status: "completed" as const,
+      attachments: [attachment],
+    };
+    expect(decodeSessionEvent(event)).toMatchObject({
+      attachments: [attachment],
+    });
+    expect(() =>
+      decodeSessionEvent({
+        ...event,
+        attachments: [{ ...attachment, dataBase64: "AAAA" }],
+      }),
+    ).toThrow(/never durable/);
+  });
+});

package/src/tool-execution.ts

@@ -0,0 +1,220 @@
+// Importing the augmented module is what merges these declarations into cordis.
+import type {} from "cordis";
+import {
+  TURN_TYPES_V1,
+  type ToolAttachmentV1,
+  type ToolCall,
+  type ToolSchema,
+  type TurnTypeV1,
+} from "./types.js";
+
+export interface ToolExecutionContext {
+  botId: string;
+  agentId: string;
+  sessionId: string;
+  compositionGenerationId: string;
+  /** Stable durable occurrence identity for provider idempotency and recovery. */
+  effectId: string;
+  /** Exact durable call; reconciliation fails closed when it is absent. */
+  toolCall?: ToolCall;
+  /** The turn type this Turn was admitted as. */
+  turnType: TurnTypeV1;
+  /**
+   * The subagent role this Turn was admitted under, on a `subagent` Turn that
+   * declared one. An opaque string here for the same reason `turnType` is: the
+   * kernel carries it and narrows the catalog by it, and what any role name
+   * means is Package policy.
+   */
+  subagentRole?: string;
+  signal: AbortSignal;
+}
+
+export interface ToolExecutionResult {
+  content: string;
+  isError: boolean;
+  /**
+   * The Turn ends once this result is recorded: the Agent loop closes the step
+   * as `completed` and makes no further model request. Declared per *result*,
+   * not per definition, because one tool can end a Turn for one payload and
+   * not another. The loop carries the boolean; what earns it is Package
+   * policy.
+   */
+  endsTurn?: boolean;
+  /**
+   * Binaries this result produced, named by their durable Workspace path.
+   *
+   * They reach the model only where the model-invocation adapter can show
+   * them; an adapter that cannot drops them and says so in the text, so a tool
+   * that returns an image is never silently answered with nothing.
+   */
+  attachments?: ToolAttachmentV1[];
+}
+
+/** The turn types — and, optionally, the subagent roles — an admission names. */
+export interface TurnAdmissionV1 {
+  /**
+   * The turn types this tool is offered on. Optional, so a declaration can
+   * narrow the *role* dimension alone: a work tool that every turn type may
+   * call but only an `executor` subagent may reach says exactly that, and does
+   * not have to restate the full turn-type list to do it.
+   */
+  turnTypes?: TurnTypeV1[];
+  /**
+   * The subagent roles this tool is offered to on a `subagent` Turn. Absent
+   * means every role, exactly as an absent `admission` means every turn type:
+   * narrowing is always something a declaration *does*, never something the
+   * kernel assumes. The strings are opaque here.
+   */
+  subagentRoles?: string[];
+}
+
+/**
+ * The turn types a registered tool may be offered on: its own declaration,
+ * bounded by the durable manifest ceiling of the Capability that contributed
+ * it. An absent declaration is every turn type — every tool shipped today is a
+ * work tool — and an absent ceiling is a manifest that set no bound. The
+ * result keeps {@link TURN_TYPES_V1} order and holds no duplicates.
+ */
+export function admittedTurnTypesV1(
+  declared: readonly TurnTypeV1[] | undefined,
+  ceiling: readonly TurnTypeV1[] | undefined,
+): TurnTypeV1[] {
+  return TURN_TYPES_V1.filter(
+    (turnType) =>
+      (declared === undefined || declared.includes(turnType)) &&
+      (ceiling === undefined || ceiling.includes(turnType)),
+  );
+}
+
+/**
+ * The subagent roles a registered tool may be offered to: its own declaration,
+ * bounded by the durable manifest ceiling of the Capability that contributed
+ * it. `undefined` — both absent — is every role. The result is deduplicated
+ * and keeps the declaration's order.
+ */
+export function admittedSubagentRolesV1(
+  declared: readonly string[] | undefined,
+  ceiling: readonly string[] | undefined,
+): readonly string[] | undefined {
+  if (declared === undefined && ceiling === undefined) return undefined;
+  const source = declared ?? ceiling ?? [];
+  const bound = declared === undefined ? undefined : ceiling;
+  const admitted: string[] = [];
+  for (const role of source) {
+    if (bound !== undefined && !bound.includes(role)) continue;
+    if (!admitted.includes(role)) admitted.push(role);
+  }
+  return admitted;
+}
+
+/**
+ * Whether a tool with these admitted roles is offered to one Turn's role. A
+ * Turn that names no role is not narrowed at all — role is a *second* ceiling
+ * dimension, and a Turn outside the subagent world has no coordinate on it.
+ */
+export function isSubagentRoleAdmittedV1(
+  admitted: readonly string[] | undefined,
+  role: string | undefined,
+): boolean {
+  if (role === undefined || admitted === undefined) return true;
+  return admitted.includes(role);
+}
+
+export type ToolEffectReconciliation =
+  | { status: "recovered"; result: ToolExecutionResult }
+  | { status: "unavailable"; reason: string };
+
+export interface ToolDefinition extends ToolSchema {
+  idempotent?: boolean;
+  /** The turn types this tool is offered on. Absent means all of them. */
+  admission?: TurnAdmissionV1;
+  validate?(input: unknown): boolean;
+  execute(
+    input: unknown,
+    context: ToolExecutionContext,
+  ): Promise<ToolExecutionResult>;
+  reconcile?(
+    input: unknown,
+    context: ToolExecutionContext,
+  ): Promise<ToolEffectReconciliation>;
+}
+
+export type ToolPreparation =
+  | { kind: "ready"; call: ToolCall; idempotent: boolean }
+  | { kind: "denied"; call: ToolCall; result: ToolExecutionResult };
+
+/** The kernel-declared tool execution interface. Implemented by a Package. */
+export interface ToolExecution {
+  /** The catalog trimmed to what this turn type — and role — admits. */
+  schemas(admission: {
+    turnType: TurnTypeV1;
+    subagentRole?: string;
+  }): ToolSchema[];
+  prepare(
+    call: ToolCall,
+    context: ToolExecutionContext,
+  ): Promise<ToolPreparation>;
+  executePrepared(
+    preparation: Extract<ToolPreparation, { kind: "ready" }>,
+    context: ToolExecutionContext,
+  ): Promise<ToolExecutionResult>;
+  /**
+   * Recovers the outcome of an already-admitted tool effect without starting a
+   * second one, so an interrupted Turn never duplicates a side effect.
+   */
+  reconcilePrepared(
+    preparation: Extract<ToolPreparation, { kind: "ready" }>,
+    context: ToolExecutionContext,
+  ): Promise<ToolEffectReconciliation>;
+}
+
+/**
+ * What the host that mounts a Contribution knows about the tool and the
+ * Package's manifest, which the tool itself cannot be trusted to restate.
+ */
+export interface ToolRegistrationOptions {
+  /**
+   * The durable manifest ceiling of the Capability contributing this tool. A
+   * tool may not be admitted onto a turn type its manifest does not list.
+   */
+  admissionCeiling?: readonly TurnTypeV1[];
+  /**
+   * The same durable ceiling on the second dimension: the subagent roles the
+   * Capability's manifest lists. Absent is a manifest that set no bound.
+   */
+  subagentRoleCeiling?: readonly string[];
+}
+
+/** Contributing Packages register tool definitions through this surface. */
+export interface ToolRegistration {
+  register(
+    definition: ToolDefinition,
+    options?: ToolRegistrationOptions,
+  ): () => void;
+}
+
+declare module "cordis" {
+  interface Context {
+    tools: ToolExecution & ToolRegistration;
+  }
+
+  interface Events {
+    "tools/pre-execute": (
+      call: ToolCall,
+      context: ToolExecutionContext,
+      next: () => Promise<ToolPreparation>,
+    ) => Promise<ToolPreparation>;
+    "tools/execute": (
+      call: ToolCall,
+      context: ToolExecutionContext,
+      next: () => Promise<ToolExecutionResult>,
+    ) => Promise<ToolExecutionResult>;
+    "tools/post-execute": (
+      call: ToolCall,
+      result: ToolExecutionResult,
+      context: ToolExecutionContext,
+      next: () => Promise<ToolExecutionResult>,
+    ) => Promise<ToolExecutionResult>;
+    "tools/result": (call: ToolCall, result: ToolExecutionResult) => void;
+  }
+}

package/src/turn-history.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, test } from "bun:test";
+import { currentTurnV1, messageTurnsV1 } from "./turn-history.js";
+import type { SessionEvent } from "./types.js";
+
+const events: SessionEvent[] = [
+  {
+    type: "turn/start",
+    turn: 1,
+    seq: 0,
+    timestamp: "2026-09-01T00:00:00.000Z",
+  },
+  {
+    type: "user/message",
+    turn: 1,
+    step: 0,
+    messageId: "m-1",
+    text: "first",
+    seq: 1,
+    timestamp: "2026-09-01T00:00:01.000Z",
+  },
+  {
+    type: "assistant/message",
+    turn: 1,
+    step: 1,
+    text: "answer",
+    toolCalls: [],
+    requestId: "r-1",
+    seq: 2,
+    timestamp: "2026-09-01T00:00:02.000Z",
+  },
+  {
+    type: "turn/start",
+    turn: 2,
+    seq: 3,
+    timestamp: "2026-09-01T00:00:03.000Z",
+  },
+  {
+    type: "user/message",
+    turn: 2,
+    step: 0,
+    messageId: "m-2",
+    text: "second",
+    seq: 4,
+    timestamp: "2026-09-01T00:00:04.000Z",
+  },
+];
+
+describe("turn history", () => {
+  test("names the Turn each derived message belongs to", () => {
+    expect(messageTurnsV1(events)).toEqual([1, 1, 2]);
+    expect(currentTurnV1(events)).toBe(2);
+    expect(currentTurnV1([])).toBe(0);
+  });
+});

package/src/turn-history.ts

@@ -0,0 +1,33 @@
+// Which of a Session's derived messages belong to the Turn being assembled.
+//
+// The Bot Durable Object keeps one ordered event log per Bot, and the kernel
+// enforces its contiguity: a Turn is always seeded with the whole history so
+// its events keep their sequence. "What enters a model request is Package
+// policy", so the *narrowing* happens when the request is assembled, and these
+// are the two mechanical facts every narrowing policy needs — which Turn each
+// derived message belongs to, and which Turn is currently open.
+//
+import type { SessionEvent } from "./types.js";
+
+/** The event types `Session.deriveMessages` turns into a message, in order. */
+const MESSAGE_EVENT_TYPES = new Set([
+  "user/message",
+  "assistant/message",
+  "tool/result",
+]);
+
+/** The Turn each derived message belongs to, in the order they were derived. */
+export function messageTurnsV1(events: readonly SessionEvent[]): number[] {
+  const turns: number[] = [];
+  for (const event of events) {
+    if (!MESSAGE_EVENT_TYPES.has(event.type)) continue;
+    turns.push("turn" in event ? event.turn : 0);
+  }
+  return turns;
+}
+
+/** The Turn a request is being assembled inside: the last one started. */
+export function currentTurnV1(events: readonly SessionEvent[]): number {
+  const started = events.findLast((event) => event.type === "turn/start");
+  return started?.type === "turn/start" ? started.turn : 0;
+}

package/src/turn-type.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, test } from "bun:test";
+import {
+  admittedTurnTypesV1,
+  decodeSessionEvent,
+  decodeTurnTypeV1,
+  TURN_TYPES_V1,
+  type SessionEvent,
+} from "./index.js";
+
+const timestamp = "2026-08-31T00:00:00.000Z";
+
+function durable(event: Record<string, unknown>): unknown {
+  return { ...event, seq: 0, timestamp };
+}
+
+describe("TurnTypeV1", () => {
+  test("names every turn type the admission vocabulary declares", () => {
+    expect([...TURN_TYPES_V1]).toEqual(["chat", "automation", "subagent"]);
+    for (const turnType of TURN_TYPES_V1) {
+      expect(decodeTurnTypeV1(turnType)).toBe(turnType);
+    }
+  });
+
+  test("rejects a value outside the declared vocabulary", () => {
+    for (const invalid of ["Chat", "routine", "", 1, null, undefined, {}]) {
+      expect(() => decodeTurnTypeV1(invalid)).toThrow(/turn type is invalid/);
+    }
+  });
+});
+
+describe("turn/admission", () => {
+  test("decodes the admitted turn type of a Turn", () => {
+    const event = durable({
+      type: "turn/admission",
+      turn: 3,
+      turnType: "automation",
+    });
+    expect(decodeSessionEvent(event)).toMatchObject({
+      type: "turn/admission",
+      turn: 3,
+      turnType: "automation",
+    });
+  });
+
+  test("rejects an unknown turn type and any extra or missing key", () => {
+    expect(() =>
+      decodeSessionEvent(
+        durable({ type: "turn/admission", turn: 1, turnType: "routine" }),
+      ),
+    ).toThrow(/turnType is invalid/);
+    expect(() =>
+      decodeSessionEvent(durable({ type: "turn/admission", turn: 1 })),
+    ).toThrow(/invalid fields/);
+    expect(() =>
+      decodeSessionEvent(
+        durable({
+          type: "turn/admission",
+          turn: 1,
+          turnType: "chat" as const,
+          extra: true,
+        }),
+      ),
+    ).toThrow(/invalid fields/);
+  });
+
+  test("leaves a pre-change turn/start decoding exactly as it did", () => {
+    const started: SessionEvent = decodeSessionEvent(
+      durable({ type: "turn/start", turn: 1 }),
+    );
+    expect(started).toMatchObject({ type: "turn/start", turn: 1 });
+    expect(() =>
+      decodeSessionEvent(
+        durable({ type: "turn/start", turn: 1, turnType: "chat" }),
+      ),
+    ).toThrow(/invalid fields/);
+  });
+});
+
+describe("admittedTurnTypesV1", () => {
+  test("admits every turn type when neither the tool nor the manifest bounds it", () => {
+    expect(admittedTurnTypesV1(undefined, undefined)).toEqual([
+      ...TURN_TYPES_V1,
+    ]);
+  });
+
+  test("narrows a tool declaration within the manifest ceiling", () => {
+    expect(
+      admittedTurnTypesV1(["chat", "automation"], ["automation", "subagent"]),
+    ).toEqual(["automation"]);
+    expect(admittedTurnTypesV1(["chat"], undefined)).toEqual(["chat"]);
+    expect(admittedTurnTypesV1(undefined, ["automation"])).toEqual([
+      "automation",
+    ]);
+  });
+
+  test("keeps the declared vocabulary order and drops duplicates", () => {
+    expect(
+      admittedTurnTypesV1(["subagent", "chat", "chat"], undefined),
+    ).toEqual(["chat", "subagent"]);
+  });
+});