@collegium/sdk 0.0.1-beta.22 → 0.0.1-beta.24

package/README.md

@@ -2,7 +2,7 @@
 
 The authoring surface for [Collegium](https://collegium.sh) plugins.
 
-A plugin is a directory of TypeScript. The deployment mounts it, compiles it at boot, and grants it to the agents that need it. The layout declares the contents: `src/config.ts` declares settings and storage, each `src/tools/<name>.ts` declares one tool named by its filename, and each `src/skills/<name>.md` ships one skill.
+A plugin is a directory of TypeScript. The deployment mounts it, compiles it at boot, and grants it to the agents that need it. The layout declares the contents: `src/config.ts` declares settings and storage, each `src/tools/<name>.ts` declares one tool named by its filename, and each `src/skills/<name>/` ships one skill as `SKILL.md` plus any `references/<name>.md` beside it.
 
 ```sh
 npm install @collegium/sdk zod
@@ -48,7 +48,7 @@ export default defineTool({
 });
 ```
 
-A tool with `approval` always stops for a human, who sees the full payload before it runs; one without never gates. The channel and the trace disclose both, line by line. `execute` returns the text the model reads, and raises the two failures a tool controls through `err`: `invalidArguments` continues the turn, `unresolved` ends it as an unconfirmed side effect.
+Every tool states its gate: `approval` is required, and a tool whose `approval` is a function always stops for a human, who sees the full payload before it runs, while one declaring `approval: null` never gates. Omitting the key refuses the plugin at boot. `approval` may be `async`, and receives `settings` and each collection's reads (`findById`, `findFirst`, `findMany`) beside `args`. A tool that acts on a stored record can then show the approver the record itself. The channel and the trace disclose both, line by line. `execute` returns the text the model reads, and raises the two failures a tool controls through `err`: `invalidArguments` continues the turn, `unresolved` ends it as an unconfirmed side effect.
 
 **Storage.** Each declared collection is a set of records: the schema's output plus `id`, `createdAt`, and `updatedAt`, which the store stamps. The handle has `create`, `findMany`, `findFirst`, `findById`, `updateById`, and `deleteById`. `create` takes the schema's input with an optional `id`, minting a cuid2 when none is given. `findMany` with no argument lists everything; with a `where` over the schema's top-level scalar fields and `id` — a value for equality, `{ in: [...] }` for membership, `{ contains: text }` for a case-insensitive substring on a string — and an optional `limit`, it filters. `findFirst` takes the same `where` and returns the earliest match or `null`. Field names and value types come from the schema, so a bad query does not compile.
 

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { c as ToolTurnScope, d as defineConfig, i as defineTool, n as ToolContext, o as ToolApprovalPayload, s as ToolDisclosure, t as PluginTool, u as Register } from "./tool-CcZsVMw2.js";
-export { type PluginTool, type Register, type ToolApprovalPayload, type ToolContext, type ToolDisclosure, type ToolTurnScope, defineConfig, defineTool };
+import { a as defineTool, c as ToolDisclosure, d as Register, f as defineConfig, l as ToolTurnScope, n as PluginTool, r as ToolContext, s as ToolApprovalPayload, t as ApprovalContext } from "./tool-0g77wWJM.js";
+export { type ApprovalContext, type PluginTool, type Register, type ToolApprovalPayload, type ToolContext, type ToolDisclosure, type ToolTurnScope, defineConfig, defineTool };

package/dist/testing.d.ts

@@ -1,4 +1,4 @@
-import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-CcZsVMw2.js";
+import { i as ToolContextFor, l as ToolTurnScope, o as PluginToolFailureError, u as PluginConfig } from "./tool-0g77wWJM.js";
 import { z } from "zod";
 //#region src/testing.d.ts
 /** `settings` as the declared schema accepts them, so defaults apply as they do at boot; `turn` overrides the four facts */

package/dist/{tool-CcZsVMw2.d.ts → tool-0g77wWJM.d.ts}

@@ -64,12 +64,14 @@ type ToolApprovalPayload = {
 };
 /**
  * A durable record's disclosure (§3.6), returned by the tool that created it; the turn writes the
- * event and the trace lines. `reference` names the record for later reads, e.g. a memory id.
+ * event the trace reads back. `reference` names the record for later reads, e.g. a memory id.
  */
 type ToolDisclosure = {
   readonly body: string;
   readonly description: string;
   readonly reference: string;
+  /** the reference of the record this one replaced in the same step, which no longer resolves (§3.6) */
+  readonly revisionOf?: string;
   readonly supersededDescriptions?: readonly string[];
 };
 declare namespace ToolFailure {
@@ -105,6 +107,18 @@ declare namespace ToolFailure {
   type Any = Exception | InvalidArguments | Timeout | UnknownTool | Unresolved;
 }
 type ToolFailure = ToolFailure.Any;
+/** the methods of a storage collection that leave the store as they found it: all of storage an approval render reaches (§3.4) */
+type ToolStorageReadMethod = 'findById' | 'findFirst' | 'findMany';
+/**
+ * What an approval render receives, derived from what `execute` receives (§3.4): the settings where
+ * the context carries them, and of each storage handle only its read half — no service, no write,
+ * and no turn.
+ */
+type ToolApprovalContext<TContext> = Pick<TContext, Extract<keyof TContext, 'settings'>> & (TContext extends {
+  readonly storage: infer TStorage;
+} ? {
+  readonly storage: { readonly [K in keyof TStorage]: Pick<TStorage[K], Extract<keyof TStorage[K], ToolStorageReadMethod>>; };
+} : unknown);
 //#endregion
 //#region ../core/src/plugins/plugins.errors.d.ts
 /** what `err.invalidArguments` and `err.unresolved` throw; the perimeter wrapper catches it and nothing else */
@@ -113,41 +127,6 @@ declare class PluginToolFailureError extends Error {
   constructor(failure: ToolFailure.InvalidArguments | ToolFailure.Unresolved);
 }
 //#endregion
-//#region ../core/src/plugins/plugins.types.d.ts
-/** what a plugin tool body may return: the text alone, or the text beside a durable record's disclosure and the line later turns replay (§3.4) */
-type PluginToolOutput = string | {
-  readonly disclosure?: ToolDisclosure;
-  readonly replay?: string;
-  readonly text: string;
-};
-/**
- * The two failures a tool body may raise itself — the rest of the taxonomy (§7.1) is the
- * framework's to raise. Each throws; the perimeter wrapper maps the throw into the taxonomy.
- */
-type PluginToolErr = {
-  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
-  invalidArguments(message: string): never;
-  /** a committed side effect whose outcome cannot be established; the turn ends stating the ambiguity */
-  unresolved(message: string): never;
-};
-/** one tool as a plugin declares it: the framework's tool minus `budgetExempt` and `isAvailableWith`, returning plain output */
-type PluginToolDeclaration<TContext, TParams extends z.ZodType> = {
-  /** present ⇒ the tool always gates (§5); renders the payload the approver reads and cannot decline */
-  approval?(args: z.infer<TParams>): ToolApprovalPayload;
-  /** may run alongside the other concurrent calls of one completion: a read that touches nothing another call in the batch does */
-  readonly concurrent?: boolean;
-  readonly description: string;
-  execute(args: z.infer<TParams>, context: TContext): Promisable<PluginToolOutput>;
-  readonly parameters: TParams;
-  /** §7.2 — whether a timed-out call may be reported to the model as a plain failure; false ends the turn as unconfirmable */
-  readonly retryable?: boolean;
-  /** a later result of any supersedable tool in the same turn replaces this one's text with its replay line, past the retained few (§3.8) */
-  readonly supersedable?: boolean;
-  readonly timeoutMs?: number;
-  /** §8.1 — the one-line summary beside the name in the status post; absent shows the name alone */
-  traceDetail?(args: z.infer<TParams>): string;
-};
-//#endregion
 //#region ../core/src/toolsets/storage/collection-query.types.d.ts
 /** the JSON scalars a query may compare; an object, array, or date field is not queryable */
 type Scalar = boolean | null | number | string;
@@ -226,6 +205,47 @@ type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TS
   readonly settings: z.infer<TSettings>;
 } : unknown);
 //#endregion
+//#region ../core/src/plugins/plugins.types.d.ts
+/** what a plugin tool body may return: the text alone, or the text beside a durable record's disclosure and the line later turns replay (§3.4) */
+type PluginToolOutput = string | {
+  readonly disclosure?: ToolDisclosure;
+  readonly replay?: string;
+  readonly text: string;
+};
+/**
+ * The two failures a tool body may raise itself — the rest of the taxonomy (§7.1) is the
+ * framework's to raise. Each throws; the perimeter wrapper maps the throw into the taxonomy.
+ */
+type PluginToolErr = {
+  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
+  invalidArguments(message: string): never;
+  /** a committed side effect whose outcome cannot be established; the turn ends stating the ambiguity */
+  unresolved(message: string): never;
+};
+/** one tool as a plugin declares it: the framework's tool minus `budgetExempt` and `isAvailableWith`, returning plain output */
+type PluginToolDeclaration<TContext, TParams extends z.ZodType> = {
+  /**
+   * The payload the approver reads, or `null` for a tool that does not gate. Required, unlike the
+   * framework's own optional field: a framework toolset is read as source by whoever maintains it,
+   * while a plugin's source may not be in this repository at all, so an omitted field cannot be
+   * told from a forgotten one (§3.14). A function ⇒ the tool always gates (§3.7) and cannot decline;
+   * it may read the settings and the stored records the call acts on (§3.4).
+   */
+  approval: ((args: z.infer<TParams>, context: ToolApprovalContext<TContext>) => Promisable<ToolApprovalPayload>) | null;
+  /** may run alongside the other concurrent calls of one completion: a read that touches nothing another call in the batch does */
+  readonly concurrent?: boolean;
+  readonly description: string;
+  execute(args: z.infer<TParams>, context: TContext): Promisable<PluginToolOutput>;
+  readonly parameters: TParams;
+  /** §7.2 — whether a timed-out call may be reported to the model as a plain failure; false ends the turn as unconfirmable */
+  readonly retryable?: boolean;
+  /** a later result of any supersedable tool in the same turn replaces this one's text with its replay line, past the retained few (§3.8) */
+  readonly supersedable?: boolean;
+  readonly timeoutMs?: number;
+  /** §8.1 — the one-line summary beside the name in the status post; absent shows the name alone */
+  traceDetail?(args: z.infer<TParams>): string;
+};
+//#endregion
 //#region src/tool.d.ts
 /** what `execute` receives under a config: its settings and storage, the failure raisers, and the four facts of the turn */
 type ToolContextFor<TConfig extends PluginConfig> = ToolsetContext<EmptyDeclaration, TConfig['settings'], TConfig['storage']> & {
@@ -233,8 +253,12 @@ type ToolContextFor<TConfig extends PluginConfig> = ToolsetContext<EmptyDeclarat
 };
 /** the context under the registered config: what every tool file's `execute` receives */
 type ToolContext = ToolContextFor<RegisteredConfig>;
+/** what `approval` receives under a config: the settings, and of each collection only the methods that read (§3.4) */
+type ApprovalContextFor<TConfig extends PluginConfig> = ToolApprovalContext<ToolContextFor<TConfig>>;
+/** the approval context under the registered config: what every tool file's `approval` receives */
+type ApprovalContext = ApprovalContextFor<RegisteredConfig>;
 type PluginTool<TParams extends z.ZodType> = PluginToolDeclaration<ToolContext, TParams>;
 /** identity at runtime; what it is for is typing `args` from `parameters` across the whole declaration */
 declare function defineTool<TParams extends z.ZodType>(tool: PluginTool<TParams>): PluginTool<TParams>;
 //#endregion
-export { PluginToolFailureError as a, ToolTurnScope as c, defineConfig as d, defineTool as i, PluginConfig as l, ToolContext as n, ToolApprovalPayload as o, ToolContextFor as r, ToolDisclosure as s, PluginTool as t, Register as u };
+export { defineTool as a, ToolDisclosure as c, Register as d, defineConfig as f, ToolContextFor as i, ToolTurnScope as l, PluginTool as n, PluginToolFailureError as o, ToolContext as r, ToolApprovalPayload as s, ApprovalContext as t, PluginConfig as u };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@collegium/sdk",
   "type": "module",
-  "version": "0.0.1-beta.22",
+  "version": "0.0.1-beta.24",
   "description": "Write a Collegium plugin: declare a toolset with its tools, settings, storage, and skills.",
   "license": "AGPL-3.0-only",
   "homepage": "https://collegium.sh",