@swirls/looms 0.0.2 → 0.1.0

package/dist/agent/agent-session.js

@@ -0,0 +1,270 @@
+import { Predicate } from 'effect';
+import { cancel, createWaitId, deterministicThreadId, emit, spawn, wait, } from '@swirls/looms/core';
+import { agentModule } from './scope.js';
+function objectPayload(event) {
+    return Predicate.isObject(event.payload) ? event.payload : {};
+}
+function messageFrom(value) {
+    const payload = Predicate.isObject(value) ? value : {};
+    return Predicate.isString(payload.messageId) && Predicate.isString(payload.text)
+        ? {
+            messageId: payload.messageId,
+            text: payload.text,
+            delivery: payload.delivery === 'steer' ||
+                payload.delivery === 'followUp' ||
+                payload.delivery === 'nextTurn'
+                ? payload.delivery
+                : undefined,
+        }
+        : null;
+}
+function consumedIds(event) {
+    const payload = objectPayload(event);
+    const embedded = Predicate.isObject(payload.event) ? payload.event : {};
+    const embeddedPayload = Predicate.isObject(embedded.payload) ? embedded.payload : {};
+    const output = Predicate.isObject(embeddedPayload.output) ? embeddedPayload.output : {};
+    const ids = output.consumedSteerMessageIds;
+    return Array.isArray(ids) ? ids.filter(Predicate.isString) : [];
+}
+function closureStatus(event) {
+    const payload = objectPayload(event);
+    const embedded = Predicate.isObject(payload.event) ? payload.event : {};
+    const embeddedPayload = Predicate.isObject(embedded.payload) ? embedded.payload : {};
+    const status = embedded.type === 'runtime.thread.completed'
+        ? 'completed'
+        : embedded.type === 'runtime.thread.cancelled'
+            ? 'cancelled'
+            : 'failed';
+    const error = Predicate.isString(embeddedPayload.error) ? embeddedPayload.error : undefined;
+    return { status, error };
+}
+function close(messageId, status, error) {
+    return error === undefined ? { messageId, status } : { messageId, status, error };
+}
+export function createAgentSessionThread(definitions) {
+    return agentModule.thread({
+        kind: 'agent-session',
+        initialState: (ctx) => {
+            const definition = definitions.get(ctx.definitionName, ctx.definitionVersion);
+            return {
+                definitionName: ctx.definitionName,
+                definitionVersion: ctx.definitionVersion,
+                pendingMessages: [],
+                nextTurnMessages: [],
+                processedMessageIds: [],
+                activeTurn: null,
+                pendingSteerDeliveries: [],
+                pendingClosures: [],
+                lastSequence: 0,
+                idleTimeoutMs: definition?.idleTimeoutMs ?? 0,
+                idleDeadlineAt: null,
+                parked: false,
+                cancelling: false,
+            };
+        },
+        step(state, event) {
+            switch (event.type) {
+                case 'runtime.thread.started': {
+                    const initial = messageFrom(objectPayload(event).input);
+                    const idleDeadlineAt = state.idleTimeoutMs > 0 ? event.ts + state.idleTimeoutMs : null;
+                    if (!initial || state.processedMessageIds.includes(initial.messageId)) {
+                        return { ...state, idleDeadlineAt };
+                    }
+                    return {
+                        ...state,
+                        pendingMessages: [initial],
+                        processedMessageIds: [initial.messageId],
+                        idleDeadlineAt,
+                    };
+                }
+                case 'agent.session.message.submitted': {
+                    const payload = objectPayload(event);
+                    const message = messageFrom(payload);
+                    if (!message || state.processedMessageIds.includes(message.messageId)) {
+                        return state;
+                    }
+                    const processedMessageIds = [...state.processedMessageIds, message.messageId];
+                    const idleDeadlineAt = state.idleTimeoutMs > 0 ? event.ts + state.idleTimeoutMs : null;
+                    if (message.delivery === 'nextTurn') {
+                        return {
+                            ...state,
+                            nextTurnMessages: [...state.nextTurnMessages, message],
+                            processedMessageIds,
+                            idleDeadlineAt,
+                            parked: false,
+                        };
+                    }
+                    const queued = message.delivery === 'steer' && state.activeTurn
+                        ? { ...message, steeredIntoMessageId: state.activeTurn.messageId }
+                        : message;
+                    return {
+                        ...state,
+                        pendingMessages: [...state.pendingMessages, queued],
+                        pendingSteerDeliveries: queued.steeredIntoMessageId &&
+                            state.activeTurn &&
+                            payload.activeChildThreadId !== state.activeTurn.childThreadId
+                            ? [...state.pendingSteerDeliveries, queued]
+                            : state.pendingSteerDeliveries,
+                        processedMessageIds,
+                        idleDeadlineAt,
+                        parked: false,
+                    };
+                }
+                case 'agent.session.turn.started': {
+                    const messageId = event.payload.messageId;
+                    const admitted = state.pendingMessages.find((message) => message.messageId === messageId);
+                    const text = [...state.nextTurnMessages, ...(admitted ? [admitted] : [])]
+                        .map((message) => message.text)
+                        .join('\n');
+                    return {
+                        ...state,
+                        pendingMessages: state.pendingMessages.filter((message) => message.messageId !== messageId),
+                        activeTurn: {
+                            messageId,
+                            childThreadId: event.payload.childThreadId,
+                            text,
+                        },
+                        nextTurnMessages: [],
+                        lastSequence: state.lastSequence + 1,
+                        cancelling: false,
+                    };
+                }
+                case 'agent.session.steer.delivered':
+                    return {
+                        ...state,
+                        pendingSteerDeliveries: state.pendingSteerDeliveries.filter((message) => message.messageId !== event.payload.messageId),
+                    };
+                case 'agent.session.turn.closed':
+                    return {
+                        ...state,
+                        pendingClosures: state.pendingClosures.filter((closure) => closure.messageId !== event.payload.messageId),
+                    };
+                case 'agent.session.cancel.requested':
+                case 'runtime.thread.cancel.requested':
+                    return state.activeTurn ? { ...state, cancelling: true } : state;
+                case 'runtime.wait.satisfied': {
+                    const payload = objectPayload(event);
+                    const tag = Predicate.isObject(payload.tag) ? payload.tag : {};
+                    if (tag.kind === 'agent-session-idle') {
+                        if (tag.deadlineAt === state.idleDeadlineAt && state.activeTurn === null) {
+                            return { ...state, parked: true, idleDeadlineAt: null };
+                        }
+                        return state;
+                    }
+                    if (tag.kind !== 'agent-session-turn' || !state.activeTurn) {
+                        return state;
+                    }
+                    const active = state.activeTurn;
+                    const consumed = new Set(consumedIds(event));
+                    const result = closureStatus(event);
+                    const pendingClosures = [
+                        ...state.pendingClosures,
+                        close(active.messageId, result.status, result.error),
+                        ...[...consumed].map((messageId) => close(messageId, result.status, result.error)),
+                    ];
+                    return {
+                        ...state,
+                        pendingMessages: state.pendingMessages.flatMap((message) => {
+                            if (consumed.has(message.messageId)) {
+                                return [];
+                            }
+                            return message.steeredIntoMessageId === active.messageId
+                                ? [{ ...message, steeredIntoMessageId: undefined }]
+                                : [message];
+                        }),
+                        pendingSteerDeliveries: state.pendingSteerDeliveries.filter((message) => !consumed.has(message.messageId) &&
+                            message.steeredIntoMessageId !== active.messageId),
+                        pendingClosures,
+                        activeTurn: null,
+                        lastSequence: state.lastSequence + 1,
+                        cancelling: false,
+                        idleDeadlineAt: state.idleTimeoutMs > 0 ? event.ts + state.idleTimeoutMs : null,
+                    };
+                }
+                default:
+                    return state;
+            }
+        },
+        effects(state, ctx) {
+            const effects = [];
+            for (const closure of state.pendingClosures) {
+                effects.push(emit(agentModule.input('session.turn.closed', { messageId: closure.messageId, status: closure.status, error: closure.error }, { threadId: ctx.threadId }), `session_close_${closure.messageId}`));
+            }
+            for (const message of state.pendingSteerDeliveries) {
+                if (!state.activeTurn || message.steeredIntoMessageId !== state.activeTurn.messageId) {
+                    continue;
+                }
+                effects.push(emit(agentModule.input('steered', {
+                    turn: 0,
+                    messageId: message.messageId,
+                    message: { role: 'user', content: message.text },
+                    interrupt: true,
+                }, { threadId: state.activeTurn.childThreadId }), `session_steer_${message.messageId}`), emit(agentModule.input('session.steer.delivered', { messageId: message.messageId, activeMessageId: state.activeTurn.messageId }, { threadId: ctx.threadId }), `session_steer_delivered_${message.messageId}`));
+            }
+            if (state.activeTurn) {
+                const { childThreadId: turnThreadId, messageId, text } = state.activeTurn;
+                const definition = definitions.get(state.definitionName, state.definitionVersion);
+                if (state.cancelling) {
+                    effects.push(cancel(turnThreadId));
+                }
+                else if (definition) {
+                    effects.push(spawn({
+                        childThreadId: turnThreadId,
+                        kind: 'agent',
+                        definitionName: definition.agent.name,
+                        definitionVersion: definition.agent.version,
+                        input: { text },
+                    }));
+                }
+                // The turn wait must survive cancellation: the child's cancelled event is what closes it.
+                effects.push(wait({
+                    waitId: createWaitId(ctx.threadId, `turn_${messageId}`),
+                    on: {
+                        type: [
+                            'runtime.thread.completed',
+                            'runtime.thread.failed',
+                            'runtime.thread.cancelled',
+                        ],
+                        match: { threadId: turnThreadId },
+                    },
+                    tag: { kind: 'agent-session-turn', messageId },
+                }));
+                return effects;
+            }
+            const next = state.pendingMessages.find((message) => message.steeredIntoMessageId === undefined);
+            if (next) {
+                effects.push(emit(agentModule.input('session.turn.started', {
+                    messageId: next.messageId,
+                    childThreadId: deterministicThreadId(ctx.threadId, 'turn', next.messageId),
+                }, { threadId: ctx.threadId }), `session_admit_${next.messageId}`));
+                return effects;
+            }
+            if (state.parked || state.idleTimeoutMs === 0 || state.idleDeadlineAt === null) {
+                effects.push(wait({
+                    waitId: createWaitId(ctx.threadId, 'mailbox'),
+                    on: { type: 'agent.session.message.submitted', match: { threadId: ctx.threadId } },
+                    tag: { kind: 'agent-session-mailbox' },
+                }));
+            }
+            else {
+                effects.push(wait({
+                    waitId: createWaitId(ctx.threadId, `idle_${state.idleDeadlineAt}`),
+                    on: { timerAt: state.idleDeadlineAt },
+                    tag: { kind: 'agent-session-idle', deadlineAt: state.idleDeadlineAt },
+                }));
+            }
+            return effects;
+        },
+    });
+}
+export function agentSessionSnapshot(state) {
+    return {
+        activeTurnId: state.activeTurn?.messageId ?? null,
+        activeChildThreadId: state.activeTurn?.childThreadId ?? null,
+        pendingMessageCount: state.pendingMessages.length,
+        nextTurnHeldCount: state.nextTurnMessages.length,
+        processedMessageIds: state.processedMessageIds,
+        lastSequence: state.lastSequence,
+        parked: state.parked,
+    };
+}

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

@@ -1,8 +1,7 @@
 import { Context, Layer } from 'effect';
+import { type DefinitionStore } from '@swirls/looms/core';
 import type { AgentDefinition } from './definitions';
-export interface AgentDefinitionStore {
-    get(name: string): AgentDefinition | undefined;
-}
+export type AgentDefinitionStore = DefinitionStore<AgentDefinition>;
 declare const AgentDefinitionsTag_base: Context.ServiceClass<AgentDefinitionsTag, "looms/AgentDefinitions", AgentDefinitionStore>;
 export declare class AgentDefinitionsTag extends AgentDefinitionsTag_base {
 }

package/dist/agent/definitions-store.js

@@ -1,10 +1,8 @@
 import { Context, Layer } from 'effect';
+import { makeDefinitionStore } from '@swirls/looms/core';
 export class AgentDefinitionsTag extends Context.Service()('looms/AgentDefinitions') {
 }
 export function makeAgentDefinitionStore(definitions) {
-    const map = new Map(definitions.map((def) => [def.name, def]));
-    return {
-        get: (name) => map.get(name),
-    };
+    return makeDefinitionStore('agent', definitions);
 }
 export const AgentDefinitionsLive = (definitions) => Layer.succeed(AgentDefinitionsTag, makeAgentDefinitionStore(definitions));

package/dist/agent/definitions.d.ts

@@ -1,6 +1,6 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Schema } from 'effect';
-import type { InferDefinedSchema, JsonValue, RuntimeEffect, SchemaInput } from '@swirls/looms/core';
+import { type JsonValue, type RuntimeEffect, type SchemaInput } from '@swirls/looms/core';
 import type { StopWhen } from './stop-when';
 import type { Message, ToolCall } from './types';
 export interface ToolContext {
@@ -12,7 +12,7 @@ export interface FunctionTool<TName extends string = string, TInput = JsonValue,
     readonly kind: 'function';
     readonly name: TName;
     readonly description: string;
-    readonly input?: StandardSchemaV1<any, TInput> | Schema.Schema<TInput>;
+    readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
     readonly inputSchema?: JsonValue;
     handler(input: TInput, ctx: ToolContext): Promise<TOutput> | TOutput;
 }
@@ -24,9 +24,11 @@ export interface ThreadTool {
     readonly inputSchema?: JsonValue;
     readonly childKind: string;
     readonly childName: string;
+    readonly childVersion: string;
     readonly child: {
         kind: string;
         name: string;
+        version?: string;
     };
     mapInput?(input: JsonValue): JsonValue;
 }
@@ -46,6 +48,7 @@ export type ToolLike = FunctionTool | ThreadTool | EffectsTool;
 export type AgentToolEntry = ToolLike | {
     kind: string;
     name: string;
+    version?: string;
     instructions?: string;
     description?: string;
     input?: SchemaInput;
@@ -57,6 +60,7 @@ export interface AgentTurnContext<TInput = JsonValue> {
     readonly input: TInput;
     readonly tools: ToolLike[];
     readonly instructions: string;
+    readonly signal?: AbortSignal;
 }
 export interface AgentTurnResult<TOutput extends JsonValue = JsonValue> {
     message: Message;
@@ -71,9 +75,10 @@ export interface AgentTurnResult<TOutput extends JsonValue = JsonValue> {
 export interface AgentDefinition<TName extends string = string, TInput = JsonValue, TOutput extends JsonValue = JsonValue> {
     readonly kind: 'agent';
     readonly name: TName;
+    readonly version: string;
     readonly model?: string;
     readonly instructions: string;
-    readonly input?: StandardSchemaV1<any, TInput> | Schema.Schema<TInput>;
+    readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
     readonly tools?: ToolLike[];
     readonly maxTurns?: number;
     readonly conversational?: boolean;
@@ -81,24 +86,26 @@ export interface AgentDefinition<TName extends string = string, TInput = JsonVal
     runTurn?(ctx: AgentTurnContext<TInput>): Promise<AgentTurnResult<TOutput>> | AgentTurnResult<TOutput>;
 }
 export type AnyAgentDefinition = AgentDefinition;
+export interface AgentSessionDefinition<TName extends string = string> {
+    readonly kind: 'agent-session';
+    readonly name: TName;
+    readonly version: string;
+    /** The agent definition is pinned when the session definition is created. */
+    readonly agent: Pick<AgentDefinition, 'kind' | 'name' | 'version'>;
+    /** Max idle milliseconds before parking. Zero waits indefinitely. */
+    readonly idleTimeoutMs: number;
+}
+export declare function defineAgentSession<TName extends string>(def: {
+    readonly name: TName;
+    readonly agent: Pick<AgentDefinition, 'kind' | 'name' | 'version'>;
+    readonly version?: string;
+    readonly idleTimeoutMs?: number;
+}): AgentSessionDefinition<TName>;
 export declare function normalizeTools(tools?: ReadonlyArray<AgentToolEntry>): ToolLike[];
-export declare function defineTool<TName extends string, TSchema = undefined, TInput = InferDefinedSchema<TSchema>, TOutput extends JsonValue = JsonValue>(def: {
-    name: TName;
-    description: string;
-    input?: TSchema;
-    inputSchema?: JsonValue;
-    handler: (input: TInput, ctx: ToolContext) => Promise<TOutput> | TOutput;
-}): FunctionTool<TName, TInput, TOutput>;
-export declare function defineAgent<TName extends string, TSchema = undefined, TInput = InferDefinedSchema<TSchema>, TOutput extends JsonValue = JsonValue>(def: {
-    name: TName;
-    model?: string;
-    instructions: string;
-    input?: TSchema;
-    tools?: AgentToolEntry[];
-    maxTurns?: number;
-    conversational?: boolean;
-    stopWhen?: StopWhen;
-    runTurn?: (ctx: AgentTurnContext<TInput>) => Promise<AgentTurnResult<TOutput>> | AgentTurnResult<TOutput>;
+export declare function defineTool<TName extends string, TInput = JsonValue, TOutput extends JsonValue = JsonValue>(def: Omit<FunctionTool<TName, TInput, TOutput>, 'kind'>): FunctionTool<TName, TInput, TOutput>;
+export declare function defineAgent<TName extends string, TInput = JsonValue, TOutput extends JsonValue = JsonValue>(def: Omit<AgentDefinition<TName, TInput, TOutput>, 'kind' | 'version' | 'tools'> & {
+    readonly version?: string;
+    readonly tools?: AgentToolEntry[];
 }): AgentDefinition<TName, TInput, TOutput>;
 export declare function asThreadTool(def: {
     name?: string;
@@ -108,6 +115,7 @@ export declare function asThreadTool(def: {
     child: {
         kind: string;
         name: string;
+        version?: string;
     };
     mapInput?: (input: JsonValue) => JsonValue;
 }): ThreadTool;
@@ -119,12 +127,28 @@ export declare function asAgentTool(def: {
     agent: {
         kind: 'agent';
         name: string;
+        version?: string;
         instructions?: string;
         input?: SchemaInput;
         inputSchema?: JsonValue;
     };
     mapInput?: (input: JsonValue) => JsonValue;
 }): ThreadTool;
+type EvaluatorToolTarget = {
+    kind: 'evaluator';
+    name: string;
+    description?: string;
+    input?: SchemaInput;
+    inputSchema?: JsonValue;
+};
+export declare function asEvaluatorTool(def: {
+    name?: string;
+    description?: string;
+    input?: SchemaInput;
+    inputSchema?: JsonValue;
+    evaluator: EvaluatorToolTarget;
+    mapInput?: (input: JsonValue) => JsonValue;
+}): ThreadTool;
 export declare function asWorkflowTool(def: {
     name?: string;
     description?: string;
@@ -133,6 +157,7 @@ export declare function asWorkflowTool(def: {
     workflow: {
         kind: 'workflow';
         name: string;
+        version?: string;
         description?: string;
         input?: SchemaInput;
         inputSchema?: JsonValue;
@@ -150,3 +175,4 @@ export declare function asEffectsTool(def: {
         match?: JsonValue;
     };
 }): EffectsTool;
+export {};

package/dist/agent/definitions.js

@@ -1,7 +1,26 @@
+import { DEFAULT_DEFINITION_VERSION, } from '@swirls/looms/core';
+export function defineAgentSession(def) {
+    return {
+        kind: 'agent-session',
+        name: def.name,
+        version: def.version ?? DEFAULT_DEFINITION_VERSION,
+        agent: {
+            kind: 'agent',
+            name: def.agent.name,
+            version: def.agent.version,
+        },
+        idleTimeoutMs: Math.max(0, def.idleTimeoutMs ?? 0),
+    };
+}
 export function normalizeTools(tools = []) {
     return tools.map((entry) => {
-        if (entry.kind === 'function' || entry.kind === 'thread' || entry.kind === 'effects') {
-            // SAFETY: kind discriminant matches ToolLike.
+        if (entry.kind === 'function' && 'handler' in entry) {
+            return entry;
+        }
+        if (entry.kind === 'thread' && 'child' in entry) {
+            return entry;
+        }
+        if (entry.kind === 'effects' && 'effects' in entry) {
             return entry;
         }
         return asThreadTool({
@@ -16,15 +35,13 @@ export function normalizeTools(tools = []) {
     });
 }
 export function defineTool(def) {
-    // SAFETY: factory fields match FunctionTool.
-    return { kind: 'function', ...def, input: def.input };
+    return { kind: 'function', ...def };
 }
 export function defineAgent(def) {
-    // SAFETY: factory fields match AgentDefinition.
     return {
         kind: 'agent',
         ...def,
-        input: def.input,
+        version: def.version ?? DEFAULT_DEFINITION_VERSION,
         tools: def.tools ? normalizeTools(def.tools) : undefined,
     };
 }
@@ -37,6 +54,7 @@ export function asThreadTool(def) {
         inputSchema: def.inputSchema,
         childKind: def.child.kind,
         childName: def.child.name,
+        childVersion: def.child.version ?? DEFAULT_DEFINITION_VERSION,
         child: def.child,
         mapInput: def.mapInput,
     };
@@ -47,7 +65,17 @@ export function asAgentTool(def) {
         description: def.description ?? def.agent.instructions,
         input: def.input ?? def.agent.input,
         inputSchema: def.inputSchema ?? def.agent.inputSchema,
-        child: { kind: 'agent', name: def.agent.name },
+        child: { kind: 'agent', name: def.agent.name, version: def.agent.version },
+        mapInput: def.mapInput,
+    });
+}
+export function asEvaluatorTool(def) {
+    return asThreadTool({
+        name: def.name,
+        description: def.description ?? def.evaluator.description,
+        input: def.input ?? def.evaluator.input,
+        inputSchema: def.inputSchema ?? def.evaluator.inputSchema,
+        child: { kind: 'evaluator', name: def.evaluator.name },
         mapInput: def.mapInput,
     });
 }
@@ -57,7 +85,7 @@ export function asWorkflowTool(def) {
         description: def.description ?? def.workflow.description,
         input: def.input ?? def.workflow.input,
         inputSchema: def.inputSchema ?? def.workflow.inputSchema,
-        child: { kind: 'workflow', name: def.workflow.name },
+        child: { kind: 'workflow', name: def.workflow.name, version: def.workflow.version },
         mapInput: def.mapInput,
     });
 }