@frockbot/plugin-authoring 0.0.0 → 0.1.1

package/frockbot.json

@@ -0,0 +1,18 @@
+{
+  "schemaVersion": 3,
+  "id": "authoring",
+  "displayName": "Package Authoring",
+  "version": "0.0.1",
+  "compatibility": {
+    "frockbot": ">=0.0.1"
+  },
+  "dependencies": {
+    "shell": ">=0.0.1"
+  },
+  "contributions": {
+    "runtime": {
+      "entry": "./agent"
+    }
+  },
+  "permissions": ["packages:author"]
+}

package/package.json

@@ -1,14 +1,39 @@
 {
   "name": "@frockbot/plugin-authoring",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./manifest": "./src/manifest.ts",
+    "./quota": "./src/quota.ts",
+    "./records": "./src/records.ts",
+    "./shared": "./src/shared.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-authoring"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, test } from "bun:test";
+import { SessionStore, type Session } from "@frockbot/kernel-contracts";
+import { Context } from "cordis";
+import {
+  createPackageAuthorTool,
+  openTurnPositionV1,
+  type AuthorPackageRequestV1,
+  type PackageAuthoringHost,
+} from "./agent.ts";
+import type { AuthorPackageOutcomeV1 } from "./shared.ts";
+
+const INPUT = {
+  packageId: "weather-lookup",
+  displayName: "Weather lookup",
+  tool: { name: "weather_lookup", description: "Looks up", inputSchema: {} },
+  source: "export const tools = [];\nexport async function execute() {}\n",
+};
+
+const CONTEXT = {
+  botId: "bot-1",
+  agentId: "bot-1",
+  sessionId: "user-1:bot-1",
+  compositionGenerationId: "2026-08-31T00:00:00.000Z:0123456789abcdef",
+  turnType: "chat" as const,
+  effectId: "tool:1:1:0",
+  signal: new AbortController().signal,
+};
+
+async function openSession(): Promise<{
+  session: Session;
+  sessions: { get(id: string): Session | undefined };
+  dispose(): Promise<void>;
+}> {
+  const root = new Context();
+  await root.plugin(SessionStore);
+  const session = root.sessions.create("user-1:bot-1");
+  session.appendBatch([
+    { type: "turn/start", turn: 4 },
+    { type: "step/start", turn: 4, step: 2 },
+  ]);
+  return {
+    session,
+    sessions: root.sessions,
+    dispose: () => root.fiber.dispose(),
+  };
+}
+
+function stubHost(
+  outcome: AuthorPackageOutcomeV1,
+  seen: AuthorPackageRequestV1[] = [],
+): PackageAuthoringHost {
+  return {
+    effectIdFor: () => Promise.resolve("author-0123456789abcdef"),
+    author: (request) => {
+      seen.push(request);
+      return Promise.resolve(outcome);
+    },
+  };
+}
+
+describe("the package_author tool", () => {
+  test("records intent before the effect and the outcome after it", async () => {
+    const { session, sessions, dispose } = await openSession();
+    const seen: AuthorPackageRequestV1[] = [];
+    const tool = createPackageAuthorTool(
+      stubHost(
+        {
+          status: "authored",
+          packageId: "weather-lookup",
+          version: "0.0.1",
+          contentHash: "b".repeat(64),
+          generationId: "2026-08-31T01:00:00.000Z:fedcba9876543210",
+        },
+        seen,
+      ),
+      sessions,
+    );
+
+    const result = await tool.execute(INPUT, CONTEXT);
+
+    expect(result.isError).toBe(false);
+    expect(result.content).toContain("version 0.0.1");
+    expect(result.content).toContain(
+      "2026-08-31T01:00:00.000Z:fedcba9876543210",
+    );
+    expect(result.content).toContain("activates on the next Turn");
+    const types = session.events.map((event) => event.type);
+    expect(types.slice(-2)).toEqual([
+      "package/author-intent",
+      "package/authored",
+    ]);
+    // The intent is recorded before the host is reached at all.
+    expect(seen).toHaveLength(1);
+    expect(seen[0]?.position).toEqual({ turn: 4, step: 2 });
+    await dispose();
+  });
+
+  test("a refusal leaves the intent recorded and no authored event", async () => {
+    const { session, sessions, dispose } = await openSession();
+    const tool = createPackageAuthorTool(
+      stubHost({
+        status: "refused",
+        reason: "a durable per-User quota refused this Package",
+        failureId: "authoring-failure-1",
+      }),
+      sessions,
+    );
+
+    const result = await tool.execute(INPUT, CONTEXT);
+
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("authoring-failure-1");
+    expect(session.events.map((event) => event.type)).toContain(
+      "package/author-intent",
+    );
+    expect(session.events.map((event) => event.type)).not.toContain(
+      "package/authored",
+    );
+    await dispose();
+  });
+
+  test("an undecodable input is a tool error, not a durable effect", async () => {
+    const { session, sessions, dispose } = await openSession();
+    const seen: AuthorPackageRequestV1[] = [];
+    const tool = createPackageAuthorTool(
+      stubHost(
+        {
+          status: "authored",
+          packageId: "x",
+          version: "0.0.1",
+          contentHash: "b".repeat(64),
+          generationId: "g",
+        },
+        seen,
+      ),
+      sessions,
+    );
+
+    expect(tool.validate?.({ packageId: "Weather" })).toBe(false);
+    const result = await tool.execute({ packageId: "Weather" }, CONTEXT);
+
+    expect(result.isError).toBe(true);
+    expect(seen).toHaveLength(0);
+    expect(session.events.map((event) => event.type)).not.toContain(
+      "package/author-intent",
+    );
+    await dispose();
+  });
+
+  test("authoring outside an open step is refused", async () => {
+    const root = new Context();
+    await root.plugin(SessionStore);
+    const session = root.sessions.create("user-1:bot-1");
+    session.appendBatch([
+      { type: "turn/start", turn: 1 },
+      { type: "step/start", turn: 1, step: 1 },
+      { type: "step/end", turn: 1, step: 1, outcome: "completed" },
+    ]);
+    expect(() => openTurnPositionV1(session)).toThrow();
+    await root.fiber.dispose();
+  });
+});

package/src/agent.ts

@@ -0,0 +1,190 @@
+// The Package Authoring runtime Contribution: one tool, `package_author`.
+//
+// The Package holds no authority of its own. It decodes the model's input at
+// the seam, appends the two session events that make the effect visible in the
+// durable log, and hands the work to the authoring host the Durable Object
+// gave it. It never reaches a Worker `env`, a bundler, object storage, or the
+// Composition store directly.
+import type {
+  Session,
+  ToolDefinition,
+  ToolExecutionContext,
+} from "@frockbot/kernel-contracts";
+import type { Plugin } from "cordis";
+import {
+  AUTHOR_PACKAGE_INPUT_SCHEMA_V1,
+  type AuthorPackageInputV1,
+  type AuthorPackageOutcomeV1,
+  decodeAuthorPackageInputV1,
+  sha256HexV1,
+} from "./shared.js";
+
+/** The turn and step an authoring event is recorded under. */
+export interface AuthoringTurnPositionV1 {
+  turn: number;
+  step: number;
+}
+
+export interface AuthorPackageRequestV1 {
+  input: AuthorPackageInputV1;
+  sourceHash: string;
+  effectId: string;
+  sessionId: string;
+  position: AuthoringTurnPositionV1;
+}
+
+/**
+ * The kernel-hosted seam this Package receives. Implemented by the Durable
+ * Object host (`@frockbot/plugin-shell/backend-authoring`), which owns the
+ * intent record, the `PACKAGE_BUNDLER` binding, the artifact store, the User
+ * quota RPC, and the Composition store.
+ */
+export interface PackageAuthoringHost {
+  /** The idempotency key for this call; deterministic in the admitted run. */
+  effectIdFor(input: {
+    packageId: string;
+    sourceHash: string;
+  }): Promise<string>;
+  author(request: AuthorPackageRequestV1): Promise<AuthorPackageOutcomeV1>;
+}
+
+/**
+ * The open step an authoring event belongs to. The session log is the
+ * reconstruction surface, so an authoring event without its turn and step
+ * would not replay in place.
+ */
+export function openTurnPositionV1(session: Session): AuthoringTurnPositionV1 {
+  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("package authoring has no open step to record against");
+  }
+  if (
+    ended?.type === "step/end" &&
+    ended.turn === started.turn &&
+    ended.step === started.step
+  ) {
+    throw new Error("package authoring has no open step to record against");
+  }
+  return { turn: started.turn, step: started.step };
+}
+
+function refusalText(
+  outcome: Extract<AuthorPackageOutcomeV1, { status: "refused" }>,
+): string {
+  return [
+    `Authoring was refused: ${outcome.reason}`,
+    `A durable failure record "${outcome.failureId}" was written; the User can inspect it. Nothing was activated.`,
+  ].join(" ");
+}
+
+function authoredText(
+  outcome: Extract<AuthorPackageOutcomeV1, { status: "authored" }>,
+): string {
+  return [
+    `Authored Package "${outcome.packageId}" version ${outcome.version}.`,
+    outcome.supersededVersion
+      ? `It supersedes version ${outcome.supersededVersion}.`
+      : undefined,
+    `Its artifact is ${outcome.contentHash} and it is recorded as Composition generation ${outcome.generationId}.`,
+    "That generation is pending: this Turn keeps running on the Composition it was admitted under, and the new Package activates on the next Turn.",
+  ]
+    .filter((part): part is string => part !== undefined)
+    .join(" ");
+}
+
+export function createPackageAuthorTool(
+  host: PackageAuthoringHost,
+  sessions: { get(sessionId: string): Session | undefined },
+): ToolDefinition {
+  return {
+    name: "package_author",
+    // A general work tool: the full toolset an `executor` subagent gets, and
+    // not part of the narrow reach of `browserUse`, `computerUse`, or the two
+    // video roles. See `@frockbot/plugin-subagents` `SUBAGENT_TOOL_REACH_V1`.
+    admission: { subagentRoles: ["executor"] },
+    description:
+      "Author a Package for yourself: one tool implemented in a single TypeScript file that runs in your own isolate. The Package is recorded as a new Composition generation and activates on your next Turn.",
+    inputSchema: AUTHOR_PACKAGE_INPUT_SCHEMA_V1,
+    idempotent: false,
+    validate: (input: unknown) => {
+      try {
+        decodeAuthorPackageInputV1(input);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    execute: async (input: unknown, context: ToolExecutionContext) => {
+      let decoded: AuthorPackageInputV1;
+      try {
+        decoded = decodeAuthorPackageInputV1(input);
+      } catch (error) {
+        return {
+          content: `package_author input was rejected: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+          isError: true,
+        };
+      }
+      const session = sessions.get(context.sessionId);
+      if (!session) {
+        return {
+          content: `package_author cannot record its intent: session "${context.sessionId}" is unavailable`,
+          isError: true,
+        };
+      }
+      const sourceHash = await sha256HexV1(decoded.source);
+      const effectId = await host.effectIdFor({
+        packageId: decoded.packageId,
+        sourceHash,
+      });
+      const position = openTurnPositionV1(session);
+      // Intent before effect: the session event and the durable intent record
+      // are both written before the bundler is reached.
+      session.append({
+        type: "package/author-intent",
+        ...position,
+        effectId,
+        packageId: decoded.packageId,
+        sourceHash,
+      });
+      await session.flush();
+
+      const outcome = await host.author({
+        input: decoded,
+        sourceHash,
+        effectId,
+        sessionId: context.sessionId,
+        position,
+      });
+      if (outcome.status === "refused") {
+        return { content: refusalText(outcome), isError: true };
+      }
+      session.append({
+        type: "package/authored",
+        ...position,
+        effectId,
+        packageId: outcome.packageId,
+        version: outcome.version,
+        contentHash: outcome.contentHash,
+        generationId: outcome.generationId,
+      });
+      // The model must not be told it succeeded before the record is durable.
+      await session.flush();
+      return { content: authoredText(outcome), isError: false };
+    },
+  };
+}
+
+/** The runtime Contribution. Registers `package_author` and nothing else. */
+export function createAuthoringRuntimePlugin(
+  host: PackageAuthoringHost,
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx) =>
+    ctx.tools.register(createPackageAuthorTool(host, ctx.sessions));
+  plugin.inject = ["tools", "sessions"];
+  return plugin;
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./agent.js";
+export { default as authoringManifest } from "./manifest.js";
+export * from "./quota.js";
+export * from "./records.js";
+export * from "./shared.js";

package/src/manifest.ts

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

package/src/quota.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, test } from "bun:test";
+import {
+  AUTHORING_QUOTA_CONFIG_KEY,
+  AUTHORING_QUOTA_DEFAULTS_V1,
+  authoringQuotaCounterKey,
+  authoringQuotaDayV1,
+  decodeAuthoringQuotaConfigV1,
+  decodeAuthoringQuotaReceiptV1,
+  reserveAuthoringQuotaV1,
+  type AuthoringQuotaStorage,
+} from "./quota.ts";
+
+function storage(initial: Record<string, unknown> = {}) {
+  const values = new Map<string, unknown>(Object.entries(initial));
+  // Durable Object transactions are serialized; this fake is too, so a
+  // read-modify-write that is *not* wrapped in one can interleave here exactly
+  // as it would in the object.
+  let queue: Promise<unknown> = Promise.resolve();
+  const store: AuthoringQuotaStorage & { values: Map<string, unknown> } = {
+    values,
+    get: <T>(key: string) => Promise.resolve(values.get(key) as T | undefined),
+    put: (key: string, value: unknown) => {
+      values.set(key, value);
+      return Promise.resolve();
+    },
+    transaction: <T>(
+      callback: (storage: AuthoringQuotaStorage) => Promise<T>,
+    ) => {
+      const run = queue.then(() => callback(store));
+      queue = run.then(
+        () => undefined,
+        () => undefined,
+      );
+      return run;
+    },
+  };
+  return store;
+}
+
+const REQUEST = {
+  schemaVersion: 1 as const,
+  userId: "user-1",
+  botId: "bot-1",
+  effectId: "author-0123456789abcdef",
+  day: "2026-08-31",
+  sourceBytes: 1_024,
+  retainedGenerations: 3,
+};
+
+describe("the durable per-User authoring quota", () => {
+  test("defaults to 50 retained generations, 100 a day, and 256 KB of source", () => {
+    expect(AUTHORING_QUOTA_DEFAULTS_V1).toEqual({
+      schemaVersion: 1,
+      retainedGenerationsPerBot: 50,
+      authoredPerUserPerDay: 100,
+      maxSourceBytes: 256 * 1024,
+    });
+    expect(decodeAuthoringQuotaConfigV1(undefined)).toEqual(
+      AUTHORING_QUOTA_DEFAULTS_V1,
+    );
+  });
+
+  test("reserves a unit and counts it under quota:generations:<yyyy-mm-dd>", async () => {
+    const store = storage();
+    const receipt = await reserveAuthoringQuotaV1(store, REQUEST);
+
+    expect(receipt).toMatchObject({ status: "reserved", used: 1, limit: 100 });
+    expect(store.values.get(authoringQuotaCounterKey("2026-08-31"))).toEqual({
+      day: "2026-08-31",
+      count: 1,
+    });
+  });
+
+  test("admits exactly one of two concurrent reservations at the limit", async () => {
+    const store = storage({
+      [AUTHORING_QUOTA_CONFIG_KEY]: {
+        ...AUTHORING_QUOTA_DEFAULTS_V1,
+        authoredPerUserPerDay: 100,
+      },
+      [authoringQuotaCounterKey("2026-08-31")]: {
+        day: "2026-08-31",
+        count: 99,
+      },
+    });
+
+    // The counter is a read-modify-write across awaits; without a transaction
+    // both reservations read 99 and both admit.
+    const [first, second] = await Promise.all([
+      reserveAuthoringQuotaV1(store, { ...REQUEST, effectId: "author-race-a" }),
+      reserveAuthoringQuotaV1(store, { ...REQUEST, effectId: "author-race-b" }),
+    ]);
+
+    expect(
+      [first.status, second.status].filter((status) => status === "reserved"),
+    ).toHaveLength(1);
+    expect(
+      [first, second].filter((receipt) => receipt.status === "refused"),
+    ).toMatchObject([{ limitName: "authored-per-day" }]);
+    expect(store.values.get(authoringQuotaCounterKey("2026-08-31"))).toEqual({
+      day: "2026-08-31",
+      count: 100,
+    });
+  });
+
+  test("is idempotent on the authoring effect id", async () => {
+    const store = storage();
+    const first = await reserveAuthoringQuotaV1(store, REQUEST);
+    const second = await reserveAuthoringQuotaV1(store, REQUEST);
+
+    expect(second).toEqual(first);
+    expect(store.values.get(authoringQuotaCounterKey("2026-08-31"))).toEqual({
+      day: "2026-08-31",
+      count: 1,
+    });
+  });
+
+  test("refuses rather than throws when the daily generation quota is spent", async () => {
+    const store = storage({
+      [AUTHORING_QUOTA_CONFIG_KEY]: {
+        ...AUTHORING_QUOTA_DEFAULTS_V1,
+        authoredPerUserPerDay: 2,
+      },
+    });
+    await reserveAuthoringQuotaV1(store, { ...REQUEST, effectId: "author-a" });
+    await reserveAuthoringQuotaV1(store, { ...REQUEST, effectId: "author-b" });
+    const refused = await reserveAuthoringQuotaV1(store, {
+      ...REQUEST,
+      effectId: "author-c",
+    });
+
+    expect(refused).toMatchObject({
+      status: "refused",
+      limitName: "authored-per-day",
+      used: 2,
+      limit: 2,
+    });
+    expect(store.values.get(authoringQuotaCounterKey("2026-08-31"))).toEqual({
+      day: "2026-08-31",
+      count: 2,
+    });
+  });
+
+  test("refuses source beyond the per-Package byte quota", async () => {
+    const refused = await reserveAuthoringQuotaV1(storage(), {
+      ...REQUEST,
+      sourceBytes: 256 * 1024 + 1,
+    });
+    expect(refused).toMatchObject({
+      status: "refused",
+      limitName: "source-bytes",
+    });
+  });
+
+  test("refuses once the Bot holds its retained-generation allowance", async () => {
+    const refused = await reserveAuthoringQuotaV1(storage(), {
+      ...REQUEST,
+      retainedGenerations: 50,
+    });
+    expect(refused).toMatchObject({
+      status: "refused",
+      limitName: "retained-generations",
+      limit: 50,
+    });
+  });
+
+  test("replays a refusal instead of letting a retry through", async () => {
+    const store = storage();
+    const first = await reserveAuthoringQuotaV1(store, {
+      ...REQUEST,
+      sourceBytes: 256 * 1024 + 1,
+    });
+    const second = await reserveAuthoringQuotaV1(store, {
+      ...REQUEST,
+      sourceBytes: 1,
+    });
+    expect(second).toEqual(first);
+  });
+
+  test("decodes its receipt at the Durable Object RPC seam", () => {
+    expect(
+      decodeAuthoringQuotaReceiptV1({
+        schemaVersion: 1,
+        status: "reserved",
+        effectId: "author-a",
+        day: "2026-08-31",
+        used: 1,
+        limit: 100,
+      }).status,
+    ).toBe("reserved");
+    expect(() =>
+      decodeAuthoringQuotaReceiptV1({ schemaVersion: 2, status: "reserved" }),
+    ).toThrow();
+    expect(() =>
+      decodeAuthoringQuotaReceiptV1({
+        schemaVersion: 1,
+        status: "refused",
+        effectId: "author-a",
+        day: "2026-08-31",
+        limitName: "unknown-limit",
+        reason: "no",
+        used: 1,
+        limit: 1,
+      }),
+    ).toThrow();
+  });
+
+  test("names the counter day in UTC", () => {
+    expect(authoringQuotaDayV1(new Date("2026-08-31T23:59:59.999Z"))).toBe(
+      "2026-08-31",
+    );
+    expect(() => authoringQuotaCounterKey("31-08-2026")).toThrow();
+  });
+});