@collegium/sdk 0.0.1-beta.11 → 0.0.1-beta.13

package/README.md

@@ -50,7 +50,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.
 
-**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`, `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. Field names and value types come from the schema, so a bad query does not compile.
+**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.
 
 **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.
 

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-Vqe6D48m.js";
+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-CZZZNBSg.js";
 export { 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-Vqe6D48m.js";
+import { a as PluginToolFailureError, c as ToolTurnScope, l as PluginConfig, r as ToolContextFor } from "./tool-CZZZNBSg.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/testing.js

@@ -137,6 +137,12 @@ function createCollection(schema) {
 		},
 		deleteById: (id) => Promise.try(() => rows.delete(id)),
 		findById: (id) => Promise.try(() => rows.has(id) ? toRecord(rows.get(id)) : null),
+		findFirst: (query = {}) => {
+			return Promise.try(() => applyCollectionQuery([...rows.values()].map(toRecord), {
+				...query,
+				limit: 1
+			})[0] ?? null);
+		},
 		findMany: (query = {}) => Promise.try(() => applyCollectionQuery([...rows.values()].map(toRecord), query)),
 		updateById: (id, patch) => {
 			return Promise.try(() => {

package/dist/{tool-Vqe6D48m.d.ts → tool-CZZZNBSg.d.ts}

@@ -129,7 +129,7 @@ type PluginToolErr = {
   /** 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 */
+/** 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;
@@ -160,10 +160,12 @@ type CollectionFieldCondition<TField> = ([Extract<TField, string>] extends [neve
 };
 /** an AND over field conditions, keyed by the record's own scalar fields */
 type CollectionWhere<TRecord> = { readonly [K in keyof QueryableFields<TRecord>]?: CollectionFieldCondition<QueryableFields<TRecord>[K]>; };
-type CollectionQuery<TRecord> = {
-  readonly limit?: number;
+type CollectionFilter<TRecord> = {
   readonly where?: CollectionWhere<TRecord>;
 };
+type CollectionQuery<TRecord> = CollectionFilter<TRecord> & {
+  readonly limit?: number;
+};
 //#endregion
 //#region ../core/src/toolsets/storage/collection.types.d.ts
 /** what the store stamps on every record beside the declared fields; a schema may not declare any of these */
@@ -185,6 +187,8 @@ type ToolsetCollection<TSchema extends z.ZodObject> = {
   }): Promise<CollectionRecord<z.output<TSchema>>>;
   deleteById(id: string): Promise<boolean>;
   findById(id: string): Promise<CollectionRecord<z.output<TSchema>> | null>;
+  /** the earliest-inserted record the query matches, or null; without a query, the earliest record */
+  findFirst(query?: CollectionFilter<CollectionRecord<z.output<TSchema>>>): Promise<CollectionRecord<z.output<TSchema>> | null>;
   /** without a query, every record in insertion order */
   findMany(query?: CollectionQuery<CollectionRecord<z.output<TSchema>>>): Promise<CollectionRecord<z.output<TSchema>>[]>;
   /** the patch merged over the stored fields and the whole parsed again, so a patch cannot leave an invalid record */

package/package.json

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