@swirls/looms 0.0.1

package/dist/agent/threads.js

@@ -0,0 +1,407 @@
+import { Predicate } from 'effect';
+import { createWaitId, emit, invoke, isWithdrawnError, parseEffectId, spawn, wait, } from '@swirls/looms/core';
+import { callLlmEffect, executeToolEffect } from './effects.js';
+import { agentModule } from './scope.js';
+import { AgentStateSchema } from './types.js';
+function inputToLine(input) {
+    if (input === null) {
+        return null;
+    }
+    if (Predicate.isString(input)) {
+        return { role: 'user', content: input };
+    }
+    if (Predicate.isObject(input)) {
+        if (Predicate.isString(input.text)) {
+            return { role: 'user', content: input.text };
+        }
+        if (Predicate.isString(input.task)) {
+            return { role: 'user', content: input.task };
+        }
+        if (Predicate.isString(input.topic)) {
+            return { role: 'user', content: input.topic };
+        }
+        if (Predicate.isString(input.prompt)) {
+            return { role: 'user', content: input.prompt };
+        }
+    }
+    return { role: 'user', content: JSON.stringify(input) };
+}
+function attachToolCall(lines, toolCall) {
+    for (let index = lines.length - 1; index >= 0; index -= 1) {
+        const line = lines[index];
+        if (line?.role !== 'assistant') {
+            continue;
+        }
+        const existing = line.toolCalls ?? [];
+        if (existing.some((item) => item.id === toolCall.id)) {
+            return [...lines];
+        }
+        const next = [...lines];
+        next[index] = { ...line, toolCalls: [...existing, toolCall] };
+        return next;
+    }
+    return [...lines];
+}
+export const agentThread = agentModule.thread({
+    kind: 'agent',
+    shape: AgentStateSchema,
+    initialState: (ctx) => ({
+        definitionName: ctx.definitionName,
+        lines: [],
+        pendingToolCalls: [],
+        executingToolCalls: [],
+        pendingSpawns: [],
+        pendingEffects: [],
+        pendingEmits: [],
+        needsLlmCall: false,
+        turn: 0,
+        maxTurns: 20,
+        pendingSteer: null,
+        input: ctx.input,
+        output: null,
+        pendingEffectTools: {},
+    }),
+    step(state, event, ctx) {
+        switch (event.type) {
+            case 'runtime.thread.started': {
+                const payload = event.payload;
+                const defName = payload.definitionName || state.definitionName;
+                // SAFETY: event payload input is JSON
+                const input = payload.input !== undefined ? payload.input : state.input;
+                const line = inputToLine(input);
+                const lines = line ? [line] : state.lines;
+                return {
+                    ...state,
+                    definitionName: defName,
+                    input,
+                    lines,
+                    needsLlmCall: true,
+                };
+            }
+            case 'agent.turn.started': {
+                return {
+                    ...state,
+                    turn: event.payload.turn,
+                    needsLlmCall: false,
+                    pendingSteer: null,
+                };
+            }
+            case 'agent.message.received': {
+                const message = event.payload.message;
+                const lines = [...state.lines, message];
+                const needsLlmCall = state.pendingToolCalls.length === 0;
+                return {
+                    ...state,
+                    lines,
+                    needsLlmCall,
+                };
+            }
+            case 'agent.message': {
+                return { ...state, lines: [...state.lines, event.payload.message] };
+            }
+            case 'agent.tool_call.requested': {
+                const { toolCall } = event.payload;
+                return {
+                    ...state,
+                    lines: attachToolCall(state.lines, toolCall),
+                    pendingToolCalls: [...state.pendingToolCalls, toolCall],
+                    executingToolCalls: [...state.executingToolCalls, toolCall],
+                    needsLlmCall: false,
+                };
+            }
+            case 'agent.tool.result': {
+                const { toolCallId, name, result, error } = event.payload;
+                const pendingToolCalls = state.pendingToolCalls.filter((item) => item.id !== toolCallId);
+                const executingToolCalls = state.executingToolCalls.filter((item) => item.id !== toolCallId);
+                const pendingSpawns = state.pendingSpawns.filter((item) => item.toolCallId !== toolCallId);
+                const pendingEffects = state.pendingEffects.filter((item) => item.toolCallId !== toolCallId);
+                const pendingEmits = state.pendingEmits.filter((item) => item.id !== `res_${toolCallId}`);
+                const content = Predicate.isString(error) && error.length > 0 ? error : JSON.stringify(result ?? null);
+                const lines = [
+                    ...state.lines,
+                    {
+                        role: 'tool',
+                        content,
+                        toolCallId,
+                        name: name ?? undefined,
+                    },
+                ];
+                const needsLlmCall = pendingToolCalls.length === 0;
+                return {
+                    ...state,
+                    lines,
+                    pendingToolCalls,
+                    executingToolCalls,
+                    pendingSpawns,
+                    pendingEffects,
+                    pendingEmits,
+                    needsLlmCall,
+                };
+            }
+            case 'agent.steered': {
+                const message = event.payload.message;
+                const interrupt = event.payload.interrupt ?? false;
+                if (interrupt) {
+                    return {
+                        ...state,
+                        lines: [...state.lines, message],
+                        pendingSteer: message,
+                        pendingToolCalls: [],
+                        executingToolCalls: [],
+                        pendingSpawns: [],
+                        pendingEffects: [],
+                        pendingEmits: [],
+                        needsLlmCall: true,
+                    };
+                }
+                return {
+                    ...state,
+                    lines: [...state.lines, message],
+                    pendingSteer: message,
+                };
+            }
+            case 'agent.spawn.requested': {
+                const { childThreadId, kind, definitionName, toolCallId, input } = event.payload;
+                return {
+                    ...state,
+                    executingToolCalls: state.executingToolCalls.filter((item) => item.id !== toolCallId),
+                    pendingSpawns: [
+                        ...state.pendingSpawns.filter((item) => item.toolCallId !== toolCallId),
+                        {
+                            childThreadId,
+                            kind,
+                            definitionName,
+                            toolCallId,
+                            // SAFETY: schema-decoded input is JSON
+                            input: input ?? null,
+                        },
+                    ],
+                };
+            }
+            case 'agent.effects.requested': {
+                const { toolCallId, effects: rawEffects, waitOn } = event.payload;
+                // SAFETY: handler serialized RuntimeEffect values into the event payload.
+                const effects = Array.isArray(rawEffects)
+                    ? [...rawEffects]
+                    : [];
+                const taggedEffects = effects.map((effect, idx) => {
+                    if (!('tag' in effect && Predicate.isString(effect.tag))) {
+                        return { ...effect, tag: `${toolCallId}_${effect.type}_${idx}` };
+                    }
+                    return effect;
+                });
+                const pending = state.executingToolCalls.find((item) => item.id === toolCallId);
+                const effectToolEntries = [
+                    [String(event.seq), { toolCallId, name: pending?.name ?? 'tool' }],
+                    [toolCallId, { toolCallId, name: pending?.name ?? 'tool' }],
+                ];
+                for (const eff of taggedEffects) {
+                    if ('tag' in eff && Predicate.isString(eff.tag)) {
+                        effectToolEntries.push([eff.tag, { toolCallId, name: pending?.name ?? 'tool' }]);
+                    }
+                }
+                return {
+                    ...state,
+                    executingToolCalls: state.executingToolCalls.filter((item) => item.id !== toolCallId),
+                    pendingEffects: [
+                        ...state.pendingEffects.filter((item) => item.toolCallId !== toolCallId),
+                        {
+                            toolCallId,
+                            effects: taggedEffects,
+                            waitOn: waitOn
+                                ? {
+                                    type: waitOn.type,
+                                    // SAFETY: schema-decoded match is JSON
+                                    match: waitOn.match ?? undefined,
+                                }
+                                : undefined,
+                        },
+                    ],
+                    pendingEffectTools: {
+                        ...state.pendingEffectTools,
+                        ...Object.fromEntries(effectToolEntries),
+                    },
+                };
+            }
+            case 'runtime.effect.failed': {
+                const payload = event.payload;
+                const error = payload.error || 'effect failed';
+                if (isWithdrawnError(error)) {
+                    return state;
+                }
+                const parsed = event.effectId ? parseEffectId(event.effectId) : null;
+                const tag = parsed?.tag;
+                const causingKey = parsed?.causingSeq !== undefined ? String(parsed.causingSeq) : '';
+                const pending = (tag ? state.pendingEffectTools?.[tag] : undefined) ??
+                    (causingKey ? state.pendingEffectTools?.[causingKey] : undefined) ??
+                    (() => {
+                        const match = state.pendingEffects.find((item) => item.effects.some((e) => 'tag' in e && e.tag === tag) ||
+                            (tag !== undefined && tag.startsWith(item.toolCallId)));
+                        return match ? { toolCallId: match.toolCallId, name: 'tool' } : undefined;
+                    })();
+                if (!pending) {
+                    return state;
+                }
+                const rest = {};
+                for (const [key, val] of Object.entries(state.pendingEffectTools ?? {})) {
+                    if (val.toolCallId !== pending.toolCallId) {
+                        rest[key] = val;
+                    }
+                }
+                return {
+                    ...state,
+                    pendingEffectTools: rest,
+                    pendingEffects: state.pendingEffects.filter((item) => item.toolCallId !== pending.toolCallId),
+                    pendingEmits: [
+                        ...state.pendingEmits.filter((item) => item.id !== `res_${pending.toolCallId}`),
+                        {
+                            id: `res_${pending.toolCallId}`,
+                            event: {
+                                type: 'agent.tool.result',
+                                payload: {
+                                    turn: state.turn,
+                                    toolCallId: pending.toolCallId,
+                                    name: pending.name,
+                                    result: null,
+                                    error,
+                                },
+                                threadId: ctx.threadId,
+                            },
+                        },
+                    ],
+                };
+            }
+            case 'runtime.wait.satisfied': {
+                if (!Predicate.isObject(event.payload)) {
+                    return state;
+                }
+                const tag = event.payload.tag;
+                if (!Predicate.isObject(tag)) {
+                    return state;
+                }
+                const toolCallId = Predicate.isString(tag.toolCallId) ? tag.toolCallId : undefined;
+                if (!toolCallId) {
+                    return state;
+                }
+                const embedded = event.payload.event;
+                const embeddedObj = Predicate.isObject(embedded) && Predicate.isObject(embedded.payload)
+                    ? embedded.payload
+                    : {};
+                const threadId = ctx.threadId;
+                const name = Predicate.isString(tag.name) ? tag.name : 'child';
+                const error = Predicate.isString(embeddedObj.error) ? embeddedObj.error : null;
+                // SAFETY: embedded output/payload is JSON
+                const result = embeddedObj.output ??
+                    (Predicate.isObject(embedded) ? embedded.payload : null) ??
+                    null;
+                return {
+                    ...state,
+                    pendingSpawns: state.pendingSpawns.filter((item) => item.toolCallId !== toolCallId),
+                    pendingEffects: state.pendingEffects.filter((item) => item.toolCallId !== toolCallId),
+                    pendingEmits: [
+                        ...state.pendingEmits.filter((item) => item.id !== `res_${toolCallId}`),
+                        {
+                            id: `res_${toolCallId}`,
+                            event: {
+                                type: 'agent.tool.result',
+                                payload: {
+                                    turn: state.turn,
+                                    toolCallId,
+                                    name,
+                                    result,
+                                    error,
+                                },
+                                threadId,
+                            },
+                        },
+                    ],
+                };
+            }
+            default:
+                return state;
+        }
+    },
+    effects(state, ctx) {
+        const effects = [];
+        if (state.needsLlmCall) {
+            effects.push(invoke(callLlmEffect, {
+                turn: state.turn + 1,
+                definitionName: state.definitionName,
+                messages: state.lines,
+                input: state.input,
+            }, `llm_turn_${state.turn + 1}`));
+        }
+        for (const toolCall of state.executingToolCalls) {
+            effects.push(invoke(executeToolEffect, {
+                turn: state.turn,
+                definitionName: state.definitionName,
+                toolCall,
+            }, `tool_${toolCall.id}`));
+        }
+        for (const spawnReq of state.pendingSpawns) {
+            const waitId = createWaitId(ctx.threadId, `spawn_${spawnReq.childThreadId}`);
+            effects.push(spawn({
+                childThreadId: spawnReq.childThreadId,
+                kind: spawnReq.kind,
+                definitionName: spawnReq.definitionName,
+                input: spawnReq.input,
+            }), wait({
+                waitId,
+                on: {
+                    type: ['runtime.thread.completed', 'runtime.thread.failed'],
+                    match: { threadId: spawnReq.childThreadId },
+                },
+                tag: { toolCallId: spawnReq.toolCallId, name: spawnReq.definitionName },
+            }));
+        }
+        for (const effectReq of state.pendingEffects) {
+            for (const eff of effectReq.effects) {
+                effects.push(eff);
+            }
+            if (effectReq.waitOn) {
+                effects.push(wait({
+                    waitId: createWaitId(ctx.threadId, `effects_${effectReq.toolCallId}`),
+                    on: { type: effectReq.waitOn.type, match: effectReq.waitOn.match },
+                    tag: { toolCallId: effectReq.toolCallId },
+                }));
+            }
+        }
+        for (const emitReq of state.pendingEmits) {
+            effects.push(emit(emitReq.event));
+        }
+        return effects;
+    },
+});
+export function satisfiedToToolResult(event) {
+    if (!Predicate.isObject(event.payload)) {
+        return null;
+    }
+    const tag = event.payload.tag;
+    if (!Predicate.isObject(tag)) {
+        return null;
+    }
+    const toolCallId = Predicate.isString(tag.toolCallId) ? tag.toolCallId : undefined;
+    if (!toolCallId) {
+        return null;
+    }
+    const embedded = event.payload.event;
+    const embeddedPayload = Predicate.isObject(embedded) && Predicate.isObject(embedded.payload) ? embedded.payload : {};
+    const threadId = event.threadId ?? null;
+    const name = Predicate.isString(tag.name) ? tag.name : 'child';
+    const error = Predicate.isString(embeddedPayload.error) ? embeddedPayload.error : null;
+    // SAFETY: embedded output/payload is JSON
+    const result = embeddedPayload.output ??
+        (Predicate.isObject(embedded) ? embedded.payload : null) ??
+        null;
+    return emit({
+        type: 'agent.tool.result',
+        payload: {
+            turn: 0,
+            toolCallId,
+            name,
+            result,
+            error,
+        },
+        threadId,
+    });
+}

package/dist/agent/tool-schema.d.ts

@@ -0,0 +1,21 @@
+import { Schema } from 'effect';
+import type { JsonValue, SchemaInput } from '@swirls/looms/core';
+import { type AgentToolEntry, type ToolLike } from './definitions';
+import type { LlmToolSpec } from './llm';
+interface StandardJsonSchemaConverter {
+    readonly input: (options: {
+        target: string;
+    }) => JsonValue;
+}
+interface StandardJsonSchemaHolder {
+    readonly '~standard': {
+        readonly jsonSchema?: {
+            readonly input?: StandardJsonSchemaConverter['input'];
+        };
+    };
+}
+type SchemaCandidate = SchemaInput | StandardJsonSchemaHolder | Schema.Codec<JsonValue>;
+export declare function toolJsonSchema(tool: ToolLike): JsonValue;
+export declare function toolSpecs(tools?: ReadonlyArray<AgentToolEntry>): LlmToolSpec[];
+export declare function jsonSchemaFromStandard(schema: SchemaCandidate | null | undefined): JsonValue;
+export {};

package/dist/agent/tool-schema.js

@@ -0,0 +1,67 @@
+import { Schema } from 'effect';
+import { normalizeTools } from './definitions.js';
+const EMPTY_OBJECT_SCHEMA = { type: 'object' };
+function isStandardJsonSchemaHolder(value) {
+    return '~standard' in value;
+}
+function fromStandardJsonSchema(schema) {
+    if (!isStandardJsonSchemaHolder(schema)) {
+        return undefined;
+    }
+    const input = schema['~standard'].jsonSchema?.input;
+    if (!input) {
+        return undefined;
+    }
+    try {
+        return input({ target: 'draft-2020-12' });
+    }
+    catch {
+        return undefined;
+    }
+}
+function fromEffectSchema(schema) {
+    if (!Schema.isSchema(schema)) {
+        return undefined;
+    }
+    try {
+        // SAFETY: Effect Schema values used as tool input codecs produce Standard JSON Schema.
+        const standard = Schema.toStandardJSONSchemaV1(schema);
+        return fromStandardJsonSchema(standard);
+    }
+    catch {
+        return undefined;
+    }
+}
+function fromInputCandidate(input) {
+    if (!input) {
+        return undefined;
+    }
+    return fromStandardJsonSchema(input) ?? fromEffectSchema(input);
+}
+function toolInputCandidate(tool) {
+    switch (tool.kind) {
+        case 'function':
+            return tool.input;
+        case 'thread':
+            return tool.input;
+        case 'effects':
+            return tool.input;
+        default: {
+            const exhaustiveCheck = tool;
+            return exhaustiveCheck;
+        }
+    }
+}
+export function toolJsonSchema(tool) {
+    return tool.inputSchema ?? fromInputCandidate(toolInputCandidate(tool)) ?? EMPTY_OBJECT_SCHEMA;
+}
+export function toolSpecs(tools = []) {
+    return normalizeTools(tools).map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputJsonSchema: toolJsonSchema(tool),
+    }));
+}
+export function jsonSchemaFromStandard(schema) {
+    return fromInputCandidate(schema ?? undefined) ?? EMPTY_OBJECT_SCHEMA;
+}

package/dist/agent/types.d.ts

@@ -0,0 +1,87 @@
+import { Schema } from 'effect';
+import type { EventInput, JsonValue, RuntimeEffect } from '@swirls/looms/core';
+export declare const ToolCallSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly name: Schema.String;
+    readonly arguments: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>;
+export type ToolCall = Schema.Schema.Type<typeof ToolCallSchema>;
+export declare const MessageRoleSchema: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
+export type MessageRole = Schema.Schema.Type<typeof MessageRoleSchema>;
+export declare const MessageSchema: Schema.Struct<{
+    readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
+    readonly content: Schema.String;
+    readonly toolCallId: Schema.optional<Schema.String>;
+    readonly name: Schema.optional<Schema.String>;
+    readonly toolCalls: Schema.optional<Schema.mutable<Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+        readonly arguments: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>>>;
+}>;
+export type Message = Schema.Schema.Type<typeof MessageSchema>;
+export declare const ConversationSchema: Schema.Struct<{
+    readonly lines: Schema.mutable<Schema.$Array<Schema.Struct<{
+        readonly role: Schema.Union<readonly [Schema.Literal<"system">, Schema.Literal<"user">, Schema.Literal<"assistant">, Schema.Literal<"tool">]>;
+        readonly content: Schema.String;
+        readonly toolCallId: Schema.optional<Schema.String>;
+        readonly name: Schema.optional<Schema.String>;
+        readonly toolCalls: Schema.optional<Schema.mutable<Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly name: Schema.String;
+            readonly arguments: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+        }>>>>;
+    }>>>;
+}>;
+export type ConversationState = Schema.Schema.Type<typeof ConversationSchema>;
+export declare const TokenUsageSchema: Schema.Struct<{
+    readonly input: Schema.Number;
+    readonly output: Schema.Number;
+}>;
+export type TokenUsage = Schema.Schema.Type<typeof TokenUsageSchema>;
+export declare const ThreadStartedPayloadSchema: Schema.Struct<{
+    readonly definitionName: Schema.optional<Schema.String>;
+    readonly input: Schema.optional<Schema.Unknown>;
+}>;
+export interface PendingEffectTool {
+    toolCallId: string;
+    name: string;
+}
+export interface AgentPendingSpawn {
+    readonly childThreadId: string;
+    readonly kind: string;
+    readonly definitionName: string;
+    readonly toolCallId: string;
+    readonly input: JsonValue;
+}
+export interface AgentPendingEffects {
+    readonly toolCallId: string;
+    readonly effects: RuntimeEffect[];
+    readonly waitOn?: {
+        type: string | readonly string[];
+        match?: JsonValue;
+    };
+}
+export interface AgentPendingEmit {
+    readonly id: string;
+    readonly event: EventInput;
+}
+export interface AgentState {
+    definitionName?: string;
+    lines: Message[];
+    pendingToolCalls: ToolCall[];
+    executingToolCalls: ToolCall[];
+    pendingSpawns: AgentPendingSpawn[];
+    pendingEffects: AgentPendingEffects[];
+    pendingEmits: AgentPendingEmit[];
+    needsLlmCall: boolean;
+    turn: number;
+    maxTurns: number;
+    pendingSteer: Message | null;
+    input: JsonValue;
+    output: JsonValue | null;
+    pendingEffectTools: {
+        [causingSeq: string]: PendingEffectTool;
+    };
+}
+export declare const AgentStateSchema: Schema.Schema<AgentState>;

package/dist/agent/types.js

@@ -0,0 +1,32 @@
+import { Schema } from 'effect';
+export const ToolCallSchema = Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    arguments: Schema.Json,
+});
+export const MessageRoleSchema = Schema.Union([
+    Schema.Literal('system'),
+    Schema.Literal('user'),
+    Schema.Literal('assistant'),
+    Schema.Literal('tool'),
+]);
+export const MessageSchema = Schema.Struct({
+    role: MessageRoleSchema,
+    content: Schema.String,
+    toolCallId: Schema.optional(Schema.String),
+    name: Schema.optional(Schema.String),
+    toolCalls: Schema.optional(Schema.mutable(Schema.Array(ToolCallSchema))),
+});
+export const ConversationSchema = Schema.Struct({
+    lines: Schema.mutable(Schema.Array(MessageSchema)),
+});
+export const TokenUsageSchema = Schema.Struct({
+    input: Schema.Number,
+    output: Schema.Number,
+});
+export const ThreadStartedPayloadSchema = Schema.Struct({
+    definitionName: Schema.optional(Schema.String),
+    input: Schema.optional(Schema.Unknown),
+});
+// SAFETY: AgentState is folded by reducers; Schema.Unknown is a typed placeholder, not a decoder.
+export const AgentStateSchema = Schema.Unknown;

package/dist/ai-vercel/index.d.ts

@@ -0,0 +1,2 @@
+export { vercelLlm, type VercelLlmOptions } from './vercel-llm';
+export { toLoomsToolCalls, toModelMessages } from './messages';

package/dist/ai-vercel/index.js

@@ -0,0 +1,2 @@
+export { vercelLlm } from './vercel-llm.js';
+export { toLoomsToolCalls, toModelMessages } from './messages.js';

package/dist/ai-vercel/messages.d.ts

@@ -0,0 +1,9 @@
+import { type ModelMessage } from 'ai';
+import type { Message, ToolCall } from '@swirls/looms/agent';
+import type { JsonValue } from '@swirls/looms/core';
+export declare function toModelMessages(messages: Message[]): ModelMessage[];
+export declare function toLoomsToolCalls(calls: ReadonlyArray<{
+    toolCallId: string;
+    toolName: string;
+    input: JsonValue;
+}>): ToolCall[];