@frockbot/plugin-skills 0.0.0 → 0.1.1

package/src/testing.ts

@@ -0,0 +1,175 @@
+// An in-memory `WorkspaceFilesV1`, for tests only.
+//
+// The Computer Package implements the real Workspace file surface; this
+// Package deliberately implements none of it. This fake exists so the loader's
+// behaviour can be proven against the contract rather than against a host.
+import {
+  workspaceRootKeyV1,
+  type WorkspaceDeleteRequestV1,
+  type WorkspaceEntryV1,
+  type WorkspaceFilesV1,
+  type WorkspaceGenerationV1,
+  type WorkspaceListOutcomeV1,
+  type WorkspaceListRequestV1,
+  type WorkspacePathV1,
+  type WorkspaceReadOutcomeV1,
+  type WorkspaceRootV1,
+  type WorkspaceStatOutcomeV1,
+  type WorkspaceWriteOutcomeV1,
+  type WorkspaceWriteRequestV1,
+  type WorkspaceWriterV1,
+} from "@frockbot/kernel-contracts";
+
+export interface FakeWorkspaceSeedV1 {
+  root: WorkspaceRootV1;
+  path: string;
+  text: string;
+  writer: WorkspaceWriterV1;
+  generationId?: string;
+}
+
+async function hashOf(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    bytes.slice().buffer as ArrayBuffer,
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+interface StoredFile {
+  entry: WorkspaceEntryV1;
+  bytes: Uint8Array;
+}
+
+/** A Workspace whose files live in a Map. Records every call it served. */
+export class FakeWorkspace implements WorkspaceFilesV1 {
+  readonly calls: string[] = [];
+  #files = new Map<string, StoredFile>();
+  #sequence = 0;
+  /** Set to make `list` answer a failure, to exercise the unreadable path. */
+  listFailure?: { status: "unavailable" | "refused"; reason: string };
+  /** Entries per `list` page, so a caller's paging can be exercised. */
+  listPageSize = 100;
+
+  static async seeded(seeds: FakeWorkspaceSeedV1[]): Promise<FakeWorkspace> {
+    const workspace = new FakeWorkspace();
+    for (const seed of seeds) await workspace.seed(seed);
+    return workspace;
+  }
+
+  async seed(seed: FakeWorkspaceSeedV1): Promise<WorkspaceGenerationV1> {
+    const bytes = new TextEncoder().encode(seed.text);
+    const generation: WorkspaceGenerationV1 = {
+      schemaVersion: 1,
+      generationId: seed.generationId ?? this.#nextGenerationId(),
+      contentHash: await hashOf(bytes),
+      size: bytes.byteLength,
+      writer: seed.writer,
+      writtenAt: new Date(0).toISOString(),
+    };
+    const path: WorkspacePathV1 = { root: seed.root, path: seed.path };
+    this.#files.set(this.#key(path), { entry: { path, generation }, bytes });
+    return generation;
+  }
+
+  read(path: WorkspacePathV1): Promise<WorkspaceReadOutcomeV1> {
+    this.calls.push(`read:${path.path}`);
+    const stored = this.#files.get(this.#key(path));
+    if (!stored) {
+      return Promise.resolve({ status: "not-found", reason: "no such file" });
+    }
+    return Promise.resolve({
+      status: "ok",
+      file: { ...stored.entry, bytes: stored.bytes },
+    });
+  }
+
+  stat(path: WorkspacePathV1): Promise<WorkspaceStatOutcomeV1> {
+    this.calls.push(`stat:${path.path}`);
+    const stored = this.#files.get(this.#key(path));
+    if (!stored) {
+      return Promise.resolve({ status: "not-found", reason: "no such file" });
+    }
+    return Promise.resolve({ status: "ok", entry: stored.entry });
+  }
+
+  list(request: WorkspaceListRequestV1): Promise<WorkspaceListOutcomeV1> {
+    this.calls.push(`list:${workspaceRootKeyV1(request.root)}`);
+    if (this.listFailure) return Promise.resolve({ ...this.listFailure });
+    const key = workspaceRootKeyV1(request.root);
+    const all = [...this.#files.values()]
+      .filter((stored) => workspaceRootKeyV1(stored.entry.path.root) === key)
+      .map((stored) => stored.entry)
+      .sort((left, right) => left.path.path.localeCompare(right.path.path));
+    const start = request.cursor ? Number(request.cursor) : 0;
+    const size = request.limit ?? this.listPageSize;
+    const entries = all.slice(start, start + size);
+    const next = start + entries.length;
+    return Promise.resolve({
+      status: "ok",
+      entries,
+      ...(next < all.length ? { cursor: String(next) } : {}),
+    });
+  }
+
+  async write(
+    request: WorkspaceWriteRequestV1,
+  ): Promise<WorkspaceWriteOutcomeV1> {
+    this.calls.push(`write:${request.path.path}`);
+    const key = this.#key(request.path);
+    const existing = this.#files.get(key);
+    const seen = existing?.entry.generation.generationId ?? null;
+    if (seen !== request.expectedGenerationId) {
+      return {
+        status: "conflict",
+        reason: `expected generation ${request.expectedGenerationId ?? "none"}`,
+      };
+    }
+    const generation: WorkspaceGenerationV1 = {
+      schemaVersion: 1,
+      generationId: this.#nextGenerationId(),
+      contentHash: await hashOf(request.bytes),
+      size: request.bytes.byteLength,
+      writer: request.writer,
+      writtenAt: new Date(0).toISOString(),
+    };
+    this.#files.set(key, {
+      entry: { path: request.path, generation },
+      bytes: request.bytes,
+    });
+    return { status: "ok", generation };
+  }
+
+  delete(request: WorkspaceDeleteRequestV1): Promise<WorkspaceWriteOutcomeV1> {
+    this.calls.push(`delete:${request.path.path}`);
+    const key = this.#key(request.path);
+    const existing = this.#files.get(key);
+    if (!existing) {
+      return Promise.resolve({ status: "not-found", reason: "no such file" });
+    }
+    this.#files.delete(key);
+    return Promise.resolve({
+      status: "ok",
+      generation: existing.entry.generation,
+    });
+  }
+
+  #key(path: WorkspacePathV1): string {
+    return `${workspaceRootKeyV1(path.root)}|${path.path}`;
+  }
+
+  #nextGenerationId(): string {
+    this.#sequence += 1;
+    return `1970-01-01T00:00:00.000Z:${String(this.#sequence).padStart(16, "0")}`;
+  }
+}
+
+export function skillMarkdown(
+  name: string,
+  description: string,
+  body: string,
+): string {
+  return `---\nname: ${name}\ndescription: ${description}\n---\n\n${body}\n`;
+}

package/src/write.ts

@@ -0,0 +1,181 @@
+// Writing one Skill document into one of a Bot's instruction roots.
+//
+// Two callers reach this, and they differ in exactly one thing: who the write
+// is attributed to. `skill_write` writes as the Bot, inside an admitted Turn
+// whose Session and Turn the provenance names. Importing a Bot template writes
+// as the importing *User*, because a template is prose their User chose to
+// materialize and no Turn of the new Bot has run yet.
+//
+// "The kernel treats every Workspace file as data. Only Skills under a Bot's
+// instruction roots — its own and its User's — written under the Bot's own
+// authority or its User's, are loaded as instructions." Both writers this
+// module admits are on the right side of that sentence, and
+// `isLoadableSkillSourceV1` is still the one place it is decided — this module
+// cannot widen it, because both roots it can write are derived from the owner
+// rather than passed in, so there is no argument with which to name another
+// User's root or another Bot's.
+import type {
+  WorkspaceFilesV1,
+  WorkspaceWriteRequestV1,
+} from "@frockbot/kernel-contracts";
+import {
+  botInstructionRootV1,
+  countSkillDocumentsV1,
+  userInstructionRootV1,
+  type SkillOwnerV1,
+} from "./catalog.js";
+import { renderSkillDocumentV1, skillDocumentPathV1 } from "./skill-md.js";
+import {
+  checkSkillQuotaV1,
+  skillCountLimitV1,
+  SKILL_QUOTA_DEFAULTS_V1,
+  type SkillQuotaConfigV1,
+  type SkillQuotaScopeV1,
+} from "./quota.js";
+
+/** Who a Skill write is attributed to. Only these two are loadable. */
+export type SkillDocumentWriterV1 =
+  | { kind: "user"; userId: string }
+  | {
+      kind: "bot";
+      botId: string;
+      sessionId: string;
+      turnId: string;
+      runId: string;
+    };
+
+export interface SkillDocumentDraftV1 {
+  slug: string;
+  name: string;
+  description: string;
+  body: string;
+}
+
+export type SkillWriteOutcomeV1 =
+  | {
+      status: "written";
+      path: string;
+      generationId: string;
+      contentHash: string;
+      /** True when the write superseded an existing generation at that path. */
+      replaced: boolean;
+    }
+  | { status: "refused"; reason: string };
+
+export async function sha256HexV1(text: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    "SHA-256",
+    new TextEncoder().encode(text),
+  );
+  return [...new Uint8Array(digest)]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Renders and writes one Skill, enforcing that root's quota on the way.
+ *
+ * A refusal is a value, never a throw: a quota breach, an unreadable root, or a
+ * losing optimistic write are all outcomes a caller must record and report, and
+ * the two callers report them very differently — one as a tool result the model
+ * reads, one as a repairable step on a durable import record.
+ */
+export async function writeSkillDocumentV1(
+  files: WorkspaceFilesV1,
+  owner: SkillOwnerV1,
+  writer: SkillDocumentWriterV1,
+  draft: SkillDocumentDraftV1,
+  options: {
+    /**
+     * Which instruction root the Skill lands in: the Bot's own by default, or
+     * the User-global root every Bot of that User shares (ADR 0016). The
+     * writer is unchanged either way — a Bot writing the shared root still
+     * records itself, which is what lets a reading Bot be told whose Skill it
+     * is following.
+     */
+    scope?: SkillQuotaScopeV1;
+    quota?: SkillQuotaConfigV1;
+    /**
+     * Recorded intent, after the quota admits the write and strictly before it
+     * runs. "Record durable execution intent before invoking an external side
+     * effect" — the Bot's tool appends `skill/write-intent` here, and the
+     * import saga marks its step in flight, so neither can be interrupted
+     * between deciding to write and having a record that it tried.
+     */
+    onIntent?(intent: { path: string; contentHash: string }): Promise<void>;
+  } = {},
+): Promise<SkillWriteOutcomeV1> {
+  const quota = options.quota ?? SKILL_QUOTA_DEFAULTS_V1;
+  const scope = options.scope ?? "bot";
+  const root =
+    scope === "user"
+      ? userInstructionRootV1(owner)
+      : botInstructionRootV1(owner);
+  const relativePath = skillDocumentPathV1(draft.slug);
+  const path = { root, path: relativePath };
+  const text = renderSkillDocumentV1({
+    name: draft.name,
+    description: draft.description,
+    body: draft.body,
+  });
+  const bytes = new TextEncoder().encode(text);
+
+  const existing = await files.stat(path);
+  if (existing.status !== "ok" && existing.status !== "not-found") {
+    return {
+      status: "refused",
+      reason: `the instruction root is unavailable: ${existing.reason}`,
+    };
+  }
+  // The count is paged to completion, and a listing that cannot be read is a
+  // refusal rather than a zero: a quota that falls open is not a quota.
+  const counted = await countSkillDocumentsV1(files, path.root, {
+    stopAfter: skillCountLimitV1(scope, quota),
+  });
+  if (counted.status !== "ok") {
+    return {
+      status: "refused",
+      reason: `${counted.reason}, so the per-${
+        scope === "user" ? "User" : "Bot"
+      } Skill quota cannot be enforced`,
+    };
+  }
+  const verdict = checkSkillQuotaV1(
+    {
+      bytes: bytes.byteLength,
+      existingSkills: counted.count,
+      replaces: existing.status === "ok",
+      scope,
+    },
+    quota,
+  );
+  if (verdict.status === "refused") {
+    return { status: "refused", reason: verdict.reason };
+  }
+
+  const contentHash = await sha256HexV1(text);
+  await options.onIntent?.({ path: relativePath, contentHash });
+
+  const request: WorkspaceWriteRequestV1 = {
+    path,
+    bytes,
+    writer,
+    expectedGenerationId:
+      existing.status === "ok" ? existing.entry.generation.generationId : null,
+    mediaType: "text/markdown",
+  };
+  const outcome = await files.write(request);
+  if (outcome.status !== "ok") {
+    return {
+      status: "refused",
+      reason: `the write was ${outcome.status}: ${outcome.reason}`,
+    };
+  }
+  return {
+    status: "written",
+    path: relativePath,
+    generationId: outcome.generation.generationId,
+    contentHash,
+    replaced: existing.status === "ok",
+  };
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/README.md

@@ -1,3 +0,0 @@
-# @frockbot/plugin-skills
-
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.