@collegium/sdk 0.0.1-beta.6 → 0.0.1-beta.8

package/README.md

@@ -50,6 +50,18 @@ 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.
 
+**Testing.** `@collegium/sdk/testing` builds the context `execute` receives, over in-memory storage that validates and parses as the deployment's store does. Pass your config; settings go through your schema, so defaults apply.
+
+```ts
+import { createTestContext, PluginToolFailureError } from '@collegium/sdk/testing';
+
+const context = createTestContext(config, { settings: { maxContacts: 1 } });
+await save.execute({ email: 'ana@example.com', id: 'ana', name: 'Ana' }, context);
+await expect(save.execute({ email: 'ben@example.com', id: 'ben', name: 'Ben' }, context)).rejects.toThrow(
+  PluginToolFailureError
+);
+```
+
 **zod is a peer dependency.** Install it beside the SDK and import it directly. A plugin may import `@collegium/sdk`, `zod`, and `node:` builtins; the compiler refuses every other bare specifier at boot.
 
 **Your installed copies are for development.** The deployment compiles a mounted plugin against the SDK and zod its image carries, not the copies in your `node_modules` — those serve your editor, `tsc`, and your tests. Exactly one zod runs in the process.

package/dist/index.d.ts

@@ -1,151 +1,2 @@
-import { z } from "zod";
-import { Promisable } from "type-fest";
-//#region src/config.d.ts
-type CollectionsDeclaration$1 = {
-  readonly [key: string]: z.ZodType;
-};
-/**
- * The config file's default export: the settings schema agents are configured by, and the storage
- * collections the plugin owns. Its generics are what carry the settings and storage types to every
- * tool, through `Register`.
- */
-type PluginConfig<TSettings extends undefined | z.ZodType = undefined | z.ZodType, TCollections extends CollectionsDeclaration$1 = CollectionsDeclaration$1> = {
-  readonly settings: TSettings;
-  readonly storage: TCollections;
-};
-/**
- * The augmentation point. `src/config.ts` declares its config here, and every tool file receives
- * the declared settings and storage types without importing the config:
- *
- * ```ts
- * declare module '@collegium/sdk' {
- *   interface Register { config: typeof config }
- * }
- * ```
- */
-interface Register {}
-type RegisteredConfig = Register extends {
-  readonly config: infer TConfig extends PluginConfig;
-} ? TConfig : PluginConfig;
-declare function defineConfig<TSettings extends undefined | z.ZodType = undefined, const TCollections extends CollectionsDeclaration$1 = {}>(config: {
-  readonly settings?: TSettings;
-  readonly storage?: TCollections;
-}): PluginConfig<TSettings, TCollections>;
-//#endregion
-//#region ../core/src/approvals/approvals.types.d.ts
-/** how a gated tool's approval payload is presented (§6.2): collapsed behind a control, or verbatim */
-type ApprovalPayloadPresentation = 'collapse' | 'verbatim';
-//#endregion
-//#region ../core/src/utils/token.utils.d.ts
-declare const SERVICE_INSTANCE: unique symbol;
-/**
- * A NestJS-compatible injection token branded with the instance type it resolves to. Declared in a
- * leaf `<module>.tokens.ts` beside `import type` of the service alone, which is what keeps a
- * toolset declaration inert (§2): the entrypoint and provisioning import one without pulling the
- * service's runtime module into their graphs.
- */
-type ServiceToken<TInstance> = {
-  readonly [SERVICE_INSTANCE]?: TInstance;
-} & symbol;
-//#endregion
-//#region ../core/src/tools/tools.types.d.ts
-/** the four facts of the running turn (§4) — everything else a tool needs, its toolset declares */
-type ToolTurnScope = {
-  readonly agentUsername: string;
-  readonly channelId: string;
-  /** provenance for anything a tool records; null on a turn no post triggered */
-  readonly triggeringPostId: null | string;
-  readonly turnId: string;
-};
-/** §6.2 — the full payload the approver reads; presence of the `approval` hook is what gates a tool (§5) */
-type ToolApprovalPayload = {
-  body: string;
-  presentation: ApprovalPayloadPresentation;
-};
-/**
- * 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.
- */
-type ToolDisclosure = {
-  readonly body: string;
-  readonly description: string;
-  readonly reference: string;
-  readonly supersededDescriptions?: readonly string[];
-};
-//#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 (§3.4) */
-type PluginToolOutput = string | {
-  readonly disclosure?: ToolDisclosure;
-  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`, 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;
-  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;
-  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/toolsets.types.d.ts
-/** `settings`, `storage`, and `turn` are the context's own keys, so a service may not claim them */
-type ServicesDeclaration = {
-  readonly [key: string]: ServiceToken<unknown>;
-} & {
-  readonly settings?: never;
-  readonly storage?: never;
-  readonly turn?: never;
-};
-type CollectionsDeclaration = {
-  readonly [key: string]: z.ZodType;
-};
-type EmptyDeclaration = {};
-/** a toolset-scoped handle over one declared storage collection; rows are validated on write and parsed on read */
-type ToolsetCollection<TValue> = {
-  delete(key: string): Promise<boolean>;
-  get(key: string): Promise<null | TValue>;
-  list(): Promise<{
-    key: string;
-    value: TValue;
-  }[]>;
-  put(key: string, value: TValue): Promise<void>;
-};
-/**
- * What `execute` receives, assembled from exactly what the toolset declared (§4): each service
- * under its own name, `settings` and `storage` only when declared, and always the turn. Reaching
- * anything undeclared is a compile error.
- */
-type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TSettings extends undefined | z.ZodType = undefined, TCollections extends CollectionsDeclaration = EmptyDeclaration> = { readonly [K in keyof TServices]: TServices[K] extends ServiceToken<infer TInstance> ? TInstance : never; } & {
-  readonly turn: ToolTurnScope;
-} & (keyof TCollections extends never ? unknown : {
-  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<z.infer<TCollections[K]>>; };
-}) & (TSettings extends z.ZodType ? {
-  readonly settings: z.infer<TSettings>;
-} : unknown);
-//#endregion
-//#region src/tool.d.ts
-/** what `execute` receives: the registered config's settings and storage, the failure raisers, and the four facts of the turn */
-type ToolContext = ToolsetContext<EmptyDeclaration, RegisteredConfig['settings'], RegisteredConfig['storage']> & {
-  readonly err: PluginToolErr;
-};
-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
+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-CN2DS668.js";
 export { type PluginTool, type Register, type ToolApprovalPayload, type ToolContext, type ToolDisclosure, type ToolTurnScope, defineConfig, defineTool };

package/dist/testing.d.ts

@@ -0,0 +1,16 @@
+import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-CN2DS668.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 */
+type TestContextOptions<TConfig extends PluginConfig> = {
+  readonly settings?: TConfig['settings'] extends z.ZodType ? z.input<TConfig['settings']> : never;
+  readonly turn?: Partial<ToolTurnScope>;
+};
+/**
+ * The context a deployment hands `execute`, over in-memory storage: each declared collection
+ * validates on write and parses on read as the real store does, settings pass through the declared
+ * schema so defaults apply, and `err` raises exactly what the framework's wrapper catches.
+ */
+declare function createTestContext<TConfig extends PluginConfig>(config: TConfig, options?: TestContextOptions<TConfig>): ToolContextFor<TConfig>;
+//#endregion
+export { PluginToolFailureError, TestContextOptions, createTestContext };

package/dist/testing.js

@@ -0,0 +1,71 @@
+//#region ../core/dist/plugins/plugins.errors.js
+/** what `err.invalidArguments` and `err.unresolved` throw; the perimeter wrapper catches it and nothing else */
+var PluginToolFailureError = class extends Error {
+	failure;
+	constructor(failure) {
+		super(failure.message);
+		this.failure = failure;
+	}
+};
+//#endregion
+//#region ../core/dist/plugins/plugins.utils.js
+/** what a plugin tool receives as `err`; shared with the SDK's testing entry, so a test raises the failure a deployment would */
+const PLUGIN_TOOL_ERR = {
+	invalidArguments(message) {
+		throw new PluginToolFailureError({
+			kind: "invalid-arguments",
+			message
+		});
+	},
+	unresolved(message) {
+		throw new PluginToolFailureError({
+			kind: "unresolved",
+			message
+		});
+	}
+};
+//#endregion
+//#region src/testing.ts
+const DEFAULT_TURN = {
+	agentUsername: "tester",
+	channelId: "test-channel",
+	triggeringPostId: null,
+	turnId: "test-turn"
+};
+function createCollection(schema) {
+	const rows = /* @__PURE__ */ new Map();
+	return {
+		delete: (key) => Promise.try(() => rows.delete(key)),
+		get: (key) => Promise.try(() => rows.has(key) ? schema.parse(rows.get(key)) : null),
+		list: () => Promise.try(() => [...rows].map(([key, value]) => ({
+			key,
+			value: schema.parse(value)
+		}))),
+		put: (key, value) => Promise.try(() => {
+			rows.set(key, schema.parse(value));
+		})
+	};
+}
+/**
+* The context a deployment hands `execute`, over in-memory storage: each declared collection
+* validates on write and parses on read as the real store does, settings pass through the declared
+* schema so defaults apply, and `err` raises exactly what the framework's wrapper catches.
+*/
+function createTestContext(config, options = {}) {
+	const storage = Object.fromEntries(Object.entries(config.storage).map(([name, schema]) => [name, createCollection(schema)]));
+	const context = {
+		err: PLUGIN_TOOL_ERR,
+		storage,
+		turn: {
+			...DEFAULT_TURN,
+			...options.turn
+		}
+	};
+	const settings = config.settings === void 0 ? {} : { settings: config.settings.parse(options.settings ?? {}) };
+	return {
+		...context,
+		...settings
+	};
+}
+//#endregion
+export { PluginToolFailureError, createTestContext };

package/dist/tool-CN2DS668.d.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import { Promisable } from "type-fest";
+//#region src/config.d.ts
+type CollectionsDeclaration$1 = {
+  readonly [key: string]: z.ZodType;
+};
+/**
+ * The config file's default export: the settings schema agents are configured by, and the storage
+ * collections the plugin owns. Its generics are what carry the settings and storage types to every
+ * tool, through `Register`.
+ */
+type PluginConfig<TSettings extends undefined | z.ZodType = undefined | z.ZodType, TCollections extends CollectionsDeclaration$1 = CollectionsDeclaration$1> = {
+  readonly settings: TSettings;
+  readonly storage: TCollections;
+};
+/**
+ * The augmentation point. `src/config.ts` declares its config here, and every tool file receives
+ * the declared settings and storage types without importing the config:
+ *
+ * ```ts
+ * declare module '@collegium/sdk' {
+ *   interface Register { config: typeof config }
+ * }
+ * ```
+ */
+interface Register {}
+type RegisteredConfig = Register extends {
+  readonly config: infer TConfig extends PluginConfig;
+} ? TConfig : PluginConfig;
+declare function defineConfig<TSettings extends undefined | z.ZodType = undefined, const TCollections extends CollectionsDeclaration$1 = {}>(config: {
+  readonly settings?: TSettings;
+  readonly storage?: TCollections;
+}): PluginConfig<TSettings, TCollections>;
+//#endregion
+//#region ../core/src/approvals/approvals.types.d.ts
+/** how a gated tool's approval payload is presented (§6.2): collapsed behind a control, or verbatim */
+type ApprovalPayloadPresentation = 'collapse' | 'verbatim';
+//#endregion
+//#region ../core/src/utils/token.utils.d.ts
+declare const SERVICE_INSTANCE: unique symbol;
+/**
+ * A NestJS-compatible injection token branded with the instance type it resolves to. Declared in a
+ * leaf `<module>.tokens.ts` beside `import type` of the service alone, which is what keeps a
+ * toolset declaration inert (§2): the entrypoint and provisioning import one without pulling the
+ * service's runtime module into their graphs.
+ */
+type ServiceToken<TInstance> = {
+  readonly [SERVICE_INSTANCE]?: TInstance;
+} & symbol;
+//#endregion
+//#region ../core/src/tools/tools.types.d.ts
+/** the four facts of the running turn (§4) — everything else a tool needs, its toolset declares */
+type ToolTurnScope = {
+  readonly agentUsername: string;
+  readonly channelId: string;
+  /** provenance for anything a tool records; null on a turn no post triggered */
+  readonly triggeringPostId: null | string;
+  readonly turnId: string;
+};
+/** §6.2 — the full payload the approver reads; presence of the `approval` hook is what gates a tool (§5) */
+type ToolApprovalPayload = {
+  body: string;
+  presentation: ApprovalPayloadPresentation;
+};
+/**
+ * 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.
+ */
+type ToolDisclosure = {
+  readonly body: string;
+  readonly description: string;
+  readonly reference: string;
+  readonly supersededDescriptions?: readonly string[];
+};
+declare namespace ToolFailure {
+  /** the tool body threw — a semantic failure that terminates the turn (§7.1, §7.2) */
+  type Exception = {
+    kind: 'exception';
+    message: string;
+  };
+  /** the arguments were rejected — returned to the model as the tool result; the turn continues */
+  type InvalidArguments = {
+    kind: 'invalid-arguments';
+    message: string;
+  };
+  /** execution outlived `timeoutMs` — for a mutation the side effect is unconfirmed (§7.1, §7.2) */
+  type Timeout = {
+    kind: 'timeout';
+    timeoutMs: number;
+  };
+  /**
+   * The tool committed something whose outcome cannot be established — a send that may or may not
+   * have left. The turn ends stating the ambiguity (§7.1); it is never returned to the model,
+   * because a model told "unresolved" will try again, which is precisely what must not happen.
+   */
+  type Unresolved = {
+    kind: 'unresolved';
+    message: string;
+  };
+  /** the model named a tool that does not exist or sits outside its configured set (§6.1, §7.2) */
+  type UnknownTool = {
+    kind: 'unknown-tool';
+    message: string;
+  };
+  type Any = Exception | InvalidArguments | Timeout | UnknownTool | Unresolved;
+}
+type ToolFailure = ToolFailure.Any;
+//#endregion
+//#region ../core/src/plugins/plugins.errors.d.ts
+/** what `err.invalidArguments` and `err.unresolved` throw; the perimeter wrapper catches it and nothing else */
+declare class PluginToolFailureError extends Error {
+  readonly failure: ToolFailure.InvalidArguments | ToolFailure.Unresolved;
+  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 (§3.4) */
+type PluginToolOutput = string | {
+  readonly disclosure?: ToolDisclosure;
+  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`, 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;
+  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;
+  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/toolsets.types.d.ts
+/** `settings`, `storage`, and `turn` are the context's own keys, so a service may not claim them */
+type ServicesDeclaration = {
+  readonly [key: string]: ServiceToken<unknown>;
+} & {
+  readonly settings?: never;
+  readonly storage?: never;
+  readonly turn?: never;
+};
+type CollectionsDeclaration = {
+  readonly [key: string]: z.ZodType;
+};
+type EmptyDeclaration = {};
+/** a toolset-scoped handle over one declared storage collection; rows are validated on write and parsed on read */
+type ToolsetCollection<TValue> = {
+  delete(key: string): Promise<boolean>;
+  get(key: string): Promise<null | TValue>;
+  list(): Promise<{
+    key: string;
+    value: TValue;
+  }[]>;
+  put(key: string, value: TValue): Promise<void>;
+};
+/**
+ * What `execute` receives, assembled from exactly what the toolset declared (§4): each service
+ * under its own name, `settings` and `storage` only when declared, and always the turn. Reaching
+ * anything undeclared is a compile error.
+ */
+type ToolsetContext<TServices extends ServicesDeclaration = EmptyDeclaration, TSettings extends undefined | z.ZodType = undefined, TCollections extends CollectionsDeclaration = EmptyDeclaration> = { readonly [K in keyof TServices]: TServices[K] extends ServiceToken<infer TInstance> ? TInstance : never; } & {
+  readonly turn: ToolTurnScope;
+} & (keyof TCollections extends never ? unknown : {
+  readonly storage: { readonly [K in keyof TCollections]: ToolsetCollection<z.infer<TCollections[K]>>; };
+}) & (TSettings extends z.ZodType ? {
+  readonly settings: z.infer<TSettings>;
+} : unknown);
+//#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']> & {
+  readonly err: PluginToolErr;
+};
+/** the context under the registered config: what every tool file's `execute` receives */
+type ToolContext = ToolContextFor<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 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@collegium/sdk",
   "type": "module",
-  "version": "0.0.1-beta.6",
+  "version": "0.0.1-beta.8",
   "description": "Write a Collegium plugin: declare a toolset with its tools, settings, storage, and skills.",
   "license": "AGPL-3.0-only",
   "homepage": "https://collegium.sh",
@@ -21,7 +21,11 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
   },
   "files": [
     "dist"