@swirls/looms 0.0.2 → 0.2.0

package/dist/agent/effects.js

@@ -1,5 +1,5 @@
-import { Effect, Predicate, Schema } from 'effect';
-import { createThreadId, validateInput } from '@swirls/looms/core';
+import { Data, Effect, Predicate, Schema } from 'effect';
+import { createThreadId, DEFAULT_DEFINITION_VERSION, validateInputEffect, } from '@swirls/looms/core';
 import { normalizeTools } from './definitions.js';
 import { AgentDefinitionsTag } from './definitions-store.js';
 import { LlmTag } from './llm.js';
@@ -7,16 +7,29 @@ import { agentModule } from './scope.js';
 import { toolSpecs } from './tool-schema.js';
 import { MessageSchema, ToolCallSchema } from './types.js';
 const CallLlmInput = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     definitionName: Schema.optional(Schema.String),
+    definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
     messages: Schema.optional(Schema.Array(MessageSchema)),
     input: Schema.optional(Schema.Json),
+    consumedSteerMessageIds: Schema.optional(Schema.Array(Schema.String)),
 });
 const ExecuteToolInput = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     definitionName: Schema.optional(Schema.String),
+    definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
     toolCall: ToolCallSchema,
 });
+class AgentExecutionError extends Data.TaggedError('AgentExecutionError') {
+    constructor(operation, cause) {
+        super({
+            operation,
+            cause,
+            message: cause instanceof Error ? cause.message : String(cause),
+        });
+        this.name = 'AgentExecutionError';
+    }
+}
 function findTool(tools, name) {
     return tools.find((tool) => tool.name === name);
 }
@@ -26,20 +39,22 @@ export const callLlmEffect = agentModule.effect({
     execute: (input, ctx) => runCallLlm({
         turn: input.turn,
         definitionName: input.definitionName,
-        // SAFETY: message arrays in callLLM input are serialized Message objects.
-        messages: input.messages ?? [],
+        definitionVersion: input.definitionVersion,
+        messages: [...(input.messages ?? [])],
         input: input.input ?? null,
+        consumedSteerMessageIds: [...(input.consumedSteerMessageIds ?? [])],
         runId: ctx.runId,
         threadId: ctx.threadId,
+        signal: ctx.signal,
         emit: (event) => ctx.emit(event),
     }),
 });
 function runCallLlm(args) {
     return Effect.gen(function* () {
-        const { turn, threadId, emit, definitionName, messages, input } = args;
+        const { turn, threadId, emit, definitionName, definitionVersion, messages, input, consumedSteerMessageIds, signal, } = args;
         const agents = yield* AgentDefinitionsTag;
         const llm = yield* LlmTag;
-        const definition = definitionName ? agents.get(definitionName) : undefined;
+        const definition = definitionName ? agents.get(definitionName, definitionVersion) : undefined;
         if (!definition) {
             return [
                 {
@@ -73,11 +88,12 @@ function runCallLlm(args) {
             input,
             tools,
             instructions: definition.instructions,
+            signal,
         };
         const result = definition.runTurn
             ? yield* Effect.tryPromise({
                 try: () => Promise.resolve(definition.runTurn(turnCtx)),
-                catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
+                catch: (cause) => new AgentExecutionError('run agent turn', cause),
             })
             : yield* llm.complete({
                 model: definition.model,
@@ -85,14 +101,13 @@ function runCallLlm(args) {
                 messages: [{ role: 'system', content: definition.instructions }, ...turnCtx.messages],
                 tools,
                 toolSpecs: toolSpecs(tools),
-                onTextDelta: async (delta) => {
-                    await emit({
-                        type: 'agent.turn.text_delta',
-                        payload: { turn, delta },
-                        threadId,
-                        ephemeral: true,
-                    });
-                },
+                signal,
+                onTextDelta: (delta) => emit({
+                    type: 'agent.turn.text_delta',
+                    payload: { turn, delta },
+                    threadId,
+                    ephemeral: true,
+                }),
             });
         const toolCalls = result.toolCalls ?? result.message.toolCalls ?? [];
         const shouldStop = definition.stopWhen?.({
@@ -113,9 +128,13 @@ function runCallLlm(args) {
         });
         if (shouldStop) {
             if (!definition.conversational) {
+                const output = result.output ?? { text: result.message.content };
                 events.push({
                     type: 'runtime.thread.completed',
-                    payload: { threadId, output: result.output ?? { text: result.message.content } },
+                    payload: {
+                        threadId,
+                        output: consumedSteerMessageIds.length === 0 ? output : { output, consumedSteerMessageIds },
+                    },
                     threadId,
                 });
             }
@@ -129,11 +148,12 @@ function runCallLlm(args) {
             });
         }
         if (toolCalls.length === 0 && !definition.conversational) {
+            const output = result.output ?? { text: result.message.content };
             events.push({
                 type: 'runtime.thread.completed',
                 payload: {
                     threadId,
-                    output: result.output ?? { text: result.message.content },
+                    output: consumedSteerMessageIds.length === 0 ? output : { output, consumedSteerMessageIds },
                 },
                 threadId,
             });
@@ -147,7 +167,9 @@ export const executeToolEffect = agentModule.effect({
     execute: (input, ctx) => Effect.gen(function* () {
         const threadId = ctx.threadId;
         const agents = yield* AgentDefinitionsTag;
-        const definition = input.definitionName ? agents.get(input.definitionName) : undefined;
+        const definition = input.definitionName
+            ? agents.get(input.definitionName, input.definitionVersion)
+            : undefined;
         if (!definition) {
             return [
                 {
@@ -182,10 +204,10 @@ export const executeToolEffect = agentModule.effect({
         }
         switch (tool.kind) {
             case 'function': {
-                const validated = yield* Effect.tryPromise({
-                    try: () => validateInput(tool.input, input.toolCall.arguments),
-                    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
-                }).pipe(Effect.map((value) => ({ ok: true, value })), Effect.catch((err) => Effect.succeed({ ok: false, error: err.message })));
+                const validated = yield* validateInputEffect(tool.input, input.toolCall.arguments).pipe(Effect.match({
+                    onFailure: (error) => ({ ok: false, error: error.message }),
+                    onSuccess: (value) => ({ ok: true, value }),
+                }));
                 if (!validated.ok) {
                     return [
                         {
@@ -206,8 +228,11 @@ export const executeToolEffect = agentModule.effect({
                         threadId,
                         turn: input.turn,
                     })),
-                    catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
-                }).pipe(Effect.map((value) => ({ ok: true, value })), Effect.catch((err) => Effect.succeed({ ok: false, error: err.message })));
+                    catch: (cause) => new AgentExecutionError(`run tool ${tool.name}`, cause),
+                }).pipe(Effect.match({
+                    onFailure: (error) => ({ ok: false, error: error.message }),
+                    onSuccess: (value) => ({ ok: true, value }),
+                }));
                 return [
                     {
                         type: 'agent.tool.result',
@@ -224,10 +249,10 @@ export const executeToolEffect = agentModule.effect({
             }
             case 'thread': {
                 const validated = tool.input
-                    ? yield* Effect.tryPromise({
-                        try: () => validateInput(tool.input, input.toolCall.arguments),
-                        catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
-                    }).pipe(Effect.map((value) => ({ ok: true, value })), Effect.catch((err) => Effect.succeed({ ok: false, error: err.message })))
+                    ? yield* validateInputEffect(tool.input, input.toolCall.arguments).pipe(Effect.match({
+                        onFailure: (error) => ({ ok: false, error: error.message }),
+                        onSuccess: (value) => ({ ok: true, value }),
+                    }))
                     : { ok: true, value: input.toolCall.arguments };
                 if (!validated.ok) {
                     return [
@@ -253,6 +278,7 @@ export const executeToolEffect = agentModule.effect({
                             childThreadId,
                             kind: tool.childKind,
                             definitionName: tool.childName,
+                            definitionVersion: tool.childVersion,
                             input: childInput,
                             toolCallId: input.toolCall.id,
                         },
@@ -262,10 +288,10 @@ export const executeToolEffect = agentModule.effect({
             }
             case 'effects': {
                 const validated = tool.input
-                    ? yield* Effect.tryPromise({
-                        try: () => validateInput(tool.input, input.toolCall.arguments),
-                        catch: (cause) => (cause instanceof Error ? cause : new Error(String(cause))),
-                    }).pipe(Effect.map((value) => ({ ok: true, value })), Effect.catch((err) => Effect.succeed({ ok: false, error: err.message })))
+                    ? yield* validateInputEffect(tool.input, input.toolCall.arguments).pipe(Effect.match({
+                        onFailure: (error) => ({ ok: false, error: error.message }),
+                        onSuccess: (value) => ({ ok: true, value }),
+                    }))
                     : { ok: true, value: input.toolCall.arguments };
                 if (!validated.ok) {
                     return [

package/dist/agent/events.d.ts

@@ -1,5 +1,4 @@
 import { Schema } from 'effect';
-import { type RuntimeEffect } from '@swirls/looms/core';
 export declare const AgentMessageReceivedPayloadSchema: Schema.Struct<{
     readonly message: Schema.Struct<{
         readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
@@ -14,14 +13,14 @@ export declare const AgentMessageReceivedPayloadSchema: Schema.Struct<{
     }>;
 }>;
 export declare const AgentTurnStartedPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
 }>;
 export declare const AgentTurnTextDeltaPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
     readonly delta: Schema.String;
 }>;
 export declare const AgentMessageEventPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
     readonly message: Schema.Struct<{
         readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
         readonly content: Schema.String;
@@ -34,12 +33,12 @@ export declare const AgentMessageEventPayloadSchema: Schema.Struct<{
         }>>>>;
     }>;
     readonly usage: Schema.optional<Schema.Struct<{
-        readonly input: Schema.Number;
-        readonly output: Schema.Number;
+        readonly input: Schema.Finite;
+        readonly output: Schema.Finite;
     }>>;
 }>;
 export declare const AgentToolCallRequestedPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
     readonly toolCall: Schema.Struct<{
         readonly id: Schema.String;
         readonly name: Schema.String;
@@ -47,14 +46,15 @@ export declare const AgentToolCallRequestedPayloadSchema: Schema.Struct<{
     }>;
 }>;
 export declare const AgentToolResultPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
     readonly toolCallId: Schema.String;
     readonly name: Schema.String;
     readonly result: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
     readonly error: Schema.NullOr<Schema.String>;
 }>;
 export declare const AgentSteeredPayloadSchema: Schema.Struct<{
-    readonly turn: Schema.Number;
+    readonly turn: Schema.Finite;
+    readonly messageId: Schema.optional<Schema.String>;
     readonly message: Schema.Struct<{
         readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
         readonly content: Schema.String;
@@ -68,16 +68,94 @@ export declare const AgentSteeredPayloadSchema: Schema.Struct<{
     }>;
     readonly interrupt: Schema.optional<Schema.Boolean>;
 }>;
+export declare const AgentSessionDeliverySchema: Schema.Union<readonly [Schema.Literal<"steer">, Schema.Literal<"followUp">, Schema.Literal<"nextTurn">]>;
+export declare const AgentSessionMessageSubmittedPayloadSchema: Schema.Struct<{
+    readonly messageId: Schema.String;
+    readonly text: Schema.String;
+    readonly delivery: Schema.optional<Schema.Union<readonly [Schema.Literal<"steer">, Schema.Literal<"followUp">, Schema.Literal<"nextTurn">]>>;
+    readonly activeChildThreadId: Schema.optional<Schema.String>;
+}>;
+export declare const AgentSessionSteerDeliveredPayloadSchema: Schema.Struct<{
+    readonly messageId: Schema.String;
+    readonly activeMessageId: Schema.String;
+}>;
+export declare const AgentSessionTurnStartedPayloadSchema: Schema.Struct<{
+    readonly messageId: Schema.String;
+    readonly childThreadId: Schema.String;
+}>;
+export declare const AgentSessionTurnClosedPayloadSchema: Schema.Struct<{
+    readonly messageId: Schema.String;
+    readonly status: Schema.Union<readonly [Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+    readonly error: Schema.optional<Schema.String>;
+}>;
+export declare const AgentSessionCancelRequestedPayloadSchema: Schema.Struct<{}>;
 export declare const AgentSpawnRequestedPayloadSchema: Schema.Struct<{
     readonly childThreadId: Schema.String;
     readonly kind: Schema.String;
     readonly definitionName: Schema.String;
+    readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
     readonly toolCallId: Schema.String;
     readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
 }>;
 export declare const AgentEffectsRequestedPayloadSchema: Schema.Struct<{
     readonly toolCallId: Schema.String;
-    readonly effects: Schema.$Array<Schema.Schema<RuntimeEffect>>;
+    readonly effects: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.spawn">;
+        readonly childThreadId: Schema.String;
+        readonly kind: Schema.String;
+        readonly definitionName: Schema.String;
+        readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.wait">;
+        readonly waitId: Schema.String;
+        readonly on: Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
+            readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly timerAt: Schema.Finite;
+        }>]>;
+        readonly tag: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.emit">;
+        readonly event: Schema.Struct<{
+            readonly type: Schema.String;
+            readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly threadId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly parentThreadId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly causationId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly correlationId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly effectId: Schema.optional<Schema.NullOr<Schema.String>>;
+            readonly origin: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Literal<"thread">;
+                readonly threadId: Schema.String;
+            }>, Schema.Struct<{
+                readonly type: Schema.Literal<"external">;
+                readonly actorId: Schema.optional<Schema.String>;
+            }>, Schema.Struct<{
+                readonly type: Schema.Literal<"system">;
+            }>]>>;
+            readonly ephemeral: Schema.optional<Schema.Boolean>;
+            readonly id: Schema.optional<Schema.String>;
+            readonly ts: Schema.optional<Schema.Finite>;
+            readonly idempotencyKey: Schema.optional<Schema.NullOr<Schema.String>>;
+        }>;
+        readonly tag: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.complete">;
+        readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.fail">;
+        readonly error: Schema.String;
+    }>, Schema.Struct<{
+        readonly type: Schema.Literal<"runtime.cancel">;
+        readonly threadId: Schema.String;
+        readonly tag: Schema.optional<Schema.String>;
+    }>, Schema.Struct<{
+        readonly type: Schema.String;
+        readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        readonly tag: Schema.optional<Schema.String>;
+    }>]>>;
     readonly waitOn: Schema.optional<Schema.Struct<{
         readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
         readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
@@ -98,14 +176,14 @@ export declare const agentCatalog: import("@swirls/looms/core").EventCatalog<"ag
         }>;
     }>;
     'turn.started': Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
     }>;
     'turn.text_delta': Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
         readonly delta: Schema.String;
     }>;
     message: Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
         readonly message: Schema.Struct<{
             readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
             readonly content: Schema.String;
@@ -118,12 +196,12 @@ export declare const agentCatalog: import("@swirls/looms/core").EventCatalog<"ag
             }>>>>;
         }>;
         readonly usage: Schema.optional<Schema.Struct<{
-            readonly input: Schema.Number;
-            readonly output: Schema.Number;
+            readonly input: Schema.Finite;
+            readonly output: Schema.Finite;
         }>>;
     }>;
     'tool_call.requested': Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
         readonly toolCall: Schema.Struct<{
             readonly id: Schema.String;
             readonly name: Schema.String;
@@ -131,14 +209,15 @@ export declare const agentCatalog: import("@swirls/looms/core").EventCatalog<"ag
         }>;
     }>;
     'tool.result': Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
         readonly toolCallId: Schema.String;
         readonly name: Schema.String;
         readonly result: Schema.NullOr<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
         readonly error: Schema.NullOr<Schema.String>;
     }>;
     steered: Schema.Struct<{
-        readonly turn: Schema.Number;
+        readonly turn: Schema.Finite;
+        readonly messageId: Schema.optional<Schema.String>;
         readonly message: Schema.Struct<{
             readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
             readonly content: Schema.String;
@@ -152,16 +231,93 @@ export declare const agentCatalog: import("@swirls/looms/core").EventCatalog<"ag
         }>;
         readonly interrupt: Schema.optional<Schema.Boolean>;
     }>;
+    'session.message.submitted': Schema.Struct<{
+        readonly messageId: Schema.String;
+        readonly text: Schema.String;
+        readonly delivery: Schema.optional<Schema.Union<readonly [Schema.Literal<"steer">, Schema.Literal<"followUp">, Schema.Literal<"nextTurn">]>>;
+        readonly activeChildThreadId: Schema.optional<Schema.String>;
+    }>;
+    'session.steer.delivered': Schema.Struct<{
+        readonly messageId: Schema.String;
+        readonly activeMessageId: Schema.String;
+    }>;
+    'session.turn.started': Schema.Struct<{
+        readonly messageId: Schema.String;
+        readonly childThreadId: Schema.String;
+    }>;
+    'session.turn.closed': Schema.Struct<{
+        readonly messageId: Schema.String;
+        readonly status: Schema.Union<readonly [Schema.Literal<"completed">, Schema.Literal<"failed">, Schema.Literal<"cancelled">]>;
+        readonly error: Schema.optional<Schema.String>;
+    }>;
+    'session.cancel.requested': Schema.Struct<{}>;
     'spawn.requested': Schema.Struct<{
         readonly childThreadId: Schema.String;
         readonly kind: Schema.String;
         readonly definitionName: Schema.String;
+        readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
         readonly toolCallId: Schema.String;
         readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     }>;
     'effects.requested': Schema.Struct<{
         readonly toolCallId: Schema.String;
-        readonly effects: Schema.$Array<Schema.Schema<RuntimeEffect>>;
+        readonly effects: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.spawn">;
+            readonly childThreadId: Schema.String;
+            readonly kind: Schema.String;
+            readonly definitionName: Schema.String;
+            readonly definitionVersion: Schema.withDecodingDefaultKey<Schema.String, never>;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.wait">;
+            readonly waitId: Schema.String;
+            readonly on: Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
+                readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            }>, Schema.Struct<{
+                readonly timerAt: Schema.Finite;
+            }>]>;
+            readonly tag: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.emit">;
+            readonly event: Schema.Struct<{
+                readonly type: Schema.String;
+                readonly payload: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+                readonly threadId: Schema.optional<Schema.NullOr<Schema.String>>;
+                readonly parentThreadId: Schema.optional<Schema.NullOr<Schema.String>>;
+                readonly causationId: Schema.optional<Schema.NullOr<Schema.String>>;
+                readonly correlationId: Schema.optional<Schema.NullOr<Schema.String>>;
+                readonly effectId: Schema.optional<Schema.NullOr<Schema.String>>;
+                readonly origin: Schema.optional<Schema.Union<readonly [Schema.Struct<{
+                    readonly type: Schema.Literal<"thread">;
+                    readonly threadId: Schema.String;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"external">;
+                    readonly actorId: Schema.optional<Schema.String>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"system">;
+                }>]>>;
+                readonly ephemeral: Schema.optional<Schema.Boolean>;
+                readonly id: Schema.optional<Schema.String>;
+                readonly ts: Schema.optional<Schema.Finite>;
+                readonly idempotencyKey: Schema.optional<Schema.NullOr<Schema.String>>;
+            }>;
+            readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.complete">;
+            readonly output: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.fail">;
+            readonly error: Schema.String;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"runtime.cancel">;
+            readonly threadId: Schema.String;
+            readonly tag: Schema.optional<Schema.String>;
+        }>, Schema.Struct<{
+            readonly type: Schema.String;
+            readonly input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+            readonly tag: Schema.optional<Schema.String>;
+        }>]>>;
         readonly waitOn: Schema.optional<Schema.Struct<{
             readonly type: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.String>]>;
             readonly match: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;

package/dist/agent/events.js

@@ -1,48 +1,78 @@
-import { Schema } from 'effect';
-import { defineEventCatalog } from '@swirls/looms/core';
+import { Effect, Schema } from 'effect';
+import { DEFAULT_DEFINITION_VERSION, defineEventCatalog, RuntimeEffectSchema } from '@swirls/looms/core';
 import { MessageSchema, TokenUsageSchema, ToolCallSchema } from './types.js';
 export const AgentMessageReceivedPayloadSchema = Schema.Struct({
     message: MessageSchema,
 });
 export const AgentTurnStartedPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
 });
 export const AgentTurnTextDeltaPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     delta: Schema.String,
 });
 export const AgentMessageEventPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     message: MessageSchema,
     usage: Schema.optional(TokenUsageSchema),
 });
 export const AgentToolCallRequestedPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     toolCall: ToolCallSchema,
 });
 export const AgentToolResultPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
     toolCallId: Schema.String,
     name: Schema.String,
     result: Schema.NullOr(Schema.Json),
     error: Schema.NullOr(Schema.String),
 });
 export const AgentSteeredPayloadSchema = Schema.Struct({
-    turn: Schema.Number,
+    turn: Schema.Finite,
+    messageId: Schema.optional(Schema.String),
     message: MessageSchema,
     interrupt: Schema.optional(Schema.Boolean),
 });
+export const AgentSessionDeliverySchema = Schema.Union([
+    Schema.Literal('steer'),
+    Schema.Literal('followUp'),
+    Schema.Literal('nextTurn'),
+]);
+export const AgentSessionMessageSubmittedPayloadSchema = Schema.Struct({
+    messageId: Schema.String,
+    text: Schema.String,
+    delivery: Schema.optional(AgentSessionDeliverySchema),
+    activeChildThreadId: Schema.optional(Schema.String),
+});
+export const AgentSessionSteerDeliveredPayloadSchema = Schema.Struct({
+    messageId: Schema.String,
+    activeMessageId: Schema.String,
+});
+export const AgentSessionTurnStartedPayloadSchema = Schema.Struct({
+    messageId: Schema.String,
+    childThreadId: Schema.String,
+});
+export const AgentSessionTurnClosedPayloadSchema = Schema.Struct({
+    messageId: Schema.String,
+    status: Schema.Union([
+        Schema.Literal('completed'),
+        Schema.Literal('failed'),
+        Schema.Literal('cancelled'),
+    ]),
+    error: Schema.optional(Schema.String),
+});
+export const AgentSessionCancelRequestedPayloadSchema = Schema.Struct({});
 export const AgentSpawnRequestedPayloadSchema = Schema.Struct({
     childThreadId: Schema.String,
     kind: Schema.String,
     definitionName: Schema.String,
+    definitionVersion: Schema.String.pipe(Schema.withDecodingDefaultKey(Effect.succeed(DEFAULT_DEFINITION_VERSION))),
     toolCallId: Schema.String,
     input: Schema.Json,
 });
 export const AgentEffectsRequestedPayloadSchema = Schema.Struct({
     toolCallId: Schema.String,
-    // SAFETY: RuntimeEffect represents serializable requested effect instructions.
-    effects: Schema.Array(Schema.Unknown),
+    effects: Schema.Array(RuntimeEffectSchema),
     waitOn: Schema.optional(Schema.Struct({
         type: Schema.Union([Schema.String, Schema.Array(Schema.String)]),
         match: Schema.optional(Schema.Json),
@@ -56,6 +86,11 @@ export const agentCatalog = defineEventCatalog('agent', {
     'tool_call.requested': AgentToolCallRequestedPayloadSchema,
     'tool.result': AgentToolResultPayloadSchema,
     steered: AgentSteeredPayloadSchema,
+    'session.message.submitted': AgentSessionMessageSubmittedPayloadSchema,
+    'session.steer.delivered': AgentSessionSteerDeliveredPayloadSchema,
+    'session.turn.started': AgentSessionTurnStartedPayloadSchema,
+    'session.turn.closed': AgentSessionTurnClosedPayloadSchema,
+    'session.cancel.requested': AgentSessionCancelRequestedPayloadSchema,
     'spawn.requested': AgentSpawnRequestedPayloadSchema,
     'effects.requested': AgentEffectsRequestedPayloadSchema,
 });

package/dist/agent/index.d.ts

@@ -11,3 +11,4 @@ export * from './signals';
 export * from './llm';
 export * from './tool-schema';
 export * from './module';
+export * from './agent-session';

package/dist/agent/index.js

@@ -11,3 +11,4 @@ export * from './signals.js';
 export * from './llm.js';
 export * from './tool-schema.js';
 export * from './module.js';
+export * from './agent-session.js';

package/dist/agent/llm.d.ts

@@ -1,5 +1,5 @@
 import { Context, Effect, Layer } from 'effect';
-import type { JsonValue } from '@swirls/looms/core';
+import { type JsonValue } from '@swirls/looms/core';
 import type { AgentTurnContext, AgentTurnResult, ToolLike } from './definitions';
 import type { Message, ToolCall } from './types';
 export interface LlmToolSpec {
@@ -17,11 +17,20 @@ export interface LlmCompleteArgs {
     signal?: AbortSignal;
 }
 export interface LlmService {
-    readonly complete: (args: LlmCompleteArgs) => Effect.Effect<AgentTurnResult, Error>;
+    readonly complete: (args: LlmCompleteArgs) => Effect.Effect<AgentTurnResult, LlmError>;
 }
 export interface LlmAdapter {
     readonly complete: (args: LlmCompleteArgs) => Promise<AgentTurnResult>;
 }
+declare const LlmError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "LlmError";
+} & Readonly<A>;
+export declare class LlmError extends LlmError_base<{
+    readonly cause: unknown;
+    readonly message: string;
+}> {
+    constructor(cause: unknown);
+}
 export declare function llmFromAdapter(adapter: LlmAdapter): LlmService;
 declare const LlmTag_base: Context.ServiceClass<LlmTag, "looms/Llm", LlmService>;
 export declare class LlmTag extends LlmTag_base {