@kuralle-agents/cli 0.13.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,18 @@
+# @kuralle-agents/cli
+
+Kuralle's interactive chat, send, simulation, and trace inspection CLI.
+
+```bash
+kuralle trace session-42
+kuralle trace session-42 --last
+kuralle trace session-42 --json
+kuralle trace session-42 --web --port 4319
+```
+
+The terminal view prints a span waterfall with durations and tool, handoff, and
+error markers. `--json` returns the native `AgentTrace` JSON for agents and CI.
+`--web` starts a loopback-only read-only viewer backed by the runtime's configured
+native `TraceStore`; its JSON routes are `/api/traces/:session` and `/api/trace/:id`.
+
+Custom agent modules export `buildRuntime(sessionId?, store?)`. Configure a durable
+trace store on that runtime when traces must survive separate CLI invocations.

package/dist/agentLoader.d.ts

@@ -0,0 +1,5 @@
+import type { BuildRuntime } from './agentRuntime.js';
+export interface LoaderOptions {
+    modelFlag?: string;
+}
+export declare function resolveBuildRuntime(agentPath?: string, options?: LoaderOptions): Promise<BuildRuntime>;

package/dist/agentLoader.js

@@ -0,0 +1,144 @@
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRuntime, MemoryStore, MemoryTraceStore, } from '@kuralle-agents/core';
+import { buildDemoRuntime } from './demoAgent.js';
+import { fileSessionStore } from './fileStore.js';
+import { fileTraceStore } from './fileTraceStore.js';
+import { readAgentRunState } from './runState.js';
+import { resolveCliModel } from './resolveModel.js';
+import { newSessionId } from './sessionId.js';
+const NAMED_KEYS = ['runtime', 'agent', 'buildRuntime', 'build'];
+function isRuntime(value) {
+    return typeof value === 'object' && value !== null && typeof value.run === 'function';
+}
+function isAgentConfig(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && typeof value.id === 'string'
+        && 'instructions' in value
+        && !isRuntime(value));
+}
+function isAgentRuntime(value) {
+    return (typeof value === 'object'
+        && value !== null
+        && 'runtime' in value
+        && 'readState' in value
+        && isRuntime(value.runtime));
+}
+function classifyExport(value) {
+    if (isRuntime(value))
+        return { kind: 'runtime', value };
+    if (isAgentConfig(value))
+        return { kind: 'agent', value };
+    if (typeof value === 'function')
+        return { kind: 'factory', value: value };
+    return undefined;
+}
+function resolveModuleExport(mod) {
+    const candidates = [];
+    if ('default' in mod)
+        candidates.push(mod.default);
+    for (const key of NAMED_KEYS) {
+        if (key in mod)
+            candidates.push(mod[key]);
+    }
+    for (const candidate of candidates) {
+        const resolved = classifyExport(candidate);
+        if (resolved)
+            return resolved;
+    }
+    return undefined;
+}
+function defaultStores(sessionId, store, traceStore) {
+    if (store) {
+        return {
+            sessionStore: store,
+            traceStore: traceStore ?? new MemoryTraceStore(),
+            fileBacked: false,
+        };
+    }
+    // sim: buildRuntime() with no args → file-backed session store
+    if (sessionId === undefined) {
+        const path = join(process.cwd(), 'runs/tui-sessions.json');
+        return {
+            sessionStore: fileSessionStore(path),
+            traceStore: traceStore ?? fileTraceStore(path.replace(/\.json$/, '') + '.traces.json'),
+            fileBacked: true,
+        };
+    }
+    // chat one-shot: sessionId only → in-memory
+    return {
+        sessionStore: new MemoryStore(),
+        traceStore: traceStore ?? new MemoryTraceStore(),
+        fileBacked: false,
+    };
+}
+function assembleAgentRuntime(runtime, sessionStore, sessionId, agentId) {
+    return {
+        runtime,
+        store: sessionStore,
+        sessionId,
+        agentId,
+        label: `agent: ${agentId}`,
+        readState: () => readAgentRunState(sessionStore, sessionId),
+    };
+}
+function buildFromAgent(agent, options) {
+    return (sessionId, store, traceStore) => {
+        const sid = sessionId ?? newSessionId();
+        const stores = defaultStores(sessionId, store, traceStore);
+        const model = resolveCliModel(agent, options?.modelFlag);
+        const runtime = createRuntime({
+            agents: [agent],
+            defaultAgentId: agent.id,
+            sessionStore: stores.sessionStore,
+            defaultModel: model,
+            tracing: { store: stores.traceStore },
+        });
+        return assembleAgentRuntime(runtime, stores.sessionStore, sid, agent.id);
+    };
+}
+function buildFromRuntime(runtime) {
+    return (sessionId) => {
+        const sid = sessionId ?? newSessionId();
+        const sessionStore = runtime.getSessionStore();
+        const agentId = 'agent';
+        return assembleAgentRuntime(runtime, sessionStore, sid, agentId);
+    };
+}
+function buildFromFactory(factory) {
+    return (sessionId, store, traceStore) => {
+        const sid = sessionId ?? newSessionId();
+        const stores = defaultStores(sessionId, store, traceStore);
+        const result = factory(sid, stores.sessionStore, stores.traceStore);
+        if (result instanceof Promise) {
+            throw new Error('async buildRuntime factories are not supported');
+        }
+        if (isAgentRuntime(result))
+            return result;
+        if (isRuntime(result)) {
+            return assembleAgentRuntime(result, stores.sessionStore, sid, 'agent');
+        }
+        console.error('buildRuntime factory must return Runtime or AgentRuntime');
+        process.exit(2);
+    };
+}
+export async function resolveBuildRuntime(agentPath, options) {
+    if (!agentPath)
+        return buildFromFactory(buildDemoRuntime);
+    const abs = resolve(agentPath);
+    const mod = (await import(pathToFileURL(abs).href));
+    const resolved = resolveModuleExport(mod);
+    if (!resolved) {
+        console.error(`Agent module must export a Runtime, AgentConfig (defineAgent), or buildRuntime factory: ${abs}`);
+        process.exit(2);
+    }
+    switch (resolved.kind) {
+        case 'agent':
+            return buildFromAgent(resolved.value, options);
+        case 'runtime':
+            return buildFromRuntime(resolved.value);
+        case 'factory':
+            return buildFromFactory(resolved.value);
+    }
+}

package/dist/agentRuntime.d.ts

@@ -0,0 +1,15 @@
+import type { Runtime, SessionStore, TraceStore } from '@kuralle-agents/core';
+export interface AgentRuntime {
+    runtime: Runtime;
+    store: SessionStore;
+    sessionId: string;
+    agentId: string;
+    label: string;
+    readState: () => Promise<{
+        activeFlow?: string;
+        runEpoch?: number;
+        completedFlows?: unknown;
+        roles: string[];
+    }>;
+}
+export type BuildRuntime = (sessionId?: string, store?: SessionStore, traceStore?: TraceStore) => AgentRuntime;

package/dist/agentRuntime.js

@@ -0,0 +1 @@
+export {};

package/dist/chat.d.ts

@@ -0,0 +1,2 @@
+import type { BuildRuntime } from './agentRuntime.js';
+export declare function runChat(argv: string[], buildRuntime: BuildRuntime): void;

package/dist/chat.js

@@ -0,0 +1,179 @@
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Kuralle TUI chat — interactive terminal REPL for a live Kuralle runtime.
+ *
+ * Slash commands: /state  /reset  /help  /quit
+ */
+import { useEffect, useRef, useState } from 'react';
+import { render, Box, Text, useApp, useInput, Static } from 'ink';
+import TextInput from 'ink-text-input';
+import { newSessionId } from './sessionId.js';
+import { fileSessionStore } from './fileStore.js';
+import { fileTraceStore } from './fileTraceStore.js';
+/** Order spans as a depth-first tree (turn root → flow → node → tool/handoff). */
+function orderSpans(spans) {
+    const byParent = new Map();
+    for (const s of spans) {
+        const list = byParent.get(s.parentSpanId) ?? [];
+        list.push(s);
+        byParent.set(s.parentSpanId, list);
+    }
+    const roots = spans.filter((s) => !s.parentSpanId || !spans.some((p) => p.spanId === s.parentSpanId));
+    const out = [];
+    const walk = (s, depth) => {
+        out.push({ span: s, depth });
+        for (const child of byParent.get(s.spanId) ?? [])
+            walk(child, depth + 1);
+    };
+    for (const r of roots)
+        walk(r, 0);
+    return out;
+}
+const kindColor = (k) => k === 'turn' ? 'white' : k === 'flow' ? 'magenta' : k === 'node' ? 'blue' : k === 'tool' ? 'yellow' : k === 'handoff' ? 'cyan' : 'gray';
+/** Live trace side panel — the built-in AgentTrace of the last turn. */
+function TracePanel({ trace }) {
+    const turn = trace?.spans.find((s) => s.kind === 'turn');
+    const tin = turn?.attributes.tokensIn;
+    const tout = turn?.attributes.tokensOut;
+    const ctx = turn?.attributes.contextTokens;
+    const parts = [];
+    if (tin !== undefined || tout !== undefined)
+        parts.push(`turn ${tin ?? '?'}↓/${tout ?? '?'}↑ tok`);
+    if (ctx !== undefined)
+        parts.push(`ctx ${ctx} tok`);
+    const tokensLine = parts.length > 0 ? parts.join(' · ') : undefined;
+    return (_jsxs(Box, { flexDirection: "column", width: 46, borderStyle: "round", borderColor: "gray", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "gray", children: ["TRACE ", trace ? `· ${trace.traceId.slice(0, 8)}` : ''] }), !trace && _jsx(Text, { dimColor: true, children: "run a turn to see its trace\u2026" }), trace && (_jsxs(_Fragment, { children: [orderSpans(trace.spans).map(({ span, depth }) => (_jsxs(Text, { color: kindColor(span.kind), children: ['  '.repeat(depth), span.status === 'error' ? '✖ ' : '', span.name, _jsxs(Text, { dimColor: true, children: [" \u00B7 ", span.endTime ? `${span.endTime - span.startTime}ms` : '…'] })] }, span.spanId))), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [tokensLine && _jsx(Text, { color: "cyan", children: tokensLine }), _jsxs(Text, { dimColor: true, children: ["used tool: ", String(trace.usedTool)] }), trace.toolResults.map((r, i) => (_jsxs(Text, { color: "yellow", wrap: "truncate-end", children: ["\u2192 ", r.name, ": ", JSON.stringify(r.result)] }, i)))] })] }))] }));
+}
+let LINE_ID = 0;
+const line = (kind, text) => ({ id: LINE_ID++, kind, text });
+async function runTurn(demo, input, onText, onEvent) {
+    const handle = demo.runtime.run({ sessionId: demo.sessionId, input });
+    let text = '';
+    try {
+        for await (const part of handle.events) {
+            if (part.type === 'text-delta') {
+                text += part.delta;
+                onText(text);
+            }
+            else if (part.type === 'tool-call')
+                onEvent(`⚙ tool ${part.toolName}`);
+            else if (part.type === 'flow-enter')
+                onEvent(`▸ enter flow ${part.flow}`);
+            else if (part.type === 'flow-end')
+                onEvent(`■ end flow ${part.flow}`);
+            else if (part.type === 'handoff')
+                onEvent(`→ handoff ${part.targetAgent}`);
+            else if (part.type === 'paused')
+                onEvent(`⏸ paused ${part.waitingFor ?? ''}`);
+            else if (part.type === 'error')
+                onEvent(`✖ ${part.error}`);
+        }
+        const res = await handle;
+        if (!text && typeof res.text === 'string')
+            text = res.text;
+    }
+    catch (e) {
+        onEvent(`✖ ${e instanceof Error ? e.message : String(e)}`);
+    }
+    return text.trim();
+}
+function App({ scripted, buildRuntime, showTrace, persist }) {
+    const { exit } = useApp();
+    const make = (sid) => persist ? buildRuntime(sid ?? persist.sessionId, persist.sessionStore, persist.traceStore) : buildRuntime(sid);
+    const demoRef = useRef(make());
+    const [log, setLog] = useState([line('system', demoRef.current.label)]);
+    const [live, setLive] = useState('');
+    const [events, setEvents] = useState([]);
+    const [status, setStatus] = useState('flow: none · epoch: 0');
+    const [value, setValue] = useState('');
+    const [busy, setBusy] = useState(false);
+    const [trace, setTrace] = useState(null);
+    useInput((input, key) => { if (key.ctrl && input === 'c')
+        exit(); }, { isActive: !scripted && Boolean(process.stdin.isTTY) });
+    const push = (l) => setLog((prev) => [...prev, l]);
+    const refreshStatus = async () => {
+        const s = await demoRef.current.readState();
+        setStatus(`flow: ${s.activeFlow ?? 'none'} · epoch: ${s.runEpoch ?? 0} · done: ${JSON.stringify(s.completedFlows ?? [])}`);
+    };
+    const submit = async (raw) => {
+        const text = raw.trim();
+        if (!text || busy)
+            return;
+        setValue('');
+        if (text === '/quit') {
+            exit();
+            return;
+        }
+        if (text === '/help') {
+            push(line('system', 'commands: /state  /reset  /quit'));
+            return;
+        }
+        if (text === '/reset') {
+            demoRef.current = make(newSessionId());
+            push(line('system', `— new session ${demoRef.current.sessionId.slice(0, 8)} —`));
+            await refreshStatus();
+            return;
+        }
+        if (text === '/state') {
+            const s = await demoRef.current.readState();
+            push(line('system', `state: flow=${s.activeFlow ?? 'none'} epoch=${s.runEpoch ?? 0} completed=${JSON.stringify(s.completedFlows ?? [])} roles=[${s.roles.join(',')}]`));
+            return;
+        }
+        push(line('user', text));
+        setBusy(true);
+        setEvents([]);
+        setLive('');
+        const turnEvents = [];
+        const answer = await runTurn(demoRef.current, text, setLive, (e) => { turnEvents.push(e); setEvents([...turnEvents]); });
+        setLive('');
+        for (const e of turnEvents)
+            push(line('event', e));
+        push(line('assistant', answer || '(no text)'));
+        setBusy(false);
+        await refreshStatus();
+        if (showTrace) {
+            setTrace((await demoRef.current.runtime.listTraces(demoRef.current.sessionId))[0] ?? null);
+        }
+    };
+    useEffect(() => {
+        if (!scripted?.length)
+            return;
+        let cancelled = false;
+        (async () => {
+            for (const t of scripted) {
+                if (cancelled)
+                    return;
+                await submit(t);
+            }
+            push(line('system', '— auto complete —'));
+            setTimeout(() => exit(), 100);
+        })();
+        return () => { cancelled = true; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const color = (k) => (k === 'user' ? 'cyan' : k === 'assistant' ? 'green' : k === 'event' ? 'gray' : 'yellow');
+    const prefix = (k) => (k === 'user' ? 'You' : k === 'assistant' ? 'Agent' : k === 'event' ? '  ·' : '  ~');
+    const body = (_jsxs(Box, { flexDirection: "column", flexGrow: 1, paddingRight: showTrace ? 1 : 0, children: [_jsx(Static, { items: log, children: (l) => (_jsxs(Text, { color: color(l.kind), children: [_jsx(Text, { bold: l.kind === 'user' || l.kind === 'assistant', children: prefix(l.kind) }), '  ', l.text] }, l.id)) }), busy && (_jsxs(Box, { flexDirection: "column", children: [events.length > 0 && _jsx(Text, { color: "gray", children: events.join('  ') }), _jsxs(Text, { color: "green", children: [_jsx(Text, { bold: true, children: "Agent" }), "  ", live, _jsx(Text, { color: "green", children: "\u258C" })] })] })), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: status }) }), !scripted && (_jsxs(Box, { children: [_jsx(Text, { color: "cyan", children: busy ? '…thinking  ' : '❯ ' }), !busy && _jsx(TextInput, { value: value, onChange: setValue, onSubmit: submit, placeholder: "type a message, or /help" })] }))] }));
+    return showTrace ? (_jsxs(Box, { flexDirection: "row", children: [body, _jsx(TracePanel, { trace: trace })] })) : body;
+}
+export function runChat(argv, buildRuntime) {
+    const flag = (name) => {
+        const i = argv.indexOf(name);
+        return i >= 0 ? argv[i + 1] : undefined;
+    };
+    const scripted = argv.includes('--auto')
+        ? (flag('--auto') ?? '').split('|').map((s) => s.trim()).filter(Boolean)
+        : undefined;
+    const showTrace = argv.includes('--trace');
+    // --store persists BOTH the session (conversation/journal) and the traces to
+    // JSON files, so `--trace` accumulates across launches. --session picks the id.
+    const storePath = flag('--store');
+    const persist = storePath
+        ? {
+            sessionStore: fileSessionStore(storePath),
+            traceStore: fileTraceStore(storePath.replace(/\.json$/, '') + '.traces.json'),
+            sessionId: flag('--session') ?? 'default',
+        }
+        : undefined;
+    render(_jsx(App, { scripted: scripted, buildRuntime: buildRuntime, showTrace: showTrace, persist: persist }));
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env bun
+/**
+ * kuralle — Kuralle CLI for interactive chat, adaptive send, and simulation.
+ *
+ *   kuralle chat [--trace] [--store <file>] [--session <id>] [--auto "msg1|msg2"] [--agent <path.ts>]
+ *   kuralle send --session <id> [--store <file>] [--state|--reset] "<message>"
+ *   kuralle sim --goal "<goal>" [--turns N] [--profile "<who>"] [--agent <path.ts>]
+ *   kuralle trace <session> [--last] [--json] [--web] [--port N]
+ */
+import { resolveBuildRuntime } from './agentLoader.js';
+import { runChat } from './chat.js';
+import { runSend } from './send.js';
+import { runSim } from './sim.js';
+import { runTrace } from './trace.js';
+const HELP = `kuralle — Kuralle agent CLI
+
+Usage:
+  kuralle chat [--trace] [--store <file>] [--session <id>] [--auto "msg1|msg2"] [--agent <path.ts>]
+  kuralle send --session <id> [--store <file>] [--state|--reset] "<message>"
+  kuralle sim --goal "<goal>" [--turns N] [--profile "<who>"] [--agent <path.ts>]
+  kuralle trace <session> [--last] [--json] [--web] [--port N]
+
+Options:
+  --agent <path.ts>   Load a Runtime, defineAgent export, or buildRuntime factory
+  --model <id>        OpenAI model id when the agent export has no model (bare-agent shape)
+  --auto "a|b|c"      Headless scripted turns (chat only)
+  --trace             Live trace side panel — the built-in AgentTrace of each turn (chat only)
+  --store <file>      Persist the session + traces to JSON files so chat survives across launches (chat only)
+  --session <id>      Session id to resume with --store (default: "default")
+`;
+function flag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+function stripGlobalFlags(argv) {
+    const rest = [];
+    let agentPath;
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--agent') {
+            agentPath = argv[i + 1];
+            i += 1;
+            continue;
+        }
+        rest.push(a);
+    }
+    return { rest, agentPath };
+}
+async function main() {
+    const rawArgv = process.argv.slice(2);
+    if (rawArgv.length === 0 || rawArgv.includes('--help') || rawArgv.includes('-h')) {
+        process.stdout.write(HELP);
+        process.exit(0);
+    }
+    const { rest, agentPath } = stripGlobalFlags(rawArgv);
+    const sub = rest[0];
+    const subArgv = rest.slice(1);
+    const buildRuntime = await resolveBuildRuntime(agentPath ?? flag(rawArgv, '--agent'), {
+        modelFlag: flag(rawArgv, '--model'),
+    });
+    switch (sub) {
+        case 'chat':
+            runChat(subArgv, buildRuntime);
+            break;
+        case 'send':
+            await runSend(subArgv, buildRuntime);
+            break;
+        case 'sim':
+            await runSim(subArgv, buildRuntime);
+            break;
+        case 'trace':
+            await runTrace(subArgv, buildRuntime);
+            break;
+        default:
+            console.error(`Unknown command: ${sub}\n`);
+            process.stdout.write(HELP);
+            process.exit(2);
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/demoAgent.d.ts

@@ -0,0 +1,7 @@
+import type { LanguageModel } from 'ai';
+import { type SessionStore, type TraceStore } from '@kuralle-agents/core';
+import type { AgentRuntime, BuildRuntime } from './agentRuntime.js';
+export declare function demoModel(): LanguageModel;
+export declare function buildDemoRuntime(sessionId?: string, store?: SessionStore, traceStore?: TraceStore): AgentRuntime;
+/** Alias matching the custom-agent contract (`buildRuntime`). */
+export declare const buildRuntime: BuildRuntime;

package/dist/demoAgent.js

@@ -0,0 +1,96 @@
+/**
+ * Demo agent for the CLI — a cafe concierge that exercises fixed behaviours:
+ * order flow (collect item+day → place), global tool (todays_special), repeatable
+ * flows, and billing handoff. Provider: OpenAI gpt-4.1-mini (forced).
+ */
+import { config } from 'dotenv';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createRuntime, defineAgent, defineFlow, reply, collect, defineTool, MemoryStore, MemoryTraceStore, } from '@kuralle-agents/core';
+import { readAgentRunState } from './runState.js';
+import { newSessionId } from './sessionId.js';
+const here = dirname(fileURLToPath(import.meta.url));
+config({ path: join(here, '../.env') });
+config({ path: join(here, '../../../.env') });
+export function demoModel() {
+    const key = process.env.OPENAI_API_KEY;
+    if (!key) {
+        console.error('No OPENAI_API_KEY — set it in packages/cli/.env or the repo .env');
+        process.exit(2);
+    }
+    return createOpenAI({ apiKey: key })(process.env.OPENAI_MODEL ?? 'gpt-4.1-mini');
+}
+export function buildDemoRuntime(sessionId = newSessionId(), store = new MemoryStore(), traceStore = new MemoryTraceStore()) {
+    const model = demoModel();
+    const lastInvoice = defineTool({
+        name: 'last_invoice',
+        description: 'Return the caller last invoice total. Bill uses this to answer billing questions.',
+        input: z.object({}),
+        execute: async () => ({ invoiceUsd: 18.5, date: '2026-07-01' }),
+    });
+    const billing = defineAgent({
+        // Bill from billing — no forced self-introduction, so the handoff reads as one
+        // continuous assistant (silent handoff is on by default). Instructing a handoff
+        // target to greet/introduce itself is the anti-pattern that leaks the transfer.
+        id: 'billing',
+        instructions: 'You are Bill, the billing specialist. Answer billing/invoice questions using last_invoice. Keep replies to one or two sentences.',
+        model,
+        globalTools: { last_invoice: lastInvoice },
+    });
+    const done = reply({
+        id: 'done',
+        instructions: 'Say the order is placed for {{item}} on {{day}} — one upbeat sentence. Do not ask anything else.',
+        next: () => ({ end: 'ordered' }),
+    });
+    const collectOrder = collect({
+        id: 'collect_order',
+        schema: z.object({ item: z.string().min(2).nullable(), day: z.string().min(2).nullable() }),
+        required: ['item', 'day'],
+        maxTurns: 6,
+        instructions: (missing) => `Take the cafe order. Missing: ${missing.join(', ') || 'none'}. Ask for the item and the day; if the caller corrects a value, use the new one.`,
+        onComplete: () => done,
+    });
+    const orderFlow = defineFlow({
+        name: 'order',
+        description: 'Take a cafe order (item + day) and place it.',
+        start: collectOrder,
+        nodes: [collectOrder, done],
+    });
+    const special = defineTool({
+        name: 'todays_special',
+        description: "Return today's cafe special. Call this whenever the caller asks about the special.",
+        input: z.object({}),
+        execute: async () => ({ special: 'Cardamom bun', priceUsd: 3.5 }),
+    });
+    const concierge = defineAgent({
+        id: 'concierge',
+        instructions: 'You are a warm cafe concierge. Coffee is $4. Use the order flow when the caller wants to order. ' +
+            'Use todays_special for the special. Transfer billing/invoice questions to the billing specialist. Keep replies short.',
+        model,
+        flows: [orderFlow],
+        globalTools: { todays_special: special },
+        handoffs: ['billing'],
+        agents: [billing],
+        experimental: { outOfBandControl: true },
+    });
+    const runtime = createRuntime({
+        agents: [concierge, billing],
+        defaultAgentId: 'concierge',
+        sessionStore: store,
+        defaultModel: model,
+        tracing: { store: traceStore },
+    });
+    const readState = () => readAgentRunState(store, sessionId);
+    return {
+        runtime,
+        store,
+        sessionId,
+        agentId: 'concierge',
+        label: 'Cafe concierge (order flow · special tool · billing handoff)',
+        readState,
+    };
+}
+/** Alias matching the custom-agent contract (`buildRuntime`). */
+export const buildRuntime = buildDemoRuntime;

package/dist/fileStore.d.ts

@@ -0,0 +1,2 @@
+import type { SessionStore } from '@kuralle-agents/core';
+export declare function fileSessionStore(path: string): SessionStore;

package/dist/fileStore.js

@@ -0,0 +1,46 @@
+/**
+ * A tiny JSON-file-backed SessionStore so a conversation survives across separate
+ * process invocations — the substrate that lets `send` do adaptive multi-turn
+ * (one turn per call). `reviveSession` spreads all keys, so the durable-run state
+ * (`durableRuns`: journal + flow position + runEpoch) round-trips through JSON intact.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { reviveSession } from '@kuralle-agents/core';
+export function fileSessionStore(path) {
+    const readAll = () => {
+        if (!existsSync(path))
+            return {};
+        try {
+            return JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    };
+    const writeAll = (map) => {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(map));
+    };
+    return {
+        async get(id) {
+            const map = readAll();
+            return map[id] ? reviveSession(map[id]) : null;
+        },
+        async save(session) {
+            const map = readAll();
+            map[session.id] = session;
+            writeAll(map);
+        },
+        async delete(id) {
+            const map = readAll();
+            delete map[id];
+            writeAll(map);
+        },
+        async list(userId) {
+            return Object.values(readAll())
+                .map((raw) => reviveSession(raw))
+                .filter((s) => (userId ? s.userId === userId : true));
+        },
+    };
+}

package/dist/fileTraceStore.d.ts

@@ -0,0 +1,2 @@
+import type { TraceStore } from '@kuralle-agents/core';
+export declare function fileTraceStore(path: string): TraceStore;

package/dist/fileTraceStore.js

@@ -0,0 +1,56 @@
+/**
+ * A tiny JSONL-file-backed TraceStore so `kuralle chat --trace --store <file>`
+ * accumulates traces across launches (dev only). Spans are APPENDED one-per-line
+ * — O(1) per write, no full-file rewrite — and reconstructed on read (last write
+ * wins per spanId). Production trace stores live in @kuralle-agents/{redis,postgres}-store
+ * and @kuralle-agents/cf-agent.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { traceFromSpans } from '@kuralle-agents/core/tracing';
+export function fileTraceStore(path) {
+    let dirReady = false;
+    const putSpan = (span) => {
+        if (!dirReady) {
+            mkdirSync(dirname(path), { recursive: true });
+            dirReady = true;
+        }
+        appendFileSync(path, `${JSON.stringify(span)}\n`);
+    };
+    const readByTrace = () => {
+        const byTrace = new Map();
+        if (!existsSync(path))
+            return byTrace;
+        for (const line of readFileSync(path, 'utf8').split('\n')) {
+            if (!line)
+                continue;
+            try {
+                const span = JSON.parse(line);
+                let spans = byTrace.get(span.traceId);
+                if (!spans) {
+                    spans = new Map();
+                    byTrace.set(span.traceId, spans);
+                }
+                spans.set(span.spanId, span); // last write wins (span updates)
+            }
+            catch {
+                // skip a torn/partial line rather than fail the read
+            }
+        }
+        return byTrace;
+    };
+    return {
+        write: putSpan,
+        putSpan,
+        async getTrace(traceId) {
+            return traceFromSpans([...(readByTrace().get(traceId)?.values() ?? [])]);
+        },
+        async listTraces(sessionId, window) {
+            const traces = [...readByTrace().values()]
+                .map((spans) => traceFromSpans([...spans.values()]))
+                .filter((t) => t !== null && t.sessionId === sessionId)
+                .sort((a, b) => b.startedAt - a.startedAt);
+            return window?.limit === undefined ? traces : traces.slice(0, window.limit);
+        },
+    };
+}

package/dist/resolveModel.d.ts

@@ -0,0 +1,4 @@
+import type { LanguageModel } from 'ai';
+import type { AgentConfig } from '@kuralle-agents/core';
+/** Resolve a speaker model for a bare agent: agent.model → --model → OPENAI_MODEL → error. */
+export declare function resolveCliModel(agent: AgentConfig, modelFlag?: string): LanguageModel;

package/dist/resolveModel.js

@@ -0,0 +1,24 @@
+import { config } from 'dotenv';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createOpenAI } from '@ai-sdk/openai';
+const here = dirname(fileURLToPath(import.meta.url));
+config({ path: join(here, '../.env') });
+config({ path: join(here, '../../../.env') });
+/** Resolve a speaker model for a bare agent: agent.model → --model → OPENAI_MODEL → error. */
+export function resolveCliModel(agent, modelFlag) {
+    if (agent.model)
+        return agent.model;
+    const key = process.env.OPENAI_API_KEY;
+    if (!key) {
+        console.error('No OPENAI_API_KEY — set it in packages/cli/.env or the repo .env');
+        process.exit(2);
+    }
+    const openai = createOpenAI({ apiKey: key });
+    if (modelFlag)
+        return openai(modelFlag);
+    if (process.env.OPENAI_MODEL)
+        return openai(process.env.OPENAI_MODEL);
+    console.error('agent has no model; pass --model');
+    process.exit(2);
+}

package/dist/runState.d.ts

@@ -0,0 +1,9 @@
+import type { SessionStore } from '@kuralle-agents/core';
+export interface AgentRunState {
+    activeFlow?: string;
+    runEpoch?: number;
+    completedFlows?: unknown;
+    roles: string[];
+}
+/** Read flow position + message roles from the durable run journal (CLI-internal). */
+export declare function readAgentRunState(store: SessionStore, sessionId: string): Promise<AgentRunState>;

package/dist/runState.js

@@ -0,0 +1,11 @@
+/** Read flow position + message roles from the durable run journal (CLI-internal). */
+export async function readAgentRunState(store, sessionId) {
+    const s = await store.get(sessionId);
+    const rs = s?.durableRuns?.[sessionId]?.runState;
+    return {
+        activeFlow: rs?.activeFlow,
+        runEpoch: rs?.runEpoch,
+        completedFlows: rs?.state?.__completedFlows,
+        roles: (s?.messages ?? []).map((m) => m.role),
+    };
+}

package/dist/send.d.ts

@@ -0,0 +1,2 @@
+import type { BuildRuntime } from './agentRuntime.js';
+export declare function runSend(argv: string[], buildRuntime: BuildRuntime): Promise<void>;

package/dist/send.js

@@ -0,0 +1,69 @@
+/**
+ * send — ONE turn against a PERSISTED session for adaptive multi-turn conversations.
+ *
+ * Flags: --session <id> · --store <file> · --state · --reset
+ */
+import { join } from 'node:path';
+import { fileSessionStore } from './fileStore.js';
+function flag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export async function runSend(argv, buildRuntime) {
+    const sessionId = flag(argv, '--session') ?? 'default';
+    const storePath = flag(argv, '--store') ?? join(process.cwd(), 'runs/tui-sessions.json');
+    const doReset = argv.includes('--reset');
+    const doState = argv.includes('--state');
+    const reserved = new Set(['--session', sessionId, '--store', storePath]);
+    const message = argv
+        .filter((a, i) => !a.startsWith('--') && !(i > 0 && (argv[i - 1] === '--session' || argv[i - 1] === '--store')))
+        .join(' ')
+        .trim();
+    const store = fileSessionStore(storePath);
+    const demo = buildRuntime(sessionId, store);
+    async function readState() {
+        const s = await store.get(sessionId);
+        const rs = s?.durableRuns?.[sessionId]?.runState;
+        return `[state] flow=${rs?.activeFlow ?? 'none'} · epoch=${rs?.runEpoch ?? 0} · done=${JSON.stringify(rs?.state?.__completedFlows ?? [])} · turns=${(s?.messages ?? []).filter((m) => m.role === 'user').length}`;
+    }
+    if (doReset) {
+        await store.delete(sessionId);
+        console.log(`reset session "${sessionId}"`);
+        return;
+    }
+    if (doState || !message) {
+        console.log(await readState());
+        if (!message && !doState)
+            console.error('(no message — pass one to take a turn, or --state to inspect)');
+        return;
+    }
+    const events = [];
+    const handle = demo.runtime.run({ sessionId, input: message });
+    let text = '';
+    for await (const part of handle.events) {
+        if (part.type === 'text-delta') {
+            text += part.delta;
+            process.stdout.write(part.delta);
+        }
+        else if (part.type === 'tool-call')
+            events.push(`tool:${part.toolName}`);
+        else if (part.type === 'flow-enter')
+            events.push(`enter:${part.flow}`);
+        else if (part.type === 'flow-end')
+            events.push(`end:${part.flow}`);
+        else if (part.type === 'handoff')
+            events.push(`handoff:${part.targetAgent}`);
+        else if (part.type === 'paused')
+            events.push(`paused:${part.waitingFor ?? ''}`);
+        else if (part.type === 'error')
+            events.push(`error:${part.error}`);
+    }
+    const res = await handle;
+    if (!text && typeof res.text === 'string')
+        text = res.text;
+    if (!text.endsWith('\n'))
+        process.stdout.write('\n');
+    if (events.length)
+        console.log(`[events] ${events.join(' ')}`);
+    console.log(await readState());
+}

package/dist/sessionId.d.ts

@@ -0,0 +1,2 @@
+/** Local session id helper — core's `newSessionId` is not on the public index. */
+export declare function newSessionId(): string;

package/dist/sessionId.js

@@ -0,0 +1,5 @@
+import { randomUUID } from 'node:crypto';
+/** Local session id helper — core's `newSessionId` is not on the public index. */
+export function newSessionId() {
+    return randomUUID();
+}

package/dist/sim.d.ts

@@ -0,0 +1,2 @@
+import type { BuildRuntime } from './agentRuntime.js';
+export declare function runSim(argv: string[], buildRuntime: BuildRuntime): Promise<void>;

package/dist/sim.js

@@ -0,0 +1,44 @@
+/**
+ * sim — drive simulateConversation with a persona toward a goal and print the transcript.
+ */
+import { simulateConversation, createJudge } from '@kuralle-agents/core';
+import { demoModel } from './demoAgent.js';
+function flag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+export async function runSim(argv, buildRuntime) {
+    const goal = flag(argv, '--goal');
+    if (!goal) {
+        console.error('Usage: kuralle sim --goal "<persona goal>" [--turns N] [--profile "<who>"] [--agent <path.ts>]');
+        process.exit(2);
+    }
+    const turnsRaw = flag(argv, '--turns');
+    const maxTurns = turnsRaw ? Number.parseInt(turnsRaw, 10) : 10;
+    if (!Number.isFinite(maxTurns) || maxTurns < 1) {
+        console.error('--turns must be a positive integer');
+        process.exit(2);
+    }
+    const profile = flag(argv, '--profile') ?? 'a customer chatting with the agent';
+    const model = demoModel();
+    const demo = buildRuntime();
+    const persona = { profile, goal, temperament: 'brief and direct' };
+    console.log(`Simulating: ${profile}`);
+    console.log(`Goal: ${goal}`);
+    console.log(`Max turns: ${maxTurns}\n`);
+    const result = await simulateConversation({
+        runtime: demo.runtime,
+        persona,
+        userModel: model,
+        maxTurns,
+        sessionId: demo.sessionId,
+    });
+    for (const turn of result.transcript) {
+        const label = turn.role === 'user' ? 'You' : 'Agent';
+        console.log(`${label}: ${turn.content}\n`);
+    }
+    console.log(`— ended by: ${result.endedBy} · turns: ${result.turns} · tools: ${result.toolsCalled.join(', ') || 'none'} —`);
+    const judge = createJudge({ model });
+    const verdict = await judge.judge(result, persona);
+    console.log(`Judge: overall=${verdict.overall.toFixed(1)} pass=${verdict.pass} — ${verdict.summary}`);
+}

package/dist/trace.d.ts

@@ -0,0 +1,6 @@
+import type { AgentTrace } from '@kuralle-agents/core';
+import { type Server } from 'node:http';
+import type { BuildRuntime } from './agentRuntime.js';
+export declare function runTrace(argv: string[], buildRuntime: BuildRuntime): Promise<void>;
+export declare function startTraceWebServer(runtime: Pick<import('@kuralle-agents/core').Runtime, 'listTraces' | 'getTrace'>, sessionId: string, port?: number): Promise<Server>;
+export declare function formatTrace(trace: AgentTrace): string;

package/dist/trace.js

@@ -0,0 +1,116 @@
+import { renderTraceViewerDocument } from '@kuralle-agents/trace-ui';
+import { createServer } from 'node:http';
+export async function runTrace(argv, buildRuntime) {
+    const sessionId = argv.find((arg) => !arg.startsWith('--'));
+    if (!sessionId)
+        throw new Error('Usage: kuralle trace <session> [--last] [--json]');
+    const { runtime } = buildRuntime(sessionId);
+    if (argv.includes('--web')) {
+        const port = numberFlag(argv, '--port') ?? 4319;
+        await startTraceWebServer(runtime, sessionId, port);
+        process.stdout.write(`Kuralle trace viewer: http://127.0.0.1:${port}\n`);
+        return;
+    }
+    const traces = await runtime.listTraces(sessionId);
+    const selected = argv.includes('--last') ? traces.slice(0, 1) : traces;
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify(argv.includes('--last') ? selected[0] ?? null : selected, null, 2)}\n`);
+        return;
+    }
+    if (selected.length === 0) {
+        process.stdout.write(`No traces found for session ${sessionId}\n`);
+        return;
+    }
+    process.stdout.write(`${selected.map(formatTrace).join('\n\n')}\n`);
+}
+export async function startTraceWebServer(runtime, sessionId, port = 4319) {
+    const server = createServer(async (request, response) => {
+        try {
+            const url = new URL(request.url ?? '/', 'http://localhost');
+            if (url.pathname === `/api/traces/${encodeURIComponent(sessionId)}`) {
+                return sendJson(response, await runtime.listTraces(sessionId));
+            }
+            if (url.pathname.startsWith('/api/trace/')) {
+                const traceId = decodeURIComponent(url.pathname.slice('/api/trace/'.length));
+                const trace = await runtime.getTrace(traceId);
+                return sendJson(response, trace, trace ? 200 : 404);
+            }
+            if (url.pathname === '/') {
+                const nonce = crypto.randomUUID().replaceAll('-', '');
+                const html = renderTraceViewerDocument(await runtime.listTraces(sessionId), {
+                    title: `Kuralle traces · ${sessionId}`,
+                    nonce,
+                });
+                response.writeHead(200, {
+                    'content-type': 'text/html; charset=utf-8',
+                    'content-security-policy': `default-src 'none'; style-src 'nonce-${nonce}'; base-uri 'none'; frame-ancestors 'self'`,
+                    'cache-control': 'no-store',
+                });
+                response.end(html);
+                return;
+            }
+            response.writeHead(404).end('Not found');
+        }
+        catch (error) {
+            response.writeHead(500, { 'content-type': 'text/plain; charset=utf-8' });
+            response.end(error instanceof Error ? error.message : String(error));
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', resolve);
+    });
+    return server;
+}
+function sendJson(response, value, status = 200) {
+    response.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(JSON.stringify(value));
+}
+function numberFlag(argv, name) {
+    const index = argv.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = Number(argv[index + 1]);
+    if (!Number.isInteger(value) || value < 0 || value > 65535)
+        throw new Error(`${name} requires a valid port`);
+    return value;
+}
+export function formatTrace(trace) {
+    const start = trace.startedAt;
+    const end = trace.endedAt ?? Math.max(...trace.spans.map((span) => span.endTime ?? span.startTime));
+    const duration = Math.max(1, end - start);
+    const lines = [
+        `trace ${trace.traceId}  session ${trace.sessionId}  ${formatDuration(end - start)}`,
+        '  offset    duration  span',
+    ];
+    for (const span of trace.spans) {
+        const offset = span.startTime - start;
+        const width = Math.max(1, Math.round(((span.endTime ?? end) - span.startTime) / duration * 30));
+        const indent = depth(span, trace.spans) * 2;
+        lines.push(`${String(offset).padStart(7)}ms  ${formatDuration((span.endTime ?? end) - span.startTime).padStart(8)}  ` +
+            `${' '.repeat(indent)}${marker(span)} ${span.name} ${'━'.repeat(width)}`);
+    }
+    return lines.join('\n');
+}
+function depth(span, spans) {
+    const byId = new Map(spans.map((entry) => [entry.spanId, entry]));
+    let parent = span.parentSpanId;
+    let value = 0;
+    while (parent && value < 10) {
+        value += 1;
+        parent = byId.get(parent)?.parentSpanId;
+    }
+    return value;
+}
+function marker(span) {
+    if (span.status === 'error')
+        return '✕';
+    if (span.kind === 'tool')
+        return '🔧';
+    if (span.kind === 'handoff')
+        return '⇢';
+    return '●';
+}
+function formatDuration(ms) {
+    return ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${ms}ms`;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@kuralle-agents/cli",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kuralle/kuralle-agents.git",
+    "directory": "packages/cli"
+  },
+  "version": "0.13.0",
+  "description": "Kuralle CLI — interactive TUI chat, adaptive send, and conversation simulation",
+  "type": "module",
+  "bin": {
+    "kuralle": "./dist/cli.js"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.0",
+    "ai": "^6.0.0",
+    "dotenv": "^16.4.0",
+    "ink": "^7.1.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^19.2.7",
+    "zod": "^4.0.0",
+    "@kuralle-agents/core": "0.13.0",
+    "@kuralle-agents/trace-ui": "0.13.0"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0",
+    "zod": "^4.0.0",
+    "@kuralle-agents/core": "0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/react": "^19.2.17",
+    "typescript": "^5.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "prebuild": "rm -rf dist",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "clean": "rm -rf dist"
+  }
+}