@swirls/looms 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @swirls/looms
 
+## 0.5.1
+
+### Patch Changes
+
+- 86280a0: Export `@swirls/looms/cloudflare/queues` so Bun/Node pull consumers can load queue helpers without importing `cloudflare:workers`.
+
+## 0.5.0
+
+### Minor Changes
+
+- edd3c5c: Agents gain structured output through a `submit_output` tool, one compaction-and-retry when the model reports a context overflow, `resolveTools` for tools that depend on the agent input, an `assertCredits` gate before each model call, and `trackUsage` beside a new `agent.turn.usage` event. Team members spawned with `asAgentTool` stop at `TEAM_MEMBER_MAX_DEPTH` (3); the parent sends the child its depth with a new `agent.lineage` event.
+- 0ac83ab: `createLooms({ blobStore })` and `LoomsDurableObject` `blobs` store strings over 64 KiB by SHA-256 and keep a reference in the event or snapshot. A payload that is still over the 1 MiB event limit is stored as one blob. Reads, subscribers, folds, projections, and snapshot loads resolve the reference, so a run can complete with a payload larger than that limit. Trim removes a blob body once nothing retained still points at it. `memoryBlobStore`, `filesystemBlobStore`, and `r2BlobStore` are the included stores. Without a blob store, events over 1 MiB and snapshots over 8 MiB are still rejected.
+- 0ac83ab: feat(runtime)!: launch workflow children as their own runs
+
+  A workflow can set `childExecution: 'run'` so spawn, map, fanout, and loop start a child run instead of a thread. The child run id is stable across retries. When the child finishes it signals `runtime.child.settled`, which completes the parent's wait. `childClose` is `terminate` or `wait`. The default remains in-process threads.
+
+  BREAKING CHANGE: `RunLauncher` implementations must provide `signal` and `cancel`.
+
+- 0ac83ab: Definitions can be loaded at start, spawn, and recovery through `definitionResolver`, with registered definitions checked first and an LRU cache in front. A missing definition fails the start before any event is written, and the accepted version stays pinned on the run. Evaluator definitions now include `version`, defaulting to `v1`, and lookup takes the name and version.
+
+  BREAKING CHANGE: `EvaluatorDefinition` requires `version`, and evaluator lookup is `(name, version)` instead of `(name)`. `defineEvaluator` still defaults the version to `v1`.
+
+- 2436516: Worker callbacks now answer `{ status: 'accepted' | 'stale' | 'cancelled', cancelRequested }` instead of the run state. `createLooms().workerCallback` and `createLoomsClient().workerCallback` return that result. `cancelRequested` tells an attempt that is already running to stop, because a dispatch that has left the host cannot be recalled. A stale report records nothing.
+
+  `failEffect({ error, nonRetryable, retryAfterMs })` fails the current attempt. `nonRetryable` ends the effect even when the retry policy has attempts left. `retryAfterMs` waits at least that long before the next attempt and never shortens the policy backoff. Worker `fail` callbacks take the same two fields.
+
+  A heartbeat may include `details`. The latest details are kept across retries and included on the next `EffectWorkerTask`, so a resumed attempt can continue from the recorded progress.
+
+- 0ac83ab: Durable Objects accept a hibernating WebSocket on `GET /runs/:id/events`. The socket replays the retained log, then receives later events without a subscription held in memory. SSE sends the same `hello` and `resync` frames. A cursor below the retained head is told to resume from `head` instead of silently skipping trimmed events. `subscribeEvents` and the React store take `transport: "websocket" | "sse" | "auto"`; the default remains SSE, and a numeric reconnect delay still works.
+- c01d046: A run started from an effect through `RunLauncher` now records its source on `runtime.run.started`. The payload's `launchedBy` holds the launching run, thread, and effect, plus the id and seq of the event that requested the effect. The event's origin is `{ type: 'run', runId }`, and its `correlationId` names the root run of the launch chain. The runtime sets these fields itself and replaces any value a handler passes. `RunState.startIdentity` exposes both fields, and a later start of the same run id that does not match them rejects with `StartRunConflictError`.
+
+  The launching run's log gets a new `runtime.run.launched` event for each start the target accepts. It carries the started run's id and definition plus the effect id, so listing what a run launched reads that run's log alone.
+
+  The index projectors store `launchedByRunId`, `launchedByEffectId`, and `correlationId` on run rows, and `listLaunched(runId)` returns the runs a run launched. Their version is now 3, so delivery replays history to fill the new columns, and `init` adds the columns to existing SQLite and Postgres tables.
+
+  `useRunSummary` returns `launchedBy`. The debugger shows a Launched by link above the thread tree that opens the launching run at the requesting event, the event inspector links `runtime.run.launched` and `runtime.run.started` to the run on the other side, and `openRun` accepts a `{ seq }` target.
+
+- 0ac83ab: Runs carry the caller's W3C trace context. `POST /runs` reads the `traceparent` and `tracestate` headers, and `start`, `startRun`, and `client.startRun` accept `trace`. A valid context is recorded on `runtime.run.started` and `startIdentity.trace`, then passed unchanged to effect handlers (`ctx.trace`), worker tasks (`task.trace`), and every launched or child run unless the launch sets its own.
+- a1fa2c3: feat(projectors): project runs into a Postgres event log without blocking append
+
+  Durable Object projectors are scheduled with `waitUntil` after the log commits. `postgresEventLog` stores each non-ephemeral envelope and a run index with status, launch links, and tenant attributes, and can rebuild that sink from the log.
+
+- 0ac83ab: feat(cloudflare): run worker effects over Cloudflare Queues
+
+  `cloudflareQueueWorker` sends each attempt to a queue as JSON, with the run's trace context and the attempt's deadlines; inputs over 100 KB travel as a blob reference and secrets stay off the queue. `queueConsumer` (push) and `createQueuePullConsumer` with `cloudflareQueuePullSource` (HTTP pull) run handlers that heartbeat, read secrets through the worker callback API, and stop when the run is cancelled. The consumer acks after `started`, so Looms owns retries; duplicate and stale deliveries are dropped, and dead-lettered messages are recovered by the schedule-to-start timeout. The pull consumer batches acks, backs off when idle, reports the backlog, and drains on `stop()`. `createMemoryQueue` gives tests the same lease and dead-letter behavior.
+
+  In the runtime, `EffectWorker.dispatchSemantics: 'acknowledged'` fails a rejected dispatch under the retry policy instead of parking it as ambiguous, and creating a runtime fails if such a worker claims an effect without `retry.scheduleToStartTimeoutMs`. Worker tasks carry `deadlines`, and `maxInFlightWorkerEffects` caps the worker attempts one run has in flight.
+
+- 0ac83ab: Runs accept immutable `attributes` and a `secrets` context. Attributes are recorded on `runtime.run.started`, the run state, and the run summary, and are passed to `authorize` when present. Secrets stay in a side store: they are available to effect handlers and in-process worker dispatch, and they are not written to events, snapshots, or run responses. A worker whose transport persists tasks reads them with `POST /runs/:runId/effects/:effectId/:attempt/secrets` (`client.workerSecrets`), which only answers the attempt that is currently running.
+- 0ac83ab: feat(runtime): authorize browser event streams with a signed run grant
+
+  `grantAuth` checks a short-lived HMAC grant from the `grant` query parameter or a `v1.` WebSocket subprotocol. The grant allows one principal to read one run, which is the credential a browser can send on EventSource or WebSocket. The Durable Object socket echoes a subprotocol grant on the upgrade, and `grantSubprotocol` gives other hosts the value to echo.
+
+- c01d046: Add a schedule module so a cron, interval, or one-shot time can start a run, and so a deploy can update, pause, or retire that schedule without a new run id.
+- 0ac83ab: feat(testing): replay recorded run logs in CI and document effect contracts
+
+  Adds a production-shaped event-log corpus under `packages/testing/corpus`, folded
+  deterministically in CI with `assertCorpusEntry`. Documents versioning effect
+  types (`payments.charge@v2`) and worker `handles` so fleets can roll out beside
+  each other without Temporal-style patches.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/actor/cell.d.ts

@@ -1,10 +1,12 @@
-import { type AnyRuntimeModule, type EventStore, type EventStoreTrimCoverage, type RunState, type SnapshotStore } from '@swirls/looms/core';
-import { type Authorize, type LoomsRuntime, type WakeScheduler } from '@swirls/looms/runtime';
+import { type AnyRuntimeModule, type DefinitionResolver, type EventInput, type EventStore, type EventStoreTrimCoverage, type LaunchRunArgs, type RunLauncher, type RunState, type RunStatusSnapshot, type SnapshotStore } from '@swirls/looms/core';
+import { type Authorize, type LoomsRuntime, type StartResult, type StartRunArgs, type WakeScheduler } from '@swirls/looms/runtime';
 export interface ActorCellOptions<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly runId: string;
     readonly store: EventStore;
     readonly scheduler?: WakeScheduler;
     readonly modules: TModules;
+    /** Loads definitions that were not registered on a module. See `CreateRuntimeOptions`. */
+    readonly definitionResolver?: DefinitionResolver;
     readonly snapshotEvery?: number;
     readonly maxWakeIterations?: number;
     readonly maxPendingRunOperations?: number;
@@ -15,6 +17,8 @@ export interface ActorCellOptions<TModules extends readonly AnyRuntimeModule[] =
     };
     /** Authorizes the cell's HTTP API; see `createFetchHandler`. */
     readonly authorize?: Authorize;
+    /** Starts runs from effect handlers. Required for schedules; there is no default inside a cell. */
+    readonly launcher?: RunLauncher;
 }
 export interface ActorCell<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly runId: string;
@@ -24,6 +28,21 @@ export interface ActorCell<TModules extends readonly AnyRuntimeModule[] = readon
     wake(): Promise<RunState>;
     recoverWake(): Promise<number>;
     dispose(): Promise<void>;
+    /** Commit this cell's run and schedule a wake. A conflicting restart is a no-op. */
+    launch(args: LaunchRunArgs): Promise<void>;
+    status(): Promise<RunStatusSnapshot | null>;
+    startRun(args: StartRunArgs): Promise<StartResult>;
+    signal(events: ReadonlyArray<EventInput>, options?: {
+        idempotencyKey?: string;
+        coalesce?: boolean;
+    }): Promise<RunState>;
+    /** Append runtime-originated events. Not the client signal path. */
+    accept(events: ReadonlyArray<EventInput>, options?: {
+        idempotencyKey?: string;
+        coalesce?: boolean;
+    }): Promise<RunState>;
+    cancel(): Promise<void>;
+    getRun(): Promise<RunState>;
 }
 /**
  * Creates an in-process actor cell that owns a single `runId`.

package/dist/actor/cell.js

@@ -1,6 +1,6 @@
 import { Effect } from 'effect';
 import { EventStoreTag, } from '@swirls/looms/core';
-import { createFetchHandler, createRuntime, } from '@swirls/looms/runtime';
+import { createFetchHandler, createRuntime, StartRunConflictError, } from '@swirls/looms/runtime';
 import { runIdFromRequest } from './routing.js';
 /**
  * Creates an in-process actor cell that owns a single `runId`.
@@ -10,14 +10,17 @@ export function createActorCell(options) {
     const { runId, store, scheduler } = options;
     const runtime = createRuntime({
         modules: options.modules,
+        definitionResolver: options.definitionResolver,
         store,
         scheduler,
+        launcher: options.launcher,
         snapshotEvery: options.snapshotEvery,
         maxWakeIterations: options.maxWakeIterations,
         maxPendingRunOperations: options.maxPendingRunOperations,
         snapshotStore: options.snapshotStore,
         trimAfterSnapshot: options.trimAfterSnapshot,
     });
+    const provide = (effect) => Effect.runPromise(Effect.provideService(effect, EventStoreTag, store));
     const fetchHandler = createFetchHandler({ runtime, store, authorize: options.authorize });
     return {
         runId,
@@ -30,8 +33,17 @@ export function createActorCell(options) {
             }
             return fetchHandler(req).then((res) => res ?? new Response('Not Found', { status: 404 }));
         },
-        wake: () => Effect.runPromise(Effect.provideService(runtime.wake(runId), EventStoreTag, store)),
-        recoverWake: () => Effect.runPromise(Effect.provideService(runtime.rescanTimers, EventStoreTag, store)),
+        wake: () => provide(runtime.wake(runId)),
+        recoverWake: () => provide(runtime.rescanTimers),
         dispose: () => Effect.runPromise(runtime.dispose),
+        launch: (args) => provide(runtime.launchRun({ ...args, runId }).pipe(Effect.catchIf((error) => error instanceof StartRunConflictError, () => Effect.void), Effect.asVoid)),
+        status: () => provide(runtime
+            .getRun(runId)
+            .pipe(Effect.map((state) => (state.rootThreadId === null ? null : { status: state.status })))),
+        startRun: (args) => provide(runtime.startRun({ ...args, runId })),
+        signal: (events, signalOptions) => provide(runtime.signal(runId, events, signalOptions)),
+        accept: (events, signalOptions) => provide(runtime.accept(runId, events, signalOptions)),
+        cancel: () => provide(runtime.cancel(runId).pipe(Effect.asVoid)),
+        getRun: () => provide(runtime.getRun(runId)),
     };
 }

package/dist/actor/host.d.ts

@@ -1,9 +1,11 @@
-import type { AnyRuntimeModule, EventStore, EventStoreTrimCoverage, SnapshotStore } from '@swirls/looms/core';
-import { type Authorize } from '@swirls/looms/runtime';
+import type { AnyRuntimeModule, DefinitionResolver, EventInput, EventStore, EventStoreTrimCoverage, RunLauncher, RunState, SnapshotStore } from '@swirls/looms/core';
+import { type Authorize, type StartResult, type StartRunArgs } from '@swirls/looms/runtime';
 import { type ActorCell } from './cell';
 export interface LocalActorHostOptions<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     readonly createStore: (runId: string) => EventStore | Promise<EventStore>;
     readonly modules: TModules;
+    /** Loads definitions that were not registered on a module. See `CreateRuntimeOptions`. */
+    readonly definitionResolver?: DefinitionResolver;
     readonly snapshotStore?: SnapshotStore;
     readonly snapshotEvery?: number;
     readonly maxWakeIterations?: number;
@@ -21,6 +23,12 @@ export interface LocalActorHostOptions<TModules extends readonly AnyRuntimeModul
 }
 export interface LocalActorHost<TModules extends readonly AnyRuntimeModule[] = readonly AnyRuntimeModule[]> {
     getCell(runId: string): Promise<ActorCell<TModules>>;
+    readonly launcher: RunLauncher;
+    startRun(args: StartRunArgs): Promise<StartResult>;
+    signal(runId: string, events: ReadonlyArray<EventInput>, options?: {
+        idempotencyKey?: string;
+    }): Promise<RunState>;
+    getRun(runId: string): Promise<RunState>;
     fetch(req: Request): Promise<Response | null>;
     dispose(): Promise<void>;
 }

package/dist/actor/host.js

@@ -1,8 +1,8 @@
 import { Data, Effect } from 'effect';
-import { EventStoreTag } from '@swirls/looms/core';
-import { createTimeoutScheduler, isLoomsApiPath } from '@swirls/looms/runtime';
+import { createRemoteRunLauncher, EventStoreTag } from '@swirls/looms/core';
+import { createTimeoutScheduler, isLoomsApiPath, } from '@swirls/looms/runtime';
 import { createActorCell } from './cell.js';
-import { crossRunResponse, resolveRunTarget, RunTargetError } from './routing.js';
+import { crossRunResponse, definitionsResponse, resolveRunTarget, RunTargetError } from './routing.js';
 class ActorWakeError extends Data.TaggedError('ActorWakeError') {
     constructor(cause) {
         super({
@@ -28,7 +28,14 @@ class ActorHostError extends Data.TaggedError('ActorHostError') {
 export function createLocalActorHost(options) {
     const cells = new Map();
     const rescanTimers = options.rescanTimers !== false;
-    const getCell = (runId) => {
+    let getCell;
+    const launcher = createRemoteRunLauncher({
+        launch: (runId, args) => getCell(runId).then((cell) => cell.launch(args)),
+        status: (runId) => getCell(runId).then((cell) => cell.status()),
+        accept: (runId, events, signalOptions) => getCell(runId).then((cell) => cell.accept(events, signalOptions).then(() => undefined)),
+        cancel: (runId) => getCell(runId).then((cell) => cell.cancel()),
+    });
+    getCell = (runId) => {
         const existing = cells.get(runId);
         if (existing) {
             return existing;
@@ -51,11 +58,13 @@ export function createLocalActorHost(options) {
                 store,
                 scheduler,
                 modules: options.modules,
+                definitionResolver: options.definitionResolver,
                 snapshotStore: options.snapshotStore,
                 snapshotEvery: options.snapshotEvery,
                 maxWakeIterations: options.maxWakeIterations,
                 trimAfterSnapshot: options.trimAfterSnapshot,
                 authorize: options.authorize,
+                launcher,
             });
             wake = () => cell.wake();
             if (rescanTimers) {
@@ -68,6 +77,16 @@ export function createLocalActorHost(options) {
     };
     return {
         getCell,
+        launcher,
+        startRun: (args) => {
+            const runId = args.runId;
+            if (!runId) {
+                return Promise.reject(new Error('LocalActorHost.startRun requires runId'));
+            }
+            return getCell(runId).then((cell) => cell.startRun(args));
+        },
+        signal: (runId, events, signalOptions) => getCell(runId).then((cell) => cell.signal(events, signalOptions)),
+        getRun: (runId) => getCell(runId).then((cell) => cell.getRun()),
         fetch: (req) => {
             const url = new URL(req.url);
             if (!isLoomsApiPath(url.pathname)) {
@@ -76,6 +95,10 @@ export function createLocalActorHost(options) {
             if (url.pathname === '/health') {
                 return Promise.resolve(Response.json({ ok: true }));
             }
+            const definitions = definitionsResponse(req, options.modules);
+            if (definitions) {
+                return Promise.resolve(definitions);
+            }
             const unsupported = crossRunResponse(req, 'the actor host');
             if (unsupported) {
                 return Promise.resolve(unsupported);

package/dist/actor/index.d.ts

@@ -1,3 +1,4 @@
 export { createActorCell, type ActorCell, type ActorCellOptions } from './cell';
-export { crossRunResponse, runIdFromRequest, resolveRunTarget, RunTargetError, type ResolvedRunTarget, } from './routing';
+export { crossRunResponse, definitionsResponse, runIdFromRequest, resolveRunTarget, RunTargetError, type ResolvedRunTarget, } from './routing';
 export { createLocalActorHost, type LocalActorHost, type LocalActorHostOptions } from './host';
+export type { RunLauncher } from '@swirls/looms/core';

package/dist/actor/index.js

@@ -1,3 +1,3 @@
 export { createActorCell } from './cell.js';
-export { crossRunResponse, runIdFromRequest, resolveRunTarget, RunTargetError, } from './routing.js';
+export { crossRunResponse, definitionsResponse, runIdFromRequest, resolveRunTarget, RunTargetError, } from './routing.js';
 export { createLocalActorHost } from './host.js';

package/dist/actor/routing.d.ts

@@ -1,3 +1,4 @@
+import { type AnyRuntimeModule } from '@swirls/looms/core';
 /**
  * Extracts the target `runId` from a Looms HTTP request.
  * Inspects `x-looms-run-id` and `/runs/:runId/*`.
@@ -8,6 +9,8 @@ export declare function runIdFromRequest(req: Request): string | null;
  * runs needs a global index, and a fork writes a second run. `host` names the backend.
  */
 export declare function crossRunResponse(req: Request, host: string): Response | null;
+/** Answers `GET /definitions` from a module list or lazy factory without touching any run cell. */
+export declare function definitionsResponse(req: Request, modules: readonly AnyRuntimeModule[] | (() => readonly AnyRuntimeModule[]) | undefined): Response | null;
 export interface ResolvedRunTarget {
     readonly runId: string;
     readonly request: Request;

package/dist/actor/routing.js

@@ -1,5 +1,5 @@
-import { Data, Effect, Option, Schema } from 'effect';
-import { createRunId, isJsonObject, stringifyJson } from '@swirls/looms/core';
+import { Data, Effect, Option, Predicate, Schema } from 'effect';
+import { composeModules, createRunId, isJsonObject, publishDefinition, stringifyJson, } from '@swirls/looms/core';
 const RunTargetBodySchema = Schema.Struct({
     runId: Schema.optional(Schema.NonEmptyString),
 });
@@ -36,6 +36,17 @@ export function crossRunResponse(req, host) {
     }
     return null;
 }
+/** Answers `GET /definitions` from a module list or lazy factory without touching any run cell. */
+export function definitionsResponse(req, modules) {
+    if (!modules || req.method !== 'GET' || new URL(req.url).pathname !== '/definitions') {
+        return null;
+    }
+    const registry = composeModules(Predicate.isFunction(modules) ? modules() : modules);
+    return Response.json({
+        definitions: registry.definitions.map(publishDefinition),
+        projections: [...registry.projections.keys()],
+    });
+}
 export class RunTargetError extends Data.TaggedError('RunTargetError') {
     constructor(method, path) {
         super({

package/dist/agent/definitions-store.d.ts

@@ -6,5 +6,5 @@ declare const AgentDefinitionsTag_base: Context.ServiceClass<AgentDefinitionsTag
 export declare class AgentDefinitionsTag extends AgentDefinitionsTag_base {
 }
 export declare function makeAgentDefinitionStore(definitions: ReadonlyArray<AgentDefinition>): AgentDefinitionStore;
-export declare const AgentDefinitionsLive: (definitions: ReadonlyArray<AgentDefinition>) => Layer.Layer<AgentDefinitionsTag, never, never>;
+export declare const AgentDefinitionsLive: (definitions: AgentDefinitionStore) => Layer.Layer<AgentDefinitionsTag, never, never>;
 export {};

package/dist/agent/definitions-store.js

@@ -5,4 +5,4 @@ export class AgentDefinitionsTag extends Context.Service()('looms/AgentDefinitio
 export function makeAgentDefinitionStore(definitions) {
     return makeDefinitionStore('agent', definitions);
 }
-export const AgentDefinitionsLive = (definitions) => Layer.succeed(AgentDefinitionsTag, makeAgentDefinitionStore(definitions));
+export const AgentDefinitionsLive = (definitions) => Layer.succeed(AgentDefinitionsTag, definitions);

package/dist/agent/definitions.d.ts

@@ -3,6 +3,28 @@ import type { Schema } from 'effect';
 import { type JsonValue, type RuntimeEffect, type SchemaInput } from '@swirls/looms/core';
 import type { StopWhen } from './stop-when';
 import type { Message, ToolCall } from './types';
+export declare const TEAM_MEMBER_MAX_DEPTH: 3;
+export declare const STRUCTURED_OUTPUT_TOOL_NAME: 'submit_output';
+export interface AgentCompactionContext {
+    readonly threadId: string;
+    readonly turn: number;
+    readonly messages: readonly Message[];
+    readonly reason: 'overflow' | 'manual' | 'threshold';
+}
+export interface AgentCompactedResult {
+    readonly messages: readonly Message[];
+    readonly summary?: string;
+}
+export type AgentCompactor = (ctx: AgentCompactionContext) => Promise<AgentCompactedResult> | AgentCompactedResult;
+/**
+ * Keeps the first message (the task) and the most recent messages, replacing the rest with a
+ * note. The recent window never starts on a tool result, so every kept result still follows
+ * the assistant message that requested it.
+ */
+export declare function defaultAgentCompactor(ctx: AgentCompactionContext): AgentCompactedResult;
+/** Whether a model error reports that the prompt exceeded the model's context window. */
+export declare function isContextOverflowError(error: Error): boolean;
+export declare function buildStructuredOutputInstructions(toolName?: "submit_output"): string;
 export interface ToolContext {
     readonly threadId: string;
     readonly turn: number;
@@ -59,6 +81,17 @@ export interface AgentTurnContext<TInput = JsonValue> {
     readonly instructions: string;
     readonly signal?: AbortSignal;
 }
+/** What `resolveTools` sees. It runs before each model turn and again when a tool executes. */
+export interface AgentToolResolutionContext<TInput = JsonValue> {
+    readonly threadId: string;
+    readonly turn: number;
+    readonly input: TInput;
+}
+export interface AgentUsage {
+    readonly input: number;
+    readonly output: number;
+    readonly turn: number;
+}
 export interface AgentTurnResult<TOutput extends JsonValue = JsonValue> {
     message: Message;
     toolCalls?: ToolCall[];
@@ -77,7 +110,22 @@ export interface AgentDefinition<TName extends string = string, TInput = JsonVal
     readonly model?: string;
     readonly instructions: string;
     readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
+    readonly output?: StandardSchemaV1<any, TOutput> | Schema.ConstraintDecoder<TOutput> | SchemaInput;
     readonly tools?: ToolLike[];
+    /**
+     * Tools added for one turn, such as per-tenant integrations. Must return the same tools for the
+     * same input and turn, because tool execution resolves them again to find the handler.
+     */
+    resolveTools?(ctx: AgentToolResolutionContext<TInput>): Promise<readonly AgentToolEntry[]> | readonly AgentToolEntry[];
+    /** Shrinks the conversation after the model reports a context overflow. */
+    readonly compact?: AgentCompactor;
+    /** Runs before each model call. Throwing fails the agent thread with the thrown message. */
+    assertCredits?(ctx: AgentTurnContext<TInput>): Promise<void> | void;
+    /**
+     * Reports token usage after each model call. Usage is also recorded as `agent.turn.usage`;
+     * a retried turn calls this again, so deduplicate on `threadId` and `turn`.
+     */
+    trackUsage?(usage: AgentUsage, ctx: AgentTurnContext<TInput>): Promise<void> | void;
     readonly maxTurns?: number;
     readonly conversational?: boolean;
     readonly stopWhen?: StopWhen;

package/dist/agent/definitions.js

@@ -1,4 +1,48 @@
 import { DEFAULT_DEFINITION_VERSION, } from '@swirls/looms/core';
+export const TEAM_MEMBER_MAX_DEPTH = 3;
+export const STRUCTURED_OUTPUT_TOOL_NAME = 'submit_output';
+const COMPACTION_RECENT_MESSAGES = 4;
+/**
+ * Keeps the first message (the task) and the most recent messages, replacing the rest with a
+ * note. The recent window never starts on a tool result, so every kept result still follows
+ * the assistant message that requested it.
+ */
+export function defaultAgentCompactor(ctx) {
+    let start = ctx.messages.length - COMPACTION_RECENT_MESSAGES;
+    while (start > 1 && ctx.messages[start]?.role === 'tool') {
+        start -= 1;
+    }
+    if (start <= 1) {
+        return { messages: [...ctx.messages] };
+    }
+    const summary = `[${start - 1} earlier messages compacted for context window]`;
+    const summaryMessage = { role: 'system', content: summary };
+    return {
+        messages: [...ctx.messages.slice(0, 1), summaryMessage, ...ctx.messages.slice(start)],
+        summary,
+    };
+}
+const CONTEXT_OVERFLOW_MARKERS = [
+    'context window',
+    'context length',
+    'context_length_exceeded',
+    'maximum context',
+    'prompt is too long',
+    'prompt too long',
+    'too many tokens',
+];
+/** Whether a model error reports that the prompt exceeded the model's context window. */
+export function isContextOverflowError(error) {
+    const message = error.message.toLowerCase();
+    return CONTEXT_OVERFLOW_MARKERS.some((marker) => message.includes(marker));
+}
+export function buildStructuredOutputInstructions(toolName = STRUCTURED_OUTPUT_TOOL_NAME) {
+    return [
+        `This task requires structured output matching the output schema.`,
+        `When you have completed all work and have the final result, call the "${toolName}" tool with your output.`,
+        `If "${toolName}" returns an error indicating validation failure, inspect the errors, correct the values, and call "${toolName}" again.`,
+    ].join(' ');
+}
 export function defineAgentSession(def) {
     const definition = {
         kind: 'agent-session',