@adia-ai/agent 0.8.26

package/prompt.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Prompt layers — ordered, composable system-prompt assembly.
+ *
+ * A layer is static text (cacheable) or a function (resolved fresh every
+ * turn, never cached). composeSystem() places static layers first so the
+ * cache breakpoint covers the stable prefix, then dynamic layers.
+ *
+ * Two output shapes, provider-decided by the agent:
+ *  - Anthropic: an array of system text blocks with `cache_control:
+ *    { type: 'ephemeral' }` on the LAST static layer — dynamic layers ride
+ *    after the breakpoint, so a per-turn context layer never busts the
+ *    cached identity/capabilities prefix.
+ *  - Everyone else: one joined string (their adapters take system as text).
+ */
+export interface PromptLayer {
+    name: string;
+    text: string | (() => string);
+    cache?: boolean;
+}
+export declare function promptLayer(name: string, text: string | (() => string), opts?: {
+    cache?: boolean;
+}): PromptLayer;
+export interface ComposedSystem {
+    /** Joined plain-text form — for providers whose system is a string. */
+    text: string;
+    /** Block-array form with cache_control markers — for Anthropic. */
+    blocks: Array<{
+        type: string;
+        text: string;
+        cache_control?: {
+            type: string;
+        };
+    }>;
+}
+export declare function composeSystem(layers: PromptLayer[]): ComposedSystem;
+//# sourceMappingURL=prompt.d.ts.map

package/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,EAC7B,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7B,WAAW,CAKb;AAED,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CACjF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,cAAc,CAqBnE"}

package/prompt.js

@@ -0,0 +1,38 @@
+/**
+ * Prompt layers — ordered, composable system-prompt assembly.
+ *
+ * A layer is static text (cacheable) or a function (resolved fresh every
+ * turn, never cached). composeSystem() places static layers first so the
+ * cache breakpoint covers the stable prefix, then dynamic layers.
+ *
+ * Two output shapes, provider-decided by the agent:
+ *  - Anthropic: an array of system text blocks with `cache_control:
+ *    { type: 'ephemeral' }` on the LAST static layer — dynamic layers ride
+ *    after the breakpoint, so a per-turn context layer never busts the
+ *    cached identity/capabilities prefix.
+ *  - Everyone else: one joined string (their adapters take system as text).
+ */
+export function promptLayer(name, text, opts = {}) {
+    if (typeof text === 'function' && opts.cache) {
+        throw new Error(`promptLayer "${name}": a function layer resolves per turn and cannot be cached`);
+    }
+    return { name, text, ...(opts.cache ? { cache: true } : {}) };
+}
+export function composeSystem(layers) {
+    const staticLayers = layers.filter(l => typeof l.text === 'string');
+    const dynamicLayers = layers.filter(l => typeof l.text === 'function');
+    const resolve = (l) => typeof l.text === 'function' ? l.text() : l.text;
+    const ordered = [...staticLayers, ...dynamicLayers];
+    const texts = ordered.map(resolve).filter(Boolean);
+    const lastCached = [...staticLayers].reverse().find(l => l.cache);
+    const blocks = ordered
+        .map((l, i) => ({ layer: l, text: texts[i] ?? '' }))
+        .filter(e => e.text)
+        .map(e => ({
+        type: 'text',
+        text: e.text,
+        ...(e.layer === lastCached ? { cache_control: { type: 'ephemeral' } } : {}),
+    }));
+    return { text: texts.join('\n\n'), blocks };
+}
+//# sourceMappingURL=prompt.js.map

package/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["src/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,MAAM,UAAU,WAAW,CACzB,IAAY,EACZ,IAA6B,EAC7B,OAA4B,EAAE;IAE9B,IAAI,OAAO,IAAI,KAAK,UAAU,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,gBAAgB,IAAI,4DAA4D,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAChE,CAAC;AASD,MAAM,UAAU,aAAa,CAAC,MAAqB;IACjD,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IACpE,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAEvE,MAAM,OAAO,GAAG,CAAC,CAAc,EAAU,EAAE,CACzC,OAAO,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAEnD,MAAM,OAAO,GAAG,CAAC,GAAG,YAAY,EAAE,GAAG,aAAa,CAAC,CAAC;IACpD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAEnD,MAAM,UAAU,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAClE,MAAM,MAAM,GAAG,OAAO;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;SACnD,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SACnB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QACT,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,CAAC,CAAC,IAAI;QACZ,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC,CAAC,CAAC;IAEN,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC"}

package/resource.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Resources — declared ways to bring outside information in.
+ *
+ * Two modes, mirroring the MCP resource/tool distinction, both riding
+ * machinery the harness already has:
+ *  - 'attach' — application-controlled: the resource is fetched by the
+ *    harness each turn and attached as a dynamic prompt layer. The model
+ *    never asks; the data is just there.
+ *  - 'tool'   — model-controlled: the resource becomes a read-only tool
+ *    (`read_<name>`) the model calls when it decides it needs the data.
+ */
+import type { PromptLayer } from './prompt.js';
+import { type ToolDef } from './tools.js';
+export interface ResourceDef {
+    name: string;
+    description?: string;
+    mode: 'attach' | 'tool';
+    get: (input?: Record<string, unknown>) => string | Promise<string>;
+}
+export declare function defineResource(def: ResourceDef): ResourceDef;
+/** Attach-mode resources → dynamic prompt layers. Resolution happens at
+ *  compose time (async), so the layer text is a plain string by the time
+ *  it reaches composeSystem. */
+export declare function attachLayers(resources: ResourceDef[]): Promise<PromptLayer[]>;
+/** Tool-mode resources → read-only tools the model can call. */
+export declare function resourceTools(resources: ResourceDef[]): ToolDef[];
+//# sourceMappingURL=resource.d.ts.map

package/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAc,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC;IACxB,GAAG,EAAE,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAS5D;AAED;;gCAEgC;AAChC,wBAAsB,YAAY,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAOnF;AAED,gEAAgE;AAChE,wBAAgB,aAAa,CAAC,SAAS,EAAE,WAAW,EAAE,GAAG,OAAO,EAAE,CASjE"}

package/resource.js

@@ -0,0 +1,46 @@
+/**
+ * Resources — declared ways to bring outside information in.
+ *
+ * Two modes, mirroring the MCP resource/tool distinction, both riding
+ * machinery the harness already has:
+ *  - 'attach' — application-controlled: the resource is fetched by the
+ *    harness each turn and attached as a dynamic prompt layer. The model
+ *    never asks; the data is just there.
+ *  - 'tool'   — model-controlled: the resource becomes a read-only tool
+ *    (`read_<name>`) the model calls when it decides it needs the data.
+ */
+import { defineTool } from './tools.js';
+export function defineResource(def) {
+    if (!def.name)
+        throw new Error('defineResource: name is required');
+    if (def.mode !== 'attach' && def.mode !== 'tool') {
+        throw new Error(`defineResource "${def.name}": mode is 'attach' | 'tool'`);
+    }
+    if (typeof def.get !== 'function') {
+        throw new Error(`defineResource "${def.name}": get() is required`);
+    }
+    return def;
+}
+/** Attach-mode resources → dynamic prompt layers. Resolution happens at
+ *  compose time (async), so the layer text is a plain string by the time
+ *  it reaches composeSystem. */
+export async function attachLayers(resources) {
+    const attach = resources.filter(r => r.mode === 'attach');
+    const resolved = await Promise.all(attach.map(async (r) => ({
+        name: `resource:${r.name}`,
+        text: `<resource name="${r.name}"${r.description ? ` description="${r.description}"` : ''}>\n${await r.get()}\n</resource>`,
+    })));
+    return resolved.filter(l => l.text);
+}
+/** Tool-mode resources → read-only tools the model can call. */
+export function resourceTools(resources) {
+    return resources
+        .filter(r => r.mode === 'tool')
+        .map(r => defineTool({
+        name: `read_${r.name.replace(/[^a-zA-Z0-9_-]/g, '_')}`,
+        description: r.description ?? `Read the "${r.name}" resource`,
+        inputSchema: { type: 'object', properties: {} },
+        execute: (input) => r.get(input),
+    }));
+}
+//# sourceMappingURL=resource.js.map

package/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["src/resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,UAAU,EAAgB,MAAM,YAAY,CAAC;AAStD,MAAM,UAAU,cAAc,CAAC,GAAgB;IAC7C,IAAI,CAAC,GAAG,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACnE,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,8BAA8B,CAAC,CAAC;IAC7E,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;gCAEgC;AAChC,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,SAAwB;IACzD,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAC,CAAC,EAAC,EAAE,CAAC,CAAC;QACxD,IAAI,EAAE,YAAY,CAAC,CAAC,IAAI,EAAE;QAC1B,IAAI,EAAE,mBAAmB,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,MAAM,MAAM,CAAC,CAAC,GAAG,EAAE,eAAe;KAC5H,CAAC,CAAC,CAAC,CAAC;IACL,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AACtC,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,aAAa,CAAC,SAAwB;IACpD,OAAO,SAAS;SACb,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,UAAU,CAAC;QACnB,IAAI,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,EAAE;QACtD,WAAW,EAAE,CAAC,CAAC,WAAW,IAAI,aAAa,CAAC,CAAC,IAAI,YAAY;QAC7D,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,EAAE,EAAE;QAC/C,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;KACjC,CAAC,CAAC,CAAC;AACR,CAAC"}

package/session.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session — the serializable conversation state.
+ *
+ * The caller owns persistence: a Session is a plain JSON-safe object
+ * (localStorage, a DB row, a URL — the package never stores one). All
+ * mutation flows through `reduce()` (events.ts), which returns a new
+ * Session; nothing in this package holds a reference to the caller's.
+ *
+ * `draft` is reduce()'s in-flight assistant turn (text snapshot + parts
+ * accumulated between a round's first chunk and its close). It is part of
+ * the serialized shape on purpose — resuming mid-turn drops nothing.
+ */
+import type { Part } from '@adia-ai/llm';
+export interface Msg {
+    role: 'user' | 'assistant' | 'tool';
+    content: string | Part[];
+}
+export interface Draft {
+    text: string;
+    parts: Part[];
+}
+export interface Session {
+    id: string;
+    messages: Msg[];
+    draft?: Draft;
+}
+export declare function createSession(id?: string): Session;
+export declare function toJSON(session: Session): string;
+export declare function fromJSON(json: string): Session;
+//# sourceMappingURL=session.d.ts.map

package/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,cAAc,CAAC;AAEzC,MAAM,WAAW,GAAG;IAClB,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IACpC,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,IAAI,EAAE,CAAC;CACf;AAED,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAID,wBAAgB,aAAa,CAAC,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAKlD;AAED,wBAAgB,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAE/C;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAM9C"}

package/session.js

@@ -0,0 +1,30 @@
+/**
+ * Session — the serializable conversation state.
+ *
+ * The caller owns persistence: a Session is a plain JSON-safe object
+ * (localStorage, a DB row, a URL — the package never stores one). All
+ * mutation flows through `reduce()` (events.ts), which returns a new
+ * Session; nothing in this package holds a reference to the caller's.
+ *
+ * `draft` is reduce()'s in-flight assistant turn (text snapshot + parts
+ * accumulated between a round's first chunk and its close). It is part of
+ * the serialized shape on purpose — resuming mid-turn drops nothing.
+ */
+let sessionCounter = 0;
+export function createSession(id) {
+    return {
+        id: id ?? `s_${Date.now().toString(36)}_${++sessionCounter}`,
+        messages: [],
+    };
+}
+export function toJSON(session) {
+    return JSON.stringify(session);
+}
+export function fromJSON(json) {
+    const parsed = JSON.parse(json);
+    if (!parsed || typeof parsed.id !== 'string' || !Array.isArray(parsed.messages)) {
+        throw new Error('Not a serialized Session: expected { id, messages[] }');
+    }
+    return parsed;
+}
+//# sourceMappingURL=session.js.map

package/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAoBH,IAAI,cAAc,GAAG,CAAC,CAAC;AAEvB,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO;QACL,EAAE,EAAE,EAAE,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,cAAc,EAAE;QAC5D,QAAQ,EAAE,EAAE;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,OAAgB;IACrC,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;AACjC,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAY,CAAC;IAC3C,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAChF,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/stub.d.ts

@@ -0,0 +1,22 @@
+/**
+ * scriptClient — a deterministic LLMClient for tests.
+ *
+ * Feed it turns; each chat()/stream() call consumes the next one. A turn
+ * with toolUse yields tool_use chunks (after any text), so a scripted
+ * [call-tool, then answer] pair exercises the whole loop keylessly.
+ * Complements @adia-ai/llm's StubLLMAdapter (which speaks A2UI JSON, not
+ * tool rounds).
+ */
+import type { ChatOpts, LLMClient, ToolUse } from '@adia-ai/llm';
+export interface ScriptedTurn {
+    text?: string;
+    toolUse?: ToolUse[];
+    stopReason?: string;
+}
+export interface ScriptClient extends LLMClient {
+    /** Every ChatOpts the client was called with, in order — assert on
+     *  messages/tools/system reaching the wire. */
+    calls: Array<Partial<ChatOpts>>;
+}
+export declare function scriptClient(turns: ScriptedTurn[]): ScriptClient;
+//# sourceMappingURL=stub.d.ts.map

package/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAc,SAAS,EAAe,OAAO,EAAE,MAAM,cAAc,CAAC;AAE1F,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C;mDAC+C;IAC/C,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;CACjC;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,EAAE,GAAG,YAAY,CA0ChE"}

package/stub.js

@@ -0,0 +1,52 @@
+/**
+ * scriptClient — a deterministic LLMClient for tests.
+ *
+ * Feed it turns; each chat()/stream() call consumes the next one. A turn
+ * with toolUse yields tool_use chunks (after any text), so a scripted
+ * [call-tool, then answer] pair exercises the whole loop keylessly.
+ * Complements @adia-ai/llm's StubLLMAdapter (which speaks A2UI JSON, not
+ * tool rounds).
+ */
+export function scriptClient(turns) {
+    let cursor = 0;
+    const calls = [];
+    function next() {
+        const turn = turns[cursor];
+        if (!turn)
+            throw new Error(`scriptClient: call ${cursor + 1} but only ${turns.length} turns scripted`);
+        cursor++;
+        return turn;
+    }
+    return {
+        calls,
+        async chat(opts) {
+            calls.push(opts);
+            const turn = next();
+            return {
+                text: turn.text ?? '',
+                usage: { input: 1, output: 1 },
+                stopReason: turn.stopReason ?? (turn.toolUse?.length ? 'tool_use' : 'end'),
+                ...(turn.toolUse?.length ? { toolUse: turn.toolUse } : {}),
+            };
+        },
+        async *stream(opts) {
+            calls.push(opts);
+            const turn = next();
+            let snapshot = '';
+            if (turn.text) {
+                snapshot = turn.text;
+                yield { type: 'text', text: turn.text, snapshot };
+            }
+            for (const call of turn.toolUse ?? []) {
+                yield { type: 'tool_use', id: call.id, name: call.name, input: call.input };
+            }
+            yield {
+                type: 'done',
+                text: snapshot,
+                usage: { input: 1, output: 1 },
+                stopReason: turn.stopReason ?? (turn.toolUse?.length ? 'tool_use' : 'end'),
+            };
+        },
+    };
+}
+//# sourceMappingURL=stub.js.map

package/stub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.js","sourceRoot":"","sources":["src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAgBH,MAAM,UAAU,YAAY,CAAC,KAAqB;IAChD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,KAAK,GAA6B,EAAE,CAAC;IAE3C,SAAS,IAAI;QACX,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC;QAC3B,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,GAAG,CAAC,aAAa,KAAK,CAAC,MAAM,iBAAiB,CAAC,CAAC;QACvG,MAAM,EAAE,CAAC;QACT,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,KAAK;QACL,KAAK,CAAC,IAAI,CAAC,IAAuB;YAChC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,OAAO;gBACL,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,EAAE;gBACrB,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;gBAC1E,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC3D,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAC,IAAuB;YACnC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACjB,MAAM,IAAI,GAAG,IAAI,EAAE,CAAC;YACpB,IAAI,QAAQ,GAAG,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACd,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;gBACrB,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,CAAC;YACpD,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;gBACtC,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9E,CAAC;YACD,MAAM;gBACJ,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,QAAQ;gBACd,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE;gBAC9B,UAAU,EAAE,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC;aAC3E,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/tools.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Tools — the typed-call registry.
+ *
+ * A tool is a JSON-Schema'd contract plus exactly one executor: a local
+ * `execute` function or a server `endpoint` (POSTs the input as JSON,
+ * returns the response text). Input is checked against the schema at the
+ * call boundary — an invalid call fails BEFORE it does anything, and the
+ * failure feeds back to the model as an isError tool_result, never a throw.
+ *
+ * The schema check is deliberately minimal (top-level required / type /
+ * enum) — zero dependencies. Consumers wanting full JSON-Schema semantics
+ * can validate inside their own `execute`.
+ */
+import type { ToolSpec } from '@adia-ai/llm';
+export interface ToolContext {
+    sessionId: string;
+    signal?: AbortSignal;
+}
+export interface ToolDef {
+    name: string;
+    description?: string;
+    inputSchema: Record<string, unknown>;
+    execute?: (input: Record<string, unknown>, ctx: ToolContext) => unknown | Promise<unknown>;
+    endpoint?: {
+        url: string;
+        method?: string;
+        headers?: Record<string, string>;
+    };
+}
+export declare function defineTool(def: ToolDef): ToolDef;
+export declare function toSpecs(tools: ToolDef[]): ToolSpec[];
+/** Top-level required / type / enum check. Returns null when valid,
+ *  a human-readable problem string when not. */
+export declare function checkInput(schema: Record<string, unknown>, input: Record<string, unknown>): string | null;
+export interface ToolOutcome {
+    output: string;
+    isError?: boolean;
+}
+/** Run one tool call end to end: schema check → executor → string output.
+ *  Every failure path returns { isError: true } — the model sees the
+ *  problem and can retry; the loop never throws over a bad call. */
+export declare function executeTool(tool: ToolDef, input: Record<string, unknown>, ctx: ToolContext): Promise<ToolOutcome>;
+//# sourceMappingURL=tools.d.ts.map

package/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3F,QAAQ,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,CAAC;CAC/E;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAWhD;AAED,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,QAAQ,EAAE,CAMpD;AAED;gDACgD;AAChD,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAmBzG;AAeD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;oEAEoE;AACpE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC,CA4BtB"}

package/tools.js

@@ -0,0 +1,103 @@
+/**
+ * Tools — the typed-call registry.
+ *
+ * A tool is a JSON-Schema'd contract plus exactly one executor: a local
+ * `execute` function or a server `endpoint` (POSTs the input as JSON,
+ * returns the response text). Input is checked against the schema at the
+ * call boundary — an invalid call fails BEFORE it does anything, and the
+ * failure feeds back to the model as an isError tool_result, never a throw.
+ *
+ * The schema check is deliberately minimal (top-level required / type /
+ * enum) — zero dependencies. Consumers wanting full JSON-Schema semantics
+ * can validate inside their own `execute`.
+ */
+export function defineTool(def) {
+    if (!def.name || !/^[a-zA-Z0-9_-]+$/.test(def.name)) {
+        throw new Error(`defineTool: "${def.name}" — tool names are [a-zA-Z0-9_-]+`);
+    }
+    if (!def.inputSchema) {
+        throw new Error(`defineTool "${def.name}": inputSchema is required`);
+    }
+    if (!!def.execute === !!def.endpoint) {
+        throw new Error(`defineTool "${def.name}": exactly one of execute / endpoint`);
+    }
+    return def;
+}
+export function toSpecs(tools) {
+    return tools.map(t => ({
+        name: t.name,
+        ...(t.description ? { description: t.description } : {}),
+        inputSchema: t.inputSchema,
+    }));
+}
+/** Top-level required / type / enum check. Returns null when valid,
+ *  a human-readable problem string when not. */
+export function checkInput(schema, input) {
+    const required = Array.isArray(schema['required']) ? schema['required'] : [];
+    for (const key of required) {
+        if (!(key in input))
+            return `missing required property "${key}"`;
+    }
+    const properties = (schema['properties'] ?? {});
+    for (const [key, value] of Object.entries(input)) {
+        const prop = properties[key];
+        if (!prop)
+            continue;
+        const type = prop['type'];
+        if (typeof type === 'string' && !typeMatches(type, value)) {
+            return `property "${key}" expected ${type}, got ${Array.isArray(value) ? 'array' : typeof value}`;
+        }
+        const allowed = prop['enum'];
+        if (Array.isArray(allowed) && !allowed.some(v => v === value)) {
+            return `property "${key}" not in enum [${allowed.join(', ')}]`;
+        }
+    }
+    return null;
+}
+function typeMatches(type, value) {
+    switch (type) {
+        case 'string': return typeof value === 'string';
+        case 'number': return typeof value === 'number';
+        case 'integer': return typeof value === 'number' && Number.isInteger(value);
+        case 'boolean': return typeof value === 'boolean';
+        case 'array': return Array.isArray(value);
+        case 'object': return typeof value === 'object' && value !== null && !Array.isArray(value);
+        case 'null': return value === null;
+        default: return true;
+    }
+}
+/** Run one tool call end to end: schema check → executor → string output.
+ *  Every failure path returns { isError: true } — the model sees the
+ *  problem and can retry; the loop never throws over a bad call. */
+export async function executeTool(tool, input, ctx) {
+    const problem = checkInput(tool.inputSchema, input);
+    if (problem)
+        return { output: `Invalid input: ${problem}`, isError: true };
+    try {
+        if (tool.execute) {
+            const result = await tool.execute(input, ctx);
+            return { output: typeof result === 'string' ? result : JSON.stringify(result ?? null) };
+        }
+        const endpoint = tool.endpoint;
+        const method = (endpoint.method ?? 'POST').toUpperCase();
+        // GET/HEAD carry no body (fetch throws on one); input rides the query.
+        const bodyless = method === 'GET' || method === 'HEAD';
+        const url = bodyless && Object.keys(input).length
+            ? `${endpoint.url}${endpoint.url.includes('?') ? '&' : '?'}${new URLSearchParams(input)}`
+            : endpoint.url;
+        const res = await fetch(url, {
+            method,
+            headers: { ...(bodyless ? {} : { 'content-type': 'application/json' }), ...endpoint.headers },
+            ...(bodyless ? {} : { body: JSON.stringify(input) }),
+            ...(ctx.signal ? { signal: ctx.signal } : {}),
+        });
+        const body = await res.text();
+        if (!res.ok)
+            return { output: `Endpoint error ${res.status}: ${body.slice(0, 500)}`, isError: true };
+        return { output: body };
+    }
+    catch (err) {
+        return { output: `Tool "${tool.name}" failed: ${err.message}`, isError: true };
+    }
+}
+//# sourceMappingURL=tools.js.map

package/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["src/tools.ts"],"names":[],"mappings":"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"}

package/workflow.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Workflows — named, declarative step sequences.
+ *
+ * A workflow is the routing cascade declared once: steps run in order;
+ * a step's `until` predicate accepts its result (stop, return it) or
+ * rejects it (fall through to the next step); a step without `until` is
+ * terminal — its result is always accepted. `when` skips a step entirely
+ * for this invocation. Scripted pipeline over per-turn re-decision: the
+ * sequence is data, so every consuming surface runs the SAME cascade.
+ */
+export interface WorkflowContext<TInput = unknown> {
+    input: TInput;
+    sessionId: string;
+    signal?: AbortSignal;
+    /** Step events land here (agent.run forwards them). */
+    emit?: (event: {
+        type: 'step';
+        workflow: string;
+        step: string;
+        data?: unknown;
+    }) => void;
+}
+export interface WorkflowStep<TInput = unknown, TResult = unknown> {
+    name?: string;
+    run: (ctx: WorkflowContext<TInput>) => TResult | Promise<TResult>;
+    /** Accept predicate: true → this result is the workflow's result.
+     *  Absent → terminal step, always accepted. */
+    until?: (result: TResult) => boolean;
+    /** Skip guard: false → step doesn't run this invocation. */
+    when?: (ctx: WorkflowContext<TInput>) => boolean;
+}
+export interface Workflow<TInput = unknown, TResult = unknown> {
+    name: string;
+    steps: Array<WorkflowStep<TInput, TResult>>;
+}
+export interface WorkflowResult<TResult = unknown> {
+    result: TResult | undefined;
+    /** Name/index of the accepting step, or null when every step fell through. */
+    step: string | null;
+    accepted: boolean;
+}
+export declare function defineWorkflow<TInput = unknown, TResult = unknown>(name: string, steps: Array<WorkflowStep<TInput, TResult>>): Workflow<TInput, TResult>;
+export declare function runWorkflow<TInput, TResult>(workflow: Workflow<TInput, TResult>, ctx: WorkflowContext<TInput>): Promise<WorkflowResult<TResult>>;
+//# sourceMappingURL=workflow.d.ts.map

package/workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,uDAAuD;IACvD,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1F;AAED,MAAM,WAAW,YAAY,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,CAAC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE;mDAC+C;IAC/C,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC;IACrC,4DAA4D;IAC5D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC;CAClD;AAED,MAAM,WAAW,QAAQ,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc,CAAC,OAAO,GAAG,OAAO;IAC/C,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,cAAc,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,EAChE,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAC1C,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAG3B;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,OAAO,EAC/C,QAAQ,EAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,GAAG,EAAE,eAAe,CAAC,MAAM,CAAC,GAC3B,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAiBlC"}

package/workflow.js

@@ -0,0 +1,36 @@
+/**
+ * Workflows — named, declarative step sequences.
+ *
+ * A workflow is the routing cascade declared once: steps run in order;
+ * a step's `until` predicate accepts its result (stop, return it) or
+ * rejects it (fall through to the next step); a step without `until` is
+ * terminal — its result is always accepted. `when` skips a step entirely
+ * for this invocation. Scripted pipeline over per-turn re-decision: the
+ * sequence is data, so every consuming surface runs the SAME cascade.
+ */
+export function defineWorkflow(name, steps) {
+    if (!steps.length)
+        throw new Error(`defineWorkflow "${name}": at least one step`);
+    return { name, steps };
+}
+export async function runWorkflow(workflow, ctx) {
+    let last;
+    for (let i = 0; i < workflow.steps.length; i++) {
+        const step = workflow.steps[i];
+        const stepName = step.name ?? `step-${i + 1}`;
+        if (step.when && !step.when(ctx))
+            continue;
+        last = await step.run(ctx);
+        const accepted = step.until ? step.until(last) : true;
+        ctx.emit?.({
+            type: 'step',
+            workflow: workflow.name,
+            step: stepName,
+            data: { accepted },
+        });
+        if (accepted)
+            return { result: last, step: stepName, accepted: true };
+    }
+    return { result: last, step: null, accepted: false };
+}
+//# sourceMappingURL=workflow.js.map

package/workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow.js","sourceRoot":"","sources":["src/workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAgCH,MAAM,UAAU,cAAc,CAC5B,IAAY,EACZ,KAA2C;IAE3C,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,sBAAsB,CAAC,CAAC;IAClF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAmC,EACnC,GAA4B;IAE5B,IAAI,IAAyB,CAAC;IAC9B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/C,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC;QAChC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QAC9C,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;YAAE,SAAS;QAC3C,IAAI,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC3B,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACtD,GAAG,CAAC,IAAI,EAAE,CAAC;YACT,IAAI,EAAE,MAAM;YACZ,QAAQ,EAAE,QAAQ,CAAC,IAAI;YACvB,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,EAAE,QAAQ,EAAE;SACnB,CAAC,CAAC;QACH,IAAI,QAAQ;YAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;IACxE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACvD,CAAC"}