@swirls/looms 0.0.1

package/dist/agent/module.js

@@ -0,0 +1,27 @@
+import { Layer } from 'effect';
+import { defineModule } from '@swirls/looms/core';
+import { AgentDefinitionsLive } from './definitions-store.js';
+import { callLlmEffect, executeToolEffect } from './effects.js';
+import { llmFromAdapter, LlmTag, StubLlmLive } from './llm.js';
+import { conversation, tokenUsage } from './projections.js';
+import { agentModule } from './scope.js';
+import { agentThread } from './threads.js';
+export function agent(options = {}) {
+    const definitions = options.definitions ?? [];
+    const llmLayer = options.llm
+        ? Layer.succeed(LlmTag, llmFromAdapter(options.llm))
+        : StubLlmLive(options.llmPolicy);
+    return defineModule(agentModule, () => ({
+        definitions,
+        threads: { agent: agentThread },
+        effects: {
+            callLLM: callLlmEffect,
+            executeTool: executeToolEffect,
+        },
+        projections: {
+            conversation,
+            tokenUsage,
+        },
+        services: () => Layer.merge(llmLayer, AgentDefinitionsLive(definitions)),
+    }));
+}

package/dist/agent/projections.d.ts

@@ -0,0 +1,17 @@
+export declare const conversation: import("@swirls/looms/core").ProjectionDefinition<{
+    readonly lines: {
+        readonly role: "assistant" | "system" | "tool" | "user";
+        readonly content: string;
+        readonly toolCallId?: string | undefined;
+        readonly name?: string | undefined;
+        readonly toolCalls?: {
+            readonly id: string;
+            readonly name: string;
+            readonly arguments: import("effect/Schema").Json;
+        }[] | undefined;
+    }[];
+}>;
+export declare const tokenUsage: import("@swirls/looms/core").ProjectionDefinition<{
+    readonly input: number;
+    readonly output: number;
+}>;

package/dist/agent/projections.js

@@ -0,0 +1,81 @@
+import { Predicate } from 'effect';
+import { agentModule } from './scope.js';
+import { ConversationSchema, TokenUsageSchema } from './types.js';
+export const conversation = agentModule.projection({
+    name: 'conversation',
+    shape: ConversationSchema,
+    initialState: { lines: [] },
+    reduce(state, event) {
+        switch (event.type) {
+            case 'agent.message.received':
+            case 'agent.message':
+            case 'agent.steered': {
+                const raw = event.payload.message;
+                if (!raw) {
+                    return state;
+                }
+                const role = raw.role === 'system' || raw.role === 'assistant' || raw.role === 'tool'
+                    ? raw.role
+                    : 'user';
+                let toolCalls;
+                const calls = raw.toolCalls;
+                if (Array.isArray(calls)) {
+                    const collected = [];
+                    for (const item of calls) {
+                        if (!Predicate.isObject(item) ||
+                            !Predicate.isString(item.id) ||
+                            !Predicate.isString(item.name)) {
+                            continue;
+                        }
+                        collected.push({ id: item.id, name: item.name, arguments: item.arguments ?? null });
+                    }
+                    if (collected.length > 0) {
+                        toolCalls = collected;
+                    }
+                }
+                const line = {
+                    role,
+                    content: Predicate.isString(raw.content) ? raw.content : '',
+                    toolCallId: raw.toolCallId ?? undefined,
+                    name: raw.name ?? undefined,
+                    toolCalls,
+                };
+                return { lines: [...state.lines, line] };
+            }
+            case 'agent.tool.result': {
+                const { error, result, toolCallId, name } = event.payload;
+                const content = Predicate.isString(error) && error.length > 0 ? error : JSON.stringify(result ?? null);
+                const toolLine = {
+                    role: 'tool',
+                    content,
+                    toolCallId: toolCallId ?? undefined,
+                    name: name ?? undefined,
+                    toolCalls: undefined,
+                };
+                return {
+                    lines: [...state.lines, toolLine],
+                };
+            }
+            default:
+                return state;
+        }
+    },
+});
+export const tokenUsage = agentModule.projection({
+    name: 'tokenUsage',
+    shape: TokenUsageSchema,
+    initialState: { input: 0, output: 0 },
+    reduce(state, event) {
+        if (event.type !== 'agent.message') {
+            return state;
+        }
+        const usage = event.payload.usage;
+        if (!usage) {
+            return state;
+        }
+        return {
+            input: state.input + (Predicate.isNumber(usage.input) ? usage.input : 0),
+            output: state.output + (Predicate.isNumber(usage.output) ? usage.output : 0),
+        };
+    },
+});

package/dist/agent/scope.d.ts

@@ -0,0 +1,171 @@
+import { type EventOf } from '@swirls/looms/core';
+export declare const agentModule: import("@swirls/looms/core").ModuleScope<"agent", import("@swirls/looms/core").ScopeUniverse<import("@swirls/looms/core").EventCatalog<"agent", {
+    'message.received': import("effect/Schema").Struct<{
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+    }>;
+    'turn.started': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+    }>;
+    'turn.text_delta': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly delta: import("effect/Schema").String;
+    }>;
+    message: import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+        readonly usage: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            readonly input: import("effect/Schema").Number;
+            readonly output: import("effect/Schema").Number;
+        }>>;
+    }>;
+    'tool_call.requested': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly toolCall: import("effect/Schema").Struct<{
+            readonly id: import("effect/Schema").String;
+            readonly name: import("effect/Schema").String;
+            readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+        }>;
+    }>;
+    'tool.result': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly toolCallId: import("effect/Schema").String;
+        readonly name: import("effect/Schema").String;
+        readonly result: import("effect/Schema").NullOr<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>;
+        readonly error: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    }>;
+    steered: import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+        readonly interrupt: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+    }>;
+    'spawn.requested': import("effect/Schema").Struct<{
+        readonly childThreadId: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").String;
+        readonly definitionName: import("effect/Schema").String;
+        readonly toolCallId: import("effect/Schema").String;
+        readonly input: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+    }>;
+    'effects.requested': import("effect/Schema").Struct<{
+        readonly toolCallId: import("effect/Schema").String;
+        readonly effects: import("effect/Schema").$Array<import("effect/Schema").Schema<import("@swirls/looms/core").RuntimeEffect>>;
+        readonly waitOn: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").$Array<import("effect/Schema").String>]>;
+            readonly match: import("effect/Schema").optional<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>;
+        }>>;
+    }>;
+}>, undefined>, import("@swirls/looms/core").EventCatalog<"agent", {
+    'message.received': import("effect/Schema").Struct<{
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+    }>;
+    'turn.started': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+    }>;
+    'turn.text_delta': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly delta: import("effect/Schema").String;
+    }>;
+    message: import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+        readonly usage: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            readonly input: import("effect/Schema").Number;
+            readonly output: import("effect/Schema").Number;
+        }>>;
+    }>;
+    'tool_call.requested': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly toolCall: import("effect/Schema").Struct<{
+            readonly id: import("effect/Schema").String;
+            readonly name: import("effect/Schema").String;
+            readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+        }>;
+    }>;
+    'tool.result': import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly toolCallId: import("effect/Schema").String;
+        readonly name: import("effect/Schema").String;
+        readonly result: import("effect/Schema").NullOr<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>;
+        readonly error: import("effect/Schema").NullOr<import("effect/Schema").String>;
+    }>;
+    steered: import("effect/Schema").Struct<{
+        readonly turn: import("effect/Schema").Number;
+        readonly message: import("effect/Schema").Struct<{
+            readonly role: import("effect/Schema").Union<readonly [import("effect/Schema").Literal<"system">, import("effect/Schema").Literal<"user">, import("effect/Schema").Literal<"assistant">, import("effect/Schema").Literal<"tool">]>;
+            readonly content: import("effect/Schema").String;
+            readonly toolCallId: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly name: import("effect/Schema").optional<import("effect/Schema").String>;
+            readonly toolCalls: import("effect/Schema").optional<import("effect/Schema").mutable<import("effect/Schema").$Array<import("effect/Schema").Struct<{
+                readonly id: import("effect/Schema").String;
+                readonly name: import("effect/Schema").String;
+                readonly arguments: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+            }>>>>;
+        }>;
+        readonly interrupt: import("effect/Schema").optional<import("effect/Schema").Boolean>;
+    }>;
+    'spawn.requested': import("effect/Schema").Struct<{
+        readonly childThreadId: import("effect/Schema").String;
+        readonly kind: import("effect/Schema").String;
+        readonly definitionName: import("effect/Schema").String;
+        readonly toolCallId: import("effect/Schema").String;
+        readonly input: import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>;
+    }>;
+    'effects.requested': import("effect/Schema").Struct<{
+        readonly toolCallId: import("effect/Schema").String;
+        readonly effects: import("effect/Schema").$Array<import("effect/Schema").Schema<import("@swirls/looms/core").RuntimeEffect>>;
+        readonly waitOn: import("effect/Schema").optional<import("effect/Schema").Struct<{
+            readonly type: import("effect/Schema").Union<readonly [import("effect/Schema").String, import("effect/Schema").$Array<import("effect/Schema").String>]>;
+            readonly match: import("effect/Schema").optional<import("effect/Schema").Codec<import("effect/Schema").Json, import("effect/Schema").Json, never, never>>;
+        }>>;
+    }>;
+}>, undefined>;
+export type AgentEvent = EventOf<typeof agentModule>;

package/dist/agent/scope.js

@@ -0,0 +1,7 @@
+import { createModuleScope } from '@swirls/looms/core';
+import { agentCatalog } from './events.js';
+export const agentModule = createModuleScope({
+    namespace: 'agent',
+    protocolVersion: '1.0.0',
+    events: agentCatalog,
+});

package/dist/agent/signals.d.ts

@@ -0,0 +1,17 @@
+import type { EventInput } from '@swirls/looms/core';
+export interface AgentSignalOptions {
+    /** Target thread. Defaults to the run's root thread when omitted. */
+    readonly threadId?: string;
+}
+/**
+ * Build the `agent.message.received` event for a conversational agent.
+ * Send it with `looms.signal(runId, [userMessage('Also greet Maya')])`.
+ */
+export declare function userMessage(content: string, options?: AgentSignalOptions): EventInput;
+/**
+ * Build the `agent.steered` event: inject a user message mid-run, optionally
+ * interrupting the current turn so the agent replans immediately.
+ */
+export declare function steer(content: string, options?: AgentSignalOptions & {
+    readonly interrupt?: boolean;
+}): EventInput;

package/dist/agent/signals.js

@@ -0,0 +1,19 @@
+import { agentModule } from './scope.js';
+/**
+ * Build the `agent.message.received` event for a conversational agent.
+ * Send it with `looms.signal(runId, [userMessage('Also greet Maya')])`.
+ */
+export function userMessage(content, options = {}) {
+    return agentModule.input('message.received', { message: { role: 'user', content } }, { threadId: options.threadId });
+}
+/**
+ * Build the `agent.steered` event: inject a user message mid-run, optionally
+ * interrupting the current turn so the agent replans immediately.
+ */
+export function steer(content, options = {}) {
+    return agentModule.input('steered', {
+        turn: 0,
+        interrupt: options.interrupt ?? true,
+        message: { role: 'user', content },
+    }, { threadId: options.threadId });
+}

package/dist/agent/stop-when.d.ts

@@ -0,0 +1,12 @@
+import type { AgentTurnResult } from './definitions';
+import type { Message, ToolCall } from './types';
+export interface StopWhenContext {
+    readonly turn: number;
+    readonly maxTurns: number;
+    readonly messages: Message[];
+    readonly toolCalls: ToolCall[];
+    readonly result: AgentTurnResult;
+}
+export type StopWhen = (ctx: StopWhenContext) => boolean;
+export declare function hasToolCall(name: string): StopWhen;
+export declare function stepCountIs(n: number): StopWhen;

package/dist/agent/stop-when.js

@@ -0,0 +1,6 @@
+export function hasToolCall(name) {
+    return (ctx) => ctx.toolCalls.some((toolCall) => toolCall.name === name);
+}
+export function stepCountIs(n) {
+    return (ctx) => ctx.turn >= n;
+}

package/dist/agent/threads.d.ts

@@ -0,0 +1,34 @@
+import { type EventEnvelope, type JsonValue, type RuntimeEffect } from '@swirls/looms/core';
+import { type Message, type ToolCall } from './types';
+export declare const agentThread: import("@swirls/looms/core").ThreadDefinition<{
+    definitionName?: string;
+    lines: Message[];
+    pendingToolCalls: ToolCall[];
+    executingToolCalls: ToolCall[];
+    needsLlmCall: boolean;
+    turn: number;
+    maxTurns: number;
+    pendingSteer: Message | null;
+    input: JsonValue;
+    output: JsonValue | null;
+    pendingEffectTools: {
+        [causingSeq: string]: import("./types").PendingEffectTool;
+    };
+    pendingSpawns: import("./types").AgentPendingSpawn[];
+    pendingEffects: import("./types").AgentPendingEffects[];
+    pendingEmits: (import("./types").AgentPendingEmit | {
+        id: string;
+        event: {
+            type: string;
+            payload: {
+                turn: number;
+                toolCallId: string;
+                name: string;
+                result: string | number | boolean | import("effect/Schema").JsonArray | import("effect/Schema").JsonObject | null;
+                error: string | null;
+            };
+            threadId: string;
+        };
+    })[];
+}>;
+export declare function satisfiedToToolResult(event: EventEnvelope): RuntimeEffect | null;