@swirls/looms 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @swirls/looms
 
+## 0.3.0
+
+### Minor Changes
+
+- 331ff55: `stopAgentTurn()` builds an `agent.turn.stopped` signal that ends the turn in progress without ending the run. A conversational agent aborts its in-flight model call or tool, cancels child threads its tool calls started, answers open tool calls with a stopped result, and waits for the next message. An agent session cancels its active turn and stays open. The debugger chat shows a Stop button while a turn is running.
+
+  An interrupting `steer` now ends the turn the same way before it starts the next one, so it no longer leaves tool calls unanswered or tool children running.
+
+  Cancelling a thread now cancels every live thread below it, and a signal interrupt also aborts in-flight work in the named thread's descendants.
+
+  The new `turnActivity` projection reports whether the root agent thread has a turn in progress.
+
+- 8da450e: `POST /runs/:id/cancel` and `client.cancel(runId, threadId?)` cancel a run or thread over HTTP. The debugger's Cancel button now uses it, so cancelling an in-flight agent turn stops the run instead of retrying the turn. Cancel stays available while a wake is running. `POST /runs/:id/wake` and `client.wake()` return `appended`, the number of events the run gained during the wake, and the debugger's Wake button reports it. Client run tables, the debugger, and projector indexes now mark a cancelled run as `cancelled` instead of `running`, and projector indexes mark a run that completed with an error as `failed` instead of `completed`. `RunRow.status` and `RunSummary.status` are typed as `RunStatus`, and `completedRunStatus()` reads the outcome of a `runtime.run.completed` payload.
+
+  Signals sent to a completed, failed, or cancelled run now reject with `RunTerminalError` (HTTP 409) instead of being appended and ignored. Retrying a signal whose `idempotencyKey` was already accepted still succeeds. `useRunSummary` exposes `finished`, and the debugger disables the agent follow-up composer and approval decisions on finished runs.
+
+- 6230fe1: `looms.fork(runId)`, `POST /runs/:id/fork`, and `client.fork()` start a new run that continues where a failed or cancelled run stopped. The fork copies the source's history up to the point it finished, keeping thread ids and sequence numbers, records `runtime.run.forked`, and re-issues the effects outstanding there. A cancelled agent re-runs the model call the cancel cut off; a failed run retries the effect whose failure ended it. Effects can declare `deterministic: true` so a fork retries the work behind them instead; workflow scheduling does. Forking a missing run rejects with `RunNotFoundError` (404 over HTTP). Actor and Durable Object hosts return 501. The debugger shows Continue on failed and cancelled runs, and `useRunSummary` reports `resumable` for them.
+
+  `runtime.thread.cancelled` records `resumeSeq` on the thread a cancel targeted: the run's last seq before the cancellation began.
+
+- 275e6a8: The projector index is keyed by run, so runs that share thread or approval ids stay apart. `getActor(runId, actorId?)` returns the run row by default or one of its threads, review rows carry `runId` instead of `actorId`, and the tables are now `looms_run_actors` and `looms_run_reviews`. The built-in index projectors moved to version 2, so delivery rebuilds them; the old `looms_actors` and `looms_reviews` tables are no longer written.
+
+## 0.2.0
+
+### Minor Changes
+
+- 6ed3a5f: `vercelEvaluator({ provider, model })` resolves model ids through an AI SDK provider such as `createTypeSafeAi({ apiKey })`, so callers can use their own TypeSafe key instead of the AI Gateway.
+- 6ed3a5f: Serve a debugger UI from `createLooms` with `debuggerUi()` from `@swirls/looms/debugger/server`. Modules ship their own debugger views from `@swirls/looms/agent/debugger`, `@swirls/looms/workflow/debugger`, and `@swirls/looms/approval/debugger`. `GET /definitions` lists the definitions and projections that UI can start and inspect, and `GET /runs/summaries` returns each run's status and definition.
+
+  `@swirls/looms/debugger` also exports the building blocks the hosted UI uses, so module views can match it: `JsonTree` (collapsible JSON that expands JSON held in strings), `FollowList` (a virtualized list that follows new items), `Composer`, `Button`, `Input`, `Textarea`, `Select`, `PanelHeader`, `PanelTitle`, `EmptyState`, `Kbd`, and `StatusBadge`. To render `DebuggerShell` in your own app, import `@swirls/looms/debugger/styles.css` after Tailwind CSS v4. The stylesheet brings its theme and scans the kit and the built-in module views.
+
+  Breaking changes:
+
+  - Tool helpers and tool definitions no longer accept `inputSchema`. Pass `input` and the JSON Schema is derived from it.
+  - `@swirls/looms/debugger` no longer exports `EventFamily`, `DEFAULT_FAMILIES`, `familyClass`, `familyFromPrefix`, `summarizeDomainEvent`, `summarizeEvent`, `searchText`, or `createDefaultCatalog`. Build a catalog with `createEventCatalog(plugins)` or use `defaultEventCatalog`.
+  - `EventStreamCatalog.familyClass` is now `familyColor`, which returns a CSS color, and `searchText` is required.
+
 ## 0.1.0
 
 ### Minor Changes

package/dist/actor/host.js

@@ -2,7 +2,7 @@ import { Data, Effect } from 'effect';
 import { EventStoreTag } from '@swirls/looms/core';
 import { createTimeoutScheduler, isLoomsApiPath } from '@swirls/looms/runtime';
 import { createActorCell } from './cell.js';
-import { resolveRunTarget, RunTargetError } from './routing.js';
+import { crossRunResponse, resolveRunTarget, RunTargetError } from './routing.js';
 class ActorWakeError extends Data.TaggedError('ActorWakeError') {
     constructor(cause) {
         super({
@@ -76,10 +76,9 @@ export function createLocalActorHost(options) {
             if (url.pathname === '/health') {
                 return Promise.resolve(Response.json({ ok: true }));
             }
-            if (req.method === 'GET' && url.pathname === '/runs') {
-                return Promise.resolve(Response.json({
-                    error: 'Global run listing is not supported in the actor host without a global index',
-                }, { status: 501 }));
+            const unsupported = crossRunResponse(req, 'the actor host');
+            if (unsupported) {
+                return Promise.resolve(unsupported);
             }
             return Effect.runPromise(Effect.gen(function* () {
                 const { runId, request } = yield* Effect.tryPromise({

package/dist/actor/index.d.ts

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

package/dist/actor/index.js

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

package/dist/actor/routing.d.ts

@@ -3,6 +3,11 @@
  * Inspects `x-looms-run-id` and `/runs/:runId/*`.
  */
 export declare function runIdFromRequest(req: Request): string | null;
+/**
+ * A 501 for requests that span runs, which a host with one cell per run cannot answer: listing
+ * runs needs a global index, and a fork writes a second run. `host` names the backend.
+ */
+export declare function crossRunResponse(req: Request, host: string): Response | null;
 export interface ResolvedRunTarget {
     readonly runId: string;
     readonly request: Request;

package/dist/actor/routing.js

@@ -22,6 +22,20 @@ export function runIdFromRequest(req) {
     }
     return null;
 }
+/**
+ * A 501 for requests that span runs, which a host with one cell per run cannot answer: listing
+ * runs needs a global index, and a fork writes a second run. `host` names the backend.
+ */
+export function crossRunResponse(req, host) {
+    const { pathname } = new URL(req.url);
+    if (req.method === 'GET' && (pathname === '/runs' || pathname === '/runs/summaries')) {
+        return Response.json({ error: `Global run listing is not supported in ${host} without a global index` }, { status: 501 });
+    }
+    if (req.method === 'POST' && /^\/runs\/[^/]+\/fork$/.test(pathname)) {
+        return Response.json({ error: `Forking runs is not supported in ${host}; each run lives in its own cell` }, { status: 501 });
+    }
+    return null;
+}
 export class RunTargetError extends Data.TaggedError('RunTargetError') {
     constructor(method, path) {
         super({

package/dist/agent/agent-session.js

@@ -140,6 +140,7 @@ export function createAgentSessionThread(definitions) {
                         pendingClosures: state.pendingClosures.filter((closure) => closure.messageId !== event.payload.messageId),
                     };
                 case 'agent.session.cancel.requested':
+                case 'agent.turn.stopped':
                 case 'runtime.thread.cancel.requested':
                     return state.activeTurn ? { ...state, cancelling: true } : state;
                 case 'runtime.wait.satisfied': {

package/dist/agent/debugger/agent-chat.d.ts

@@ -0,0 +1,2 @@
+import { type WorkspaceContext } from '@swirls/looms/debugger';
+export declare function AgentChat(context: WorkspaceContext): import("react").JSX.Element;

package/dist/agent/debugger/agent-chat.js

@@ -0,0 +1,210 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bot, CornerDownRight, GitFork, MessageSquare, Settings2, User, Wrench } from 'lucide-react';
+import { useMemo, useState } from 'react';
+import { createEventId, isJsonObject, isJsonString, } from '@swirls/looms/core';
+import { Button, cn, Composer, EmptyState, errorMessage, FollowList, inputForm, JsonTree, messageInput, parseStructuredJson, Select, SelectContent, SelectItem, SelectTrigger, SelectValue, shortId, useDebugger, useStartRun, } from '@swirls/looms/debugger';
+import { createFold, useEventFold, useProjection, useRunStore, useRunSummary } from '@swirls/looms/react';
+import { conversation, turnActivity } from '../projections.js';
+import { agentSessionMessageEvents, stopAgentTurn, userMessage } from '../signals.js';
+/** Child thread of the session turn that is still open, from the events the store already has. */
+function activeSessionChild(events) {
+    let child;
+    for (const event of events) {
+        if (!isJsonObject(event.payload)) {
+            continue;
+        }
+        if (event.type === 'agent.session.turn.started' && isJsonString(event.payload.childThreadId)) {
+            child = event.payload.childThreadId;
+            continue;
+        }
+        const tag = event.payload.tag;
+        if (event.type === 'runtime.wait.satisfied' &&
+            isJsonObject(tag) &&
+            tag.kind === 'agent-session-turn') {
+            child = undefined;
+        }
+    }
+    return child;
+}
+const streamingFold = createFold({
+    name: 'agentStreamingText',
+    initialState: { lastMessageSeq: -1, turnStarted: false, parts: [] },
+    includeEphemeral: true,
+    reduce(state, event) {
+        if (event.type === 'agent.message' ||
+            event.type === 'agent.turn.stopped' ||
+            event.type === 'runtime.thread.cancelled') {
+            return { lastMessageSeq: event.seq, turnStarted: false, parts: [] };
+        }
+        if (event.seq <= state.lastMessageSeq) {
+            return state;
+        }
+        if (event.type === 'agent.turn.started') {
+            return { ...state, turnStarted: true };
+        }
+        if (event.type === 'agent.turn.text_delta' &&
+            isJsonObject(event.payload) &&
+            isJsonString(event.payload.delta)) {
+            return {
+                ...state,
+                turnStarted: true,
+                parts: state.parts.concat(event.payload.delta),
+            };
+        }
+        return state;
+    },
+});
+const deliveryOptions = [
+    { value: 'followUp', label: 'Follow up', description: 'Queue after the current turn' },
+    { value: 'steer', label: 'Steer', description: 'Redirect the active turn' },
+    { value: 'nextTurn', label: 'Next turn', description: 'Hold until the next turn starts' },
+];
+function RoleLabel({ icon, children }) {
+    return (_jsxs("div", { className: "text-muted-foreground mb-1.5 flex items-center gap-1.5 text-[11px] font-medium [&_svg]:size-3", children: [icon, children] }));
+}
+function MessageText({ content, className }) {
+    const structured = useMemo(() => parseStructuredJson(content), [content]);
+    if (structured !== undefined) {
+        return _jsx(JsonTree, { value: structured, defaultExpandDepth: 2 });
+    }
+    return (_jsx("div", { className: cn('text-[13px] leading-relaxed break-words whitespace-pre-wrap', className), children: content }));
+}
+function ToolCard({ icon, name, meta, children, }) {
+    return (_jsxs("div", { className: "border-border bg-card/60 overflow-hidden rounded-lg border", children: [_jsxs("div", { className: "border-border/70 flex h-7 items-center gap-1.5 border-b px-2.5 text-[11px] [&_svg]:size-3", children: [_jsx("span", { className: "text-muted-foreground", children: icon }), _jsx("span", { className: "font-mono font-medium", children: name }), meta ? (_jsx("span", { className: "text-muted-foreground ml-auto truncate font-mono text-[10px]", children: meta })) : null] }), _jsx("div", { className: "px-2.5 py-1.5", children: children })] }));
+}
+function ToolCallCard({ call }) {
+    return (_jsx(ToolCard, { icon: _jsx(Wrench, {}), name: call.name, meta: shortId(call.id), children: _jsx(JsonTree, { value: call.arguments, defaultExpandDepth: 2 }) }));
+}
+function MessageItem({ line, toolName }) {
+    switch (line.role) {
+        case 'user':
+            return (_jsxs(_Fragment, { children: [_jsx(RoleLabel, { icon: _jsx(User, {}), children: "User" }), _jsx("div", { className: "bg-secondary w-fit max-w-full rounded-lg px-3 py-2", children: _jsx(MessageText, { content: line.content }) })] }));
+        case 'assistant':
+            return (_jsxs(_Fragment, { children: [_jsx(RoleLabel, { icon: _jsx(Bot, {}), children: "Assistant" }), _jsxs("div", { className: "grid gap-2", children: [line.content ? _jsx(MessageText, { content: line.content }) : null, line.toolCalls?.map((call) => (_jsx(ToolCallCard, { call: call }, call.id)))] })] }));
+        case 'tool':
+            return (_jsx(ToolCard, { icon: _jsx(CornerDownRight, {}), name: `${line.name ?? toolName ?? 'tool'} result`, meta: line.toolCallId ? shortId(line.toolCallId) : undefined, children: _jsx(MessageText, { content: line.content }) }));
+        case 'system':
+            return (_jsxs(_Fragment, { children: [_jsx(RoleLabel, { icon: _jsx(Settings2, {}), children: "System" }), _jsx(MessageText, { content: line.content, className: "text-muted-foreground" })] }));
+        default: {
+            const exhaustive = line.role;
+            return exhaustive;
+        }
+    }
+}
+function StreamingItem({ text }) {
+    return (_jsxs(_Fragment, { children: [_jsx(RoleLabel, { icon: _jsx(Bot, {}), children: "Assistant" }), _jsxs("div", { className: "text-[13px] leading-relaxed break-words whitespace-pre-wrap", children: [text, _jsx("span", { "aria-label": "Generating", className: "bg-foreground/70 ml-0.5 inline-block h-3.5 w-1.5 animate-pulse rounded-[1px] align-[-2px]" })] })] }));
+}
+function Transcript({ runId }) {
+    const store = useRunStore(runId);
+    const convo = useProjection(store, conversation);
+    const streaming = useEventFold(store, streamingFold);
+    const stream = streaming.turnStarted ? streaming.parts.join('') : null;
+    const toolNames = useMemo(() => {
+        const names = new Map();
+        for (const line of convo.lines) {
+            for (const call of line.toolCalls ?? []) {
+                names.set(call.id, call.name);
+            }
+        }
+        return names;
+    }, [convo.lines]);
+    const items = useMemo(() => {
+        const lines = convo.lines.map((line, index) => ({
+            kind: 'line',
+            line,
+            index,
+        }));
+        return stream === null ? lines : [...lines, { kind: 'stream', text: stream }];
+    }, [convo.lines, stream]);
+    return (_jsx(FollowList, { items: items, estimateSize: 96, overscan: 4, paddingStart: 8, paddingEnd: 12, getKey: (item) => (item.kind === 'stream' ? 'stream' : item.index), empty: _jsx("p", { className: "text-muted-foreground p-6 text-center text-xs", children: "Waiting for messages\u2026" }), renderItem: (item) => (_jsx("div", { className: "px-4 py-2", children: item.kind === 'stream' ? (_jsx(StreamingItem, { text: item.text })) : (_jsx(MessageItem, { line: item.line, toolName: item.line.toolCallId ? toolNames.get(item.line.toolCallId) : undefined })) })) }));
+}
+function DeliverySelect({ value, onChange, }) {
+    return (_jsxs(Select, { value: value, onValueChange: (next) => {
+            const option = deliveryOptions.find((candidate) => candidate.value === next);
+            if (option) {
+                onChange(option.value);
+            }
+        }, children: [_jsx(SelectTrigger, { "aria-label": "Delivery", children: _jsx(SelectValue, {}) }), _jsx(SelectContent, { align: "start", className: "w-60", children: deliveryOptions.map((option) => (_jsx(SelectItem, { value: option.value, description: option.description, children: option.label }, option.value))) })] }));
+}
+export function AgentChat(context) {
+    const { definition, runId } = context;
+    const { client } = useDebugger();
+    const [draft, setDraft] = useState('');
+    const [delivery, setDelivery] = useState('followUp');
+    const { start, pending, error } = useStartRun(context);
+    const session = definition.kind === 'agent-session';
+    const form = inputForm(definition.inputSchema);
+    function send() {
+        const content = draft.trim();
+        const input = session ? null : messageInput(form, content);
+        if (!content || input === undefined) {
+            return;
+        }
+        setDraft('');
+        start(input, session
+            ? (started) => client.signal(started.runId, agentSessionMessageEvents(createEventId(), content, { threadId: started.threadId }))
+            : undefined);
+    }
+    return (_jsxs("div", { className: "flex h-full min-h-0 flex-col", children: [runId ? (_jsx(Transcript, { runId: runId })) : (_jsx("div", { className: "min-h-0 flex-1", children: _jsx(EmptyState, { icon: _jsx(MessageSquare, {}), title: `Talk to ${definition.name}`, children: "Your first message starts a new run." }) })), runId ? (_jsx(FollowUp, { runId: runId, session: session, delivery: delivery, setDelivery: setDelivery, startError: error, onForked: context.onStarted })) : (_jsx(Composer, { value: draft, onChange: setDraft, onSubmit: send, pending: pending, placeholder: `Message ${definition.name}…`, submitLabel: "Start", error: error }))] }));
+}
+function FollowUp({ onForked, ...props }) {
+    const { status, resumable } = useRunSummary(useRunStore(props.runId));
+    return resumable ? (_jsx(ContinueRun, { runId: props.runId, status: status, onForked: onForked })) : (_jsx(Reply, { ...props }));
+}
+function ContinueRun({ runId, status, onForked, }) {
+    const { client } = useDebugger();
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    function continueInNewRun() {
+        setPending(true);
+        setError(null);
+        client
+            .fork(runId)
+            .then((forked) => onForked(forked.runId))
+            .catch((cause) => setError(errorMessage(cause)))
+            .finally(() => setPending(false));
+    }
+    return (_jsxs("div", { className: "border-border shrink-0 border-t p-3", children: [_jsxs("div", { className: "flex items-center gap-2", children: [_jsxs("p", { className: "text-muted-foreground min-w-0 flex-1 text-xs", children: ["Run ", status, ". Continue from where it stopped in a new run."] }), _jsxs(Button, { size: "sm", variant: "outline", disabled: pending, onClick: continueInNewRun, children: [_jsx(GitFork, {}), "Continue in new run"] })] }), error ? _jsx("p", { className: "text-status-failed mt-2 text-[11px]", children: error }) : null] }));
+}
+function Reply({ runId, session, delivery, setDelivery, startError }) {
+    const store = useRunStore(runId);
+    const { rootThreadId, status, finished } = useRunSummary(store);
+    const turn = useProjection(store, turnActivity);
+    const [draft, setDraft] = useState('');
+    const [pending, setPending] = useState(false);
+    const [stopping, setStopping] = useState(false);
+    const [error, setError] = useState(null);
+    function stop() {
+        if (!rootThreadId) {
+            return;
+        }
+        setStopping(true);
+        setError(null);
+        store
+            .commit(stopAgentTurn({ threadId: rootThreadId }))
+            .catch((cause) => setError(errorMessage(cause)))
+            .finally(() => setStopping(false));
+    }
+    function send() {
+        const content = draft.trim();
+        if (!content || !rootThreadId || finished) {
+            return;
+        }
+        setPending(true);
+        setError(null);
+        const events = session
+            ? agentSessionMessageEvents(createEventId(), content, {
+                delivery,
+                threadId: rootThreadId,
+                activeChildThreadId: delivery === 'steer' ? activeSessionChild(store.events()) : undefined,
+            })
+            : [userMessage(content, { threadId: rootThreadId })];
+        const [only] = events;
+        const commit = events.length === 1 && only ? store.commit(only) : store.commit(events);
+        commit
+            .then(() => setDraft(''))
+            .catch((cause) => setError(errorMessage(cause)))
+            .finally(() => setPending(false));
+    }
+    return (_jsx(Composer, { value: draft, onChange: setDraft, onSubmit: send, onStop: turn.active && !finished ? stop : undefined, stopping: stopping, pending: pending, disabled: !rootThreadId || finished, placeholder: finished ? `Run ${status}. Start a new run to continue.` : 'Send a follow-up…', error: error ?? startError, toolbar: session ? _jsx(DeliverySelect, { value: delivery, onChange: setDelivery }) : null }));
+}

package/dist/agent/debugger/index.d.ts

@@ -0,0 +1,5 @@
+import { type DebuggerPlugin } from '@swirls/looms/debugger';
+import { AgentChat } from './agent-chat';
+import { TokenUsageView } from './token-usage';
+export declare const agentDebugger: DebuggerPlugin;
+export { AgentChat, TokenUsageView };

package/dist/agent/debugger/index.js

@@ -0,0 +1,19 @@
+import { inputForm, messageInput } from '@swirls/looms/debugger';
+import { tokenUsage } from '../projections.js';
+import { AgentChat } from './agent-chat.js';
+import { summarizeAgentEvent } from './summarize.js';
+import { TokenUsageView } from './token-usage.js';
+function isChat(definition) {
+    return messageInput(inputForm(definition.inputSchema), '') !== undefined;
+}
+export const agentDebugger = {
+    name: 'agent',
+    families: [{ family: 'agent', color: 'oklch(0.74 0.12 240)', summarize: summarizeAgentEvent }],
+    workspace: {
+        kinds: ['agent', 'agent-session'],
+        matches: (definition) => definition.kind === 'agent-session' || isChat(definition),
+        component: AgentChat,
+    },
+    projections: [{ name: tokenUsage.name, component: TokenUsageView }],
+};
+export { AgentChat, TokenUsageView };

package/dist/agent/debugger/summarize.d.ts

@@ -0,0 +1,2 @@
+import { type DebuggerEvent, type EventSummary } from '@swirls/looms/debugger';
+export declare function summarizeAgentEvent(event: DebuggerEvent): EventSummary | undefined;

package/dist/agent/debugger/summarize.js

@@ -0,0 +1,53 @@
+import { isJsonObject, isJsonString } from '@swirls/looms/core';
+import { compactJson, jsonFields, jsonNumberText, jsonText, } from '@swirls/looms/debugger';
+function messageContent(payload) {
+    const message = jsonFields(payload).message;
+    return isJsonObject(message) && isJsonString(message.content) ? message.content : undefined;
+}
+function toolCallSummary(payload) {
+    const call = jsonFields(payload).toolCall;
+    if (!isJsonObject(call)) {
+        return { name: 'tool', args: null };
+    }
+    return {
+        name: isJsonString(call.name) ? call.name : 'tool',
+        args: call.arguments ?? null,
+    };
+}
+export function summarizeAgentEvent(event) {
+    const payload = jsonFields(event.payload);
+    switch (event.type) {
+        case 'agent.message.received':
+            return { title: 'user message', detail: messageContent(event.payload) };
+        case 'agent.turn.started':
+            return { title: 'turn started', detail: `turn ${jsonNumberText(payload.turn) ?? ''}` };
+        case 'agent.turn.text_delta':
+            return { title: 'text delta', detail: jsonText(payload.delta) };
+        case 'agent.message':
+            return { title: 'agent message', detail: messageContent(event.payload) };
+        case 'agent.tool_call.requested': {
+            const call = toolCallSummary(event.payload);
+            return { title: `tool ${call.name}`, detail: compactJson(call.args) };
+        }
+        case 'agent.tool.result':
+            return {
+                title: jsonText(payload.error)
+                    ? `tool error ${jsonText(payload.name)}`
+                    : `tool result ${jsonText(payload.name)}`,
+                detail: jsonText(payload.error) ?? compactJson(payload.result ?? null),
+            };
+        case 'agent.steered':
+            return { title: 'steered', detail: messageContent(event.payload) };
+        case 'agent.turn.stopped':
+            return { title: 'turn stopped' };
+        case 'agent.spawn.requested':
+            return {
+                title: 'agent spawn',
+                detail: `${jsonText(payload.kind) ?? 'agent'}:${jsonText(payload.definitionName) ?? 'unknown'}`,
+            };
+        case 'agent.effects.requested':
+            return { title: 'agent effects', detail: jsonText(payload.toolCallId) };
+        default:
+            return undefined;
+    }
+}

package/dist/agent/debugger/token-usage.d.ts

@@ -0,0 +1,3 @@
+export declare function TokenUsageView({ runId }: {
+    runId: string;
+}): import("react").JSX.Element;

package/dist/agent/debugger/token-usage.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useProjection, useRunStore } from '@swirls/looms/react';
+import { tokenUsage } from '../projections.js';
+const format = new Intl.NumberFormat();
+function Stat({ label, value }) {
+    return (_jsxs("div", { className: "border-border bg-card/60 rounded-lg border px-2.5 py-2", children: [_jsx("p", { className: "text-muted-foreground text-[11px]", children: label }), _jsx("p", { className: "font-mono text-[13px] font-medium tabular-nums", children: format.format(value) })] }));
+}
+export function TokenUsageView({ runId }) {
+    const state = useProjection(useRunStore(runId), tokenUsage);
+    return (_jsxs("div", { className: "grid grid-cols-3 gap-2", children: [_jsx(Stat, { label: "Input", value: state.input }), _jsx(Stat, { label: "Output", value: state.output }), _jsx(Stat, { label: "Total", value: state.input + state.output })] }));
+}

package/dist/agent/definitions.d.ts

@@ -13,7 +13,6 @@ export interface FunctionTool<TName extends string = string, TInput = JsonValue,
     readonly name: TName;
     readonly description: string;
     readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
-    readonly inputSchema?: JsonValue;
     handler(input: TInput, ctx: ToolContext): Promise<TOutput> | TOutput;
 }
 export interface ThreadTool {
@@ -21,7 +20,6 @@ export interface ThreadTool {
     readonly name: string;
     readonly description: string;
     readonly input?: SchemaInput;
-    readonly inputSchema?: JsonValue;
     readonly childKind: string;
     readonly childName: string;
     readonly childVersion: string;
@@ -37,7 +35,6 @@ export interface EffectsTool {
     readonly name: string;
     readonly description: string;
     readonly input?: SchemaInput;
-    readonly inputSchema?: JsonValue;
     effects(input: JsonValue): RuntimeEffect[];
     waitOn?: {
         type: string | readonly string[];
@@ -76,6 +73,7 @@ export interface AgentDefinition<TName extends string = string, TInput = JsonVal
     readonly kind: 'agent';
     readonly name: TName;
     readonly version: string;
+    readonly description?: string;
     readonly model?: string;
     readonly instructions: string;
     readonly input?: StandardSchemaV1<any, TInput> | Schema.ConstraintDecoder<TInput>;
@@ -90,6 +88,7 @@ export interface AgentSessionDefinition<TName extends string = string> {
     readonly kind: 'agent-session';
     readonly name: TName;
     readonly version: string;
+    readonly description?: 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. */
@@ -97,6 +96,7 @@ export interface AgentSessionDefinition<TName extends string = string> {
 }
 export declare function defineAgentSession<TName extends string>(def: {
     readonly name: TName;
+    readonly description?: string;
     readonly agent: Pick<AgentDefinition, 'kind' | 'name' | 'version'>;
     readonly version?: string;
     readonly idleTimeoutMs?: number;
@@ -111,7 +111,6 @@ export declare function asThreadTool(def: {
     name?: string;
     description?: string;
     input?: SchemaInput;
-    inputSchema?: JsonValue;
     child: {
         kind: string;
         name: string;
@@ -123,14 +122,12 @@ export declare function asAgentTool(def: {
     name?: string;
     description?: string;
     input?: SchemaInput;
-    inputSchema?: JsonValue;
     agent: {
         kind: 'agent';
         name: string;
         version?: string;
         instructions?: string;
         input?: SchemaInput;
-        inputSchema?: JsonValue;
     };
     mapInput?: (input: JsonValue) => JsonValue;
 }): ThreadTool;
@@ -139,13 +136,11 @@ type EvaluatorToolTarget = {
     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;
@@ -153,14 +148,12 @@ export declare function asWorkflowTool(def: {
     name?: string;
     description?: string;
     input?: SchemaInput;
-    inputSchema?: JsonValue;
     workflow: {
         kind: 'workflow';
         name: string;
         version?: string;
         description?: string;
         input?: SchemaInput;
-        inputSchema?: JsonValue;
     };
     mapInput?: (input: JsonValue) => JsonValue;
 }): ThreadTool;
@@ -168,7 +161,6 @@ export declare function asEffectsTool(def: {
     name: string;
     description: string;
     input?: SchemaInput;
-    inputSchema?: JsonValue;
     effects: (input: JsonValue) => RuntimeEffect[];
     waitOn?: {
         type: string | readonly string[];

package/dist/agent/definitions.js

@@ -1,6 +1,6 @@
 import { DEFAULT_DEFINITION_VERSION, } from '@swirls/looms/core';
 export function defineAgentSession(def) {
-    return {
+    const definition = {
         kind: 'agent-session',
         name: def.name,
         version: def.version ?? DEFAULT_DEFINITION_VERSION,
@@ -11,6 +11,10 @@ export function defineAgentSession(def) {
         },
         idleTimeoutMs: Math.max(0, def.idleTimeoutMs ?? 0),
     };
+    if (def.description === undefined) {
+        return definition;
+    }
+    return { ...definition, description: def.description };
 }
 export function normalizeTools(tools = []) {
     return tools.map((entry) => {
@@ -51,7 +55,6 @@ export function asThreadTool(def) {
         name: def.name ?? def.child.name,
         description: def.description ?? def.child.name,
         input: def.input,
-        inputSchema: def.inputSchema,
         childKind: def.child.kind,
         childName: def.child.name,
         childVersion: def.child.version ?? DEFAULT_DEFINITION_VERSION,
@@ -64,7 +67,6 @@ export function asAgentTool(def) {
         name: def.name,
         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, version: def.agent.version },
         mapInput: def.mapInput,
     });
@@ -74,7 +76,6 @@ export function asEvaluatorTool(def) {
         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,
     });
@@ -84,7 +85,6 @@ export function asWorkflowTool(def) {
         name: def.name,
         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, version: def.workflow.version },
         mapInput: def.mapInput,
     });
@@ -95,7 +95,6 @@ export function asEffectsTool(def) {
         name: def.name,
         description: def.description,
         input: def.input,
-        inputSchema: def.inputSchema,
         effects: def.effects,
         waitOn: def.waitOn,
     };