@xandout/libra-harness 0.1.8

package/dist/handle.d.ts

@@ -0,0 +1,56 @@
+import type { AgentResponse } from './context.js';
+/**
+ * Controller for a running agent turn.
+ *
+ * Returned by {@link Agent.run}. The handle is **thenable** — you can
+ * `await` it directly to get the final {@link AgentResponse} — but it also
+ * exposes discrete controls for steering and halting the turn:
+ *
+ * ```typescript
+ * const handle = agent.run({ message: 'Research this' })
+ *
+ * // Steer mid-turn (injects a user message before the next LLM iteration)
+ * handle.steer('Focus on the financial aspects')
+ *
+ * // Halt mid-turn (cancels in-flight model calls, stops the loop)
+ * handle.halt('user cancelled')
+ *
+ * // Or just await the result
+ * const result = await handle
+ * ```
+ *
+ * Each call to `agent.run()` returns its own independent handle. This means
+ * multiple turns can run concurrently without clobbering each other's
+ * steering/halting state.
+ */
+export interface RunHandle extends PromiseLike<AgentResponse> {
+    /** The AbortSignal for this turn. Passed to model calls and tools. */
+    readonly signal: AbortSignal;
+    /** Whether the turn is still running. */
+    readonly isRunning: boolean;
+    /**
+     * Inject a steering message into the turn.
+     *
+     * The message is added as a `user` message before the next LLM iteration,
+     * allowing the caller to redirect the agent mid-turn. No-op if the turn
+     * has already completed.
+     */
+    steer(message: string): void;
+    /**
+     * Halt the turn.
+     *
+     * Aborts any in-flight model call and stops the turn loop. The turn
+     * resolves with `finishReason: 'halted'`. No-op if the turn has already
+     * completed.
+     *
+     * **Propagation**: Halting cancels in-flight `fetch` calls to the model
+     * and races against running tool executions. Tools that receive the
+     * AbortSignal via {@link ToolContext.signal} should check it cooperatively
+     * to clean up resources. A tool that ignores the signal may continue
+     * running in the background, but the harness will not wait for it.
+     */
+    halt(reason?: string): void;
+    /** The promise that resolves with the final response. */
+    readonly done: Promise<AgentResponse>;
+}
+//# sourceMappingURL=handle.d.ts.map

package/dist/handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,SAAU,SAAQ,WAAW,CAAC,aAAa,CAAC;IAC3D,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAE5B;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAE7B;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAE5B,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,aAAa,CAAC,CAAC;CACvC"}

package/dist/handle.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=handle.js.map

package/dist/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":""}

package/dist/hooks.d.ts

@@ -0,0 +1,98 @@
+import type { TurnContext } from './context.js';
+import type { ModelRequest, ModelResponse } from './model.js';
+import type { ToolCall, ToolResult } from './types.js';
+/**
+ * Lifecycle stages where hooks can participate.
+ *
+ * The exact set may evolve; these map to the turn execution model:
+ *
+ * ```
+ * beforeTurn → beforeContext → [beforeLLM → afterLLM → (beforeTool → afterTool)*]* → beforeResponse → afterTurn
+ *
+ * onError fires when any error is thrown during the turn (model error, hook
+ * error, etc.). An onError hook can recover by returning
+ * `{ skip: true, value: AgentResponse }`.
+ * ```
+ */
+export type HookName = 'beforeTurn' | 'beforeContext' | 'beforeLLM' | 'afterLLM' | 'beforeTool' | 'afterTool' | 'beforeResponse' | 'afterTurn' | 'onError';
+/**
+ * Data passed to a hook handler.
+ *
+ * `turn` is always present. Other fields are populated depending on the
+ * stage so extensions can inspect what they need.
+ */
+export interface HookContext {
+    /** The mutable turn state. */
+    turn: TurnContext;
+    /** Populated on beforeLLM/afterLLM. */
+    modelRequest?: ModelRequest;
+    /** Populated on afterLLM. */
+    modelResponse?: ModelResponse;
+    /** Populated on beforeTool/afterTool. */
+    toolCall?: ToolCall;
+    /** Populated on afterTool (and beforeTool if a prior hook set it). */
+    toolResult?: ToolResult;
+    /** Populated on onError — the error that was thrown. */
+    error?: unknown;
+}
+/**
+ * What a hook can return.
+ *
+ * - `skip: true` — short-circuit remaining hooks **and** the default
+ *   action for this stage. The `value` (if provided) is used as the
+ *   stage result where applicable.
+ * - `value` — stage-specific override (e.g. a {@link ModelResponse} for
+ *   beforeLLM, a {@link ToolResult} for beforeTool).
+ */
+export interface HookResult {
+    skip?: boolean;
+    value?: unknown;
+}
+/**
+ * A hook handler. May mutate the context and/or return a {@link HookResult}.
+ */
+export type HookHandler = (ctx: HookContext) => Promise<HookResult | void>;
+/**
+ * An entry in the hook registry.
+ */
+export interface HookEntry {
+    /** Name of the extension that registered this hook (for error reporting). */
+    extensionName: string;
+    handler: HookHandler;
+    /**
+     * Priority of the extension that registered this hook. Higher = runs
+     * first. Ties are broken by registration order (stable sort).
+     * Default: 0.
+     */
+    priority: number;
+}
+/**
+ * Ordered registry of hooks per lifecycle stage.
+ *
+ * Hooks execute in priority order within each stage (higher priority
+ * first), with registration order as the tiebreaker (stable sort).
+ * A hook returning `{ skip: true }` short-circuits remaining hooks
+ * in that stage.
+ */
+export declare class HookRegistry {
+    private readonly hooks;
+    /**
+     * Register a hook at a stage.
+     *
+     * @param priority Higher = runs first. Ties keep registration order.
+     *   Default: 0.
+     */
+    register(stage: HookName, extensionName: string, handler: HookHandler, priority?: number): void;
+    /**
+     * Get all hooks for a stage, sorted by priority (descending) then
+     * registration order (stable). This sort is computed on each call so
+     * that hooks registered after an `unregister()` stay correctly
+     * ordered.
+     */
+    entries(stage: HookName): HookEntry[];
+    /** Whether any hooks are registered at a stage. */
+    has(stage: HookName): boolean;
+    /** Remove all hooks registered by an extension (across all stages). */
+    unregister(extensionName: string): void;
+}
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC9D,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,QAAQ,GAChB,YAAY,GACZ,eAAe,GACf,WAAW,GACX,UAAU,GACV,YAAY,GACZ,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,SAAS,CAAC;AAEd;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,8BAA8B;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,uCAAuC;IACvC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,6BAA6B;IAC7B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,yCAAyC;IACzC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,sEAAsE;IACtE,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,6EAA6E;IAC7E,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAE1D;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,SAAI,GAAG,IAAI,CAIzF;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,EAAE,CAMpC;IAED,mDAAmD;IACnD,GAAG,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAE5B;IAED,uEAAuE;IACvE,UAAU,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAStC;CACF"}

package/dist/hooks.js

@@ -0,0 +1,53 @@
+/**
+ * Ordered registry of hooks per lifecycle stage.
+ *
+ * Hooks execute in priority order within each stage (higher priority
+ * first), with registration order as the tiebreaker (stable sort).
+ * A hook returning `{ skip: true }` short-circuits remaining hooks
+ * in that stage.
+ */
+export class HookRegistry {
+    hooks = new Map();
+    /**
+     * Register a hook at a stage.
+     *
+     * @param priority Higher = runs first. Ties keep registration order.
+     *   Default: 0.
+     */
+    register(stage, extensionName, handler, priority = 0) {
+        const entries = this.hooks.get(stage) ?? [];
+        entries.push({ extensionName, handler, priority });
+        this.hooks.set(stage, entries);
+    }
+    /**
+     * Get all hooks for a stage, sorted by priority (descending) then
+     * registration order (stable). This sort is computed on each call so
+     * that hooks registered after an `unregister()` stay correctly
+     * ordered.
+     */
+    entries(stage) {
+        const entries = this.hooks.get(stage);
+        if (!entries || entries.length <= 1)
+            return entries ?? [];
+        // Stable sort by priority descending. Array.prototype.sort is
+        // stable in V8 (Node 12+) and all modern engines.
+        return [...entries].sort((a, b) => b.priority - a.priority);
+    }
+    /** Whether any hooks are registered at a stage. */
+    has(stage) {
+        return (this.hooks.get(stage)?.length ?? 0) > 0;
+    }
+    /** Remove all hooks registered by an extension (across all stages). */
+    unregister(extensionName) {
+        for (const [stage, entries] of this.hooks) {
+            const filtered = entries.filter((e) => e.extensionName !== extensionName);
+            if (filtered.length === 0) {
+                this.hooks.delete(stage);
+            }
+            else {
+                this.hooks.set(stage, filtered);
+            }
+        }
+    }
+}
+//# sourceMappingURL=hooks.js.map

package/dist/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAmFA;;;;;;;GAOG;AACH,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE1D;;;;;OAKG;IACH,QAAQ,CAAC,KAAe,EAAE,aAAqB,EAAE,OAAoB,EAAE,QAAQ,GAAG,CAAC;QACjF,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5C,OAAO,CAAC,IAAI,CAAC,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,KAAe;QACrB,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC;YAAE,OAAO,OAAO,IAAI,EAAE,CAAC;QAC1D,8DAA8D;QAC9D,kDAAkD;QAClD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC;IAC9D,CAAC;IAED,mDAAmD;IACnD,GAAG,CAAC,KAAe;QACjB,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;IAClD,CAAC;IAED,uEAAuE;IACvE,UAAU,CAAC,aAAqB;QAC9B,KAAK,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1C,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,KAAK,aAAa,CAAC,CAAC;YAC1E,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC3B,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export type { Role, Message, MessageContent, TextContentPart, FileContentPart, FileContentData, ToolCall, ToolResult, ToolDefinition, } from './types.js';
+export { messageContentToText, hasFileContent } from './types.js';
+export { LibraError, ModelError, ToolError, HookError, HaltedError, MaxIterationsError, } from './errors.js';
+export type { Model, ModelRequest, ModelResponse, ModelDelta, FinishReason } from './model.js';
+export { AISdkModel } from './ai-sdk-model.js';
+export type { Tool, ToolContext } from './tool.js';
+export { toToolDefinition, createAgentTool } from './tool.js';
+export type { AgentToolOptions } from './tool.js';
+export type { AgentRequest, AgentResponse, TurnContext, TurnFinishReason } from './context.js';
+export type { HookName, HookContext, HookResult, HookHandler, HookEntry } from './hooks.js';
+export { HookRegistry } from './hooks.js';
+export type { Extension } from './extension.js';
+export { Agent } from './agent.js';
+export type { AgentConfig, ErrorPolicy, ErrorPolicyContext } from './agent.js';
+export type { RunHandle } from './handle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,IAAI,EACJ,OAAO,EACP,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,QAAQ,EACR,UAAU,EACV,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAGlE,OAAO,EACL,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAGrB,YAAY,EAAE,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/F,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,YAAY,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC9D,YAAY,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlD,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAG/F,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAG1C,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAG/E,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { messageContentToText, hasFileContent } from './types.js';
+// Errors
+export { LibraError, ModelError, ToolError, HookError, HaltedError, MaxIterationsError, } from './errors.js';
+export { AISdkModel } from './ai-sdk-model.js';
+export { toToolDefinition, createAgentTool } from './tool.js';
+export { HookRegistry } from './hooks.js';
+// Agent
+export { Agent } from './agent.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAElE,SAAS;AACT,OAAO,EACL,UAAU,EACV,UAAU,EACV,SAAS,EACT,SAAS,EACT,WAAW,EACX,kBAAkB,GACnB,MAAM,aAAa,CAAC;AAIrB,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAI/C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAQ9D,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAK1C,QAAQ;AACR,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/model.d.ts

@@ -0,0 +1,75 @@
+import type { Message, ToolDefinition } from './types.js';
+/**
+ * A partial output delta from a streaming model call.
+ *
+ * Emitted via {@link ModelRequest.onDelta} during generation. The core
+ * does not interpret these — it simply forwards the callback to the
+ * model provider. Extensions can subscribe by setting `onDelta` on
+ * `ctx.modelRequest` in a `beforeLLM` hook.
+ */
+export interface ModelDelta {
+    /** What kind of delta this is. */
+    type: 'text' | 'reasoning' | 'tool-input';
+    /** The partial content for this delta. */
+    content: string;
+    /** Tool call ID (only for `tool-input` deltas). */
+    toolCallId?: string;
+    /** Tool name (only for `tool-input` deltas). */
+    toolName?: string;
+}
+/**
+ * Request to a model provider.
+ *
+ * The provider translates this into whatever wire format it speaks.
+ * If `onDelta` is provided, the provider should stream partial output
+ * via that callback in addition to returning the final {@link ModelResponse}.
+ */
+export interface ModelRequest {
+    messages: Message[];
+    tools?: ToolDefinition[];
+    /** System instructions prepended to the conversation. */
+    systemPrompt?: string;
+    temperature?: number;
+    maxTokens?: number;
+    signal?: AbortSignal;
+    /**
+     * Optional callback for streaming deltas.
+     *
+     * When set, the model provider should use its streaming API and
+     * invoke this callback for each text/reasoning/tool-input delta.
+     * The final assembled {@link ModelResponse} is still returned.
+     */
+    onDelta?: (delta: ModelDelta) => void;
+}
+/** Why the model stopped generating. */
+export type FinishReason = 'stop' | 'tool_calls' | 'length' | 'content_filter';
+/** Response from a model provider. */
+export interface ModelResponse {
+    /** The assistant message. May contain `toolCalls` when the model requests tools. */
+    message: Message;
+    finishReason: FinishReason;
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        /** Prompt tokens served from the provider's cache (cache read/hit). */
+        cachedPromptTokens?: number;
+        /** Prompt tokens written to the provider's cache for future reuse. */
+        cacheWriteTokens?: number;
+        /** Reasoning/thinking tokens if the provider reports them separately. */
+        reasoningTokens?: number;
+    };
+}
+/**
+ * Abstract model interface.
+ *
+ * Implementations are responsible for translating libra's {@link Message}
+ * format to/from their wire format and for surfacing tool-call decisions
+ * via {@link Message.toolCalls}.
+ *
+ * The built-in {@link AISdkModel} wraps any Vercel AI SDK provider. You can
+ * also implement this interface directly for custom providers.
+ */
+export interface Model {
+    generate(request: ModelRequest): Promise<ModelResponse>;
+}
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,kCAAkC;IAClC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;IAC1C,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IACzB,yDAAyD;IACzD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC;AAED,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,CAAC;AAE/E,sCAAsC;AACtC,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,CAAC,EAAE;QACN,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,uEAAuE;QACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,sEAAsE;QACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,yEAAyE;QACzE,eAAe,CAAC,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACzD"}

package/dist/model.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=model.js.map

package/dist/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":""}

package/dist/tool.d.ts

@@ -0,0 +1,78 @@
+import type { ToolDefinition, ToolResult } from './types.js';
+import type { Agent } from './agent.js';
+/** Context passed to a tool's execute function. */
+export interface ToolContext {
+    /** AbortSignal — aborted when the turn is halted. */
+    signal: AbortSignal;
+    /** Shared turn metadata bag. Extensions may read/write here. */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A tool the agent can call.
+ *
+ * `parameters` is a JSON Schema object (OpenAI function parameters format).
+ * `execute` receives parsed arguments and a context.
+ *
+ * Set `external: true` for tools whose calls should be returned to the caller
+ * instead of executed internally. When the model calls an external tool, the
+ * agent breaks its continuation loop and returns the tool call in the response
+ * with `finishReason: 'tool_calls'`. The caller is responsible for executing
+ * the tool and sending the result back in a subsequent request.
+ */
+export interface Tool {
+    name: string;
+    description?: string;
+    parameters: Record<string, unknown>;
+    execute(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolResult>;
+    /**
+     * When true, the agent does not execute this tool. Instead, the tool call
+     * is returned to the caller via `AgentResponse.toolCalls` with
+     * `finishReason: 'tool_calls'`. The caller executes the tool and sends
+     * the result back as a `tool` message in a follow-up request.
+     */
+    external?: boolean;
+}
+/** Convert a libra {@link Tool} to an OpenAI-compatible {@link ToolDefinition}. */
+export declare function toToolDefinition(tool: Tool): ToolDefinition;
+/**
+ * Options for {@link createAgentTool}.
+ */
+export interface AgentToolOptions {
+    /** Tool name as seen by the LLM. */
+    name: string;
+    /** Tool description as seen by the LLM. */
+    description: string;
+    /** JSON Schema for the tool's single `message` parameter. */
+    parameters?: Record<string, unknown>;
+    /** System prompt override for the inner agent's turns. */
+    systemPrompt?: string;
+    /** Max iterations for the inner agent's turns. */
+    maxIterations?: number;
+}
+/**
+ * Wrap an {@link Agent} as a {@link Tool} so an outer agent can delegate to it.
+ *
+ * The inner agent runs fully in-process. The outer agent's `AbortSignal` and
+ * `metadata` are forwarded to the inner agent's turn, so:
+ *
+ * - If the outer turn is **halted**, the inner agent is also halted.
+ * - The inner agent **shares metadata** with the outer turn (e.g. session ID,
+ *   trace IDs, user context).
+ * - If the inner agent is **halted** (via its own hooks or signal), the tool
+ *   returns an error result so the outer agent can react.
+ *
+ * @example
+ * ```typescript
+ * const researchTool = createAgentTool(researchAgent, {
+ *   name: 'research',
+ *   description: 'Delegate a research question to a research agent',
+ * })
+ *
+ * const outerAgent = new Agent({
+ *   model,
+ *   tools: [researchTool],
+ * })
+ * ```
+ */
+export declare function createAgentTool(agent: Agent, options: AgentToolOptions): Tool;
+//# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,qDAAqD;IACrD,MAAM,EAAE,WAAW,CAAC;IACpB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAC9E;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,mFAAmF;AACnF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,cAAc,CAS3D;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,oCAAoC;IACpC,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kDAAkD;IAClD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,gBAAgB,GAAG,IAAI,CA0C7E"}

package/dist/tool.js

@@ -0,0 +1,78 @@
+/** Convert a libra {@link Tool} to an OpenAI-compatible {@link ToolDefinition}. */
+export function toToolDefinition(tool) {
+    return {
+        type: 'function',
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters,
+        },
+    };
+}
+/**
+ * Wrap an {@link Agent} as a {@link Tool} so an outer agent can delegate to it.
+ *
+ * The inner agent runs fully in-process. The outer agent's `AbortSignal` and
+ * `metadata` are forwarded to the inner agent's turn, so:
+ *
+ * - If the outer turn is **halted**, the inner agent is also halted.
+ * - The inner agent **shares metadata** with the outer turn (e.g. session ID,
+ *   trace IDs, user context).
+ * - If the inner agent is **halted** (via its own hooks or signal), the tool
+ *   returns an error result so the outer agent can react.
+ *
+ * @example
+ * ```typescript
+ * const researchTool = createAgentTool(researchAgent, {
+ *   name: 'research',
+ *   description: 'Delegate a research question to a research agent',
+ * })
+ *
+ * const outerAgent = new Agent({
+ *   model,
+ *   tools: [researchTool],
+ * })
+ * ```
+ */
+export function createAgentTool(agent, options) {
+    return {
+        name: options.name,
+        description: options.description,
+        parameters: options.parameters ?? {
+            type: 'object',
+            properties: {
+                message: {
+                    type: 'string',
+                    description: 'The message to send to the agent.',
+                },
+            },
+            required: ['message'],
+        },
+        async execute(args, ctx) {
+            const message = args.message != null
+                ? String(args.message)
+                : args.query != null
+                    ? String(args.query)
+                    : JSON.stringify(args);
+            const result = await agent.run({
+                message,
+                signal: ctx.signal,
+                metadata: ctx.metadata,
+                ...(options.systemPrompt && { systemPrompt: options.systemPrompt }),
+                ...(options.maxIterations !== undefined && { maxIterations: options.maxIterations }),
+            });
+            if (result.finishReason === 'halted') {
+                return {
+                    toolCallId: '',
+                    content: 'Subagent was halted.',
+                    isError: true,
+                };
+            }
+            return {
+                toolCallId: '',
+                content: result.message,
+            };
+        },
+    };
+}
+//# sourceMappingURL=tool.js.map

package/dist/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAqCA,mFAAmF;AACnF,MAAM,UAAU,gBAAgB,CAAC,IAAU;IACzC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B;KACF,CAAC;AACJ,CAAC;AAkBD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,eAAe,CAAC,KAAY,EAAE,OAAyB;IACrE,OAAO;QACL,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI;YAChC,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,OAAO,EAAE;oBACP,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,mCAAmC;iBACjD;aACF;YACD,QAAQ,EAAE,CAAC,SAAS,CAAC;SACtB;QACD,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG;YACrB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI;gBAClC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;gBACtB,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI;oBAClB,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC;oBACpB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC;gBAC7B,OAAO;gBACP,MAAM,EAAE,GAAG,CAAC,MAAM;gBAClB,QAAQ,EAAE,GAAG,CAAC,QAAQ;gBACtB,GAAG,CAAC,OAAO,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE,CAAC;gBACnE,GAAG,CAAC,OAAO,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,aAAa,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC;aACrF,CAAC,CAAC;YAEH,IAAI,MAAM,CAAC,YAAY,KAAK,QAAQ,EAAE,CAAC;gBACrC,OAAO;oBACL,UAAU,EAAE,EAAE;oBACd,OAAO,EAAE,sBAAsB;oBAC/B,OAAO,EAAE,IAAI;iBACd,CAAC;YACJ,CAAC;YAED,OAAO;gBACL,UAAU,EAAE,EAAE;gBACd,OAAO,EAAE,MAAM,CAAC,OAAO;aACxB,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Core message and content types.
+ *
+ * These are libra's own types. The model provider translates to/from
+ * the wire format of whatever API it targets (OpenAI-compatible, etc.).
+ */
+/** A single tool call requested by the model. */
+export interface ToolCall {
+    /** Unique id assigned by the model, used to correlate tool results. */
+    id: string;
+    /** The tool/function name to invoke. */
+    name: string;
+    /** JSON-encoded arguments string (matches OpenAI tool_call.function.arguments). */
+    arguments: string;
+}
+/** The result of executing a tool call. */
+export interface ToolResult {
+    /** Correlates with {@link ToolCall.id}. */
+    toolCallId: string;
+    /** Human/machine readable result content. */
+    content: string;
+    /** When true, the result represents a failure the model should see as an error. */
+    isError?: boolean;
+}
+/** Conversation participant role. */
+export type Role = 'system' | 'user' | 'assistant' | 'tool';
+/** Text content within a multimodal message. */
+export interface TextContentPart {
+    type: 'text';
+    text: string;
+}
+/** Provider-independent file data. */
+export type FileContentData = {
+    type: 'data';
+    data: string | Uint8Array;
+} | {
+    type: 'url';
+    url: string;
+} | {
+    type: 'text';
+    text: string;
+};
+/** A file attachment, including images, documents, audio, and video. */
+export interface FileContentPart {
+    type: 'file';
+    mediaType: string;
+    filename?: string;
+    data: FileContentData;
+}
+/** Message content. Strings remain supported as the text-only shorthand. */
+export type MessageContent = string | Array<TextContentPart | FileContentPart>;
+/** Convert message content to a text representation for logs and text-only extensions. */
+export declare function messageContentToText(content: MessageContent): string;
+/** Whether message content contains at least one file attachment. */
+export declare function hasFileContent(content: MessageContent, mediaTypePrefix?: string): boolean;
+/**
+ * A single conversation message.
+ *
+ * - `assistant` messages may carry `toolCalls` when the model requests tools.
+ * - `tool` messages carry a single `toolCallId` linking back to the call
+ *   and `content` holds the tool result.
+ */
+export interface Message {
+    role: Role;
+    /** Text or multimodal content. For `tool` messages this is the tool result. */
+    content: MessageContent;
+    /** Present on assistant messages that request tool execution. */
+    toolCalls?: ToolCall[];
+    /** Present on tool messages — links to the originating tool call id. */
+    toolCallId?: string;
+    /** Optional tool name for tool messages. */
+    name?: string;
+}
+/** JSON Schema describing a tool's parameters (OpenAI function format). */
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters: Record<string, unknown>;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,iDAAiD;AACjD,MAAM,WAAW,QAAQ;IACvB,uEAAuE;IACvE,EAAE,EAAE,MAAM,CAAC;IACX,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,2CAA2C;AAC3C,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qCAAqC;AACrC,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sCAAsC;AACtC,MAAM,MAAM,eAAe,GACvB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnC,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,eAAe,CAAC;CACvB;AAED,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,KAAK,CAAC,eAAe,GAAG,eAAe,CAAC,CAAC;AAE/E,0FAA0F;AAC1F,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,cAAc,GAAG,MAAM,CAMpE;AAED,qEAAqE;AACrE,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAIzF;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,IAAI,CAAC;IACX,+EAA+E;IAC/E,OAAO,EAAE,cAAc,CAAC;IACxB,iEAAiE;IACjE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,2EAA2E;AAC3E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH"}

package/dist/types.js

@@ -0,0 +1,21 @@
+/**
+ * Core message and content types.
+ *
+ * These are libra's own types. The model provider translates to/from
+ * the wire format of whatever API it targets (OpenAI-compatible, etc.).
+ */
+/** Convert message content to a text representation for logs and text-only extensions. */
+export function messageContentToText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.map((part) => {
+        if (part.type === 'text')
+            return part.text;
+        return part.filename ? `[File: ${part.filename} (${part.mediaType})]` : `[File: ${part.mediaType}]`;
+    }).join('\n');
+}
+/** Whether message content contains at least one file attachment. */
+export function hasFileContent(content, mediaTypePrefix) {
+    return Array.isArray(content) && content.some((part) => part.type === 'file' && (!mediaTypePrefix || part.mediaType.startsWith(mediaTypePrefix)));
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAgDH,0FAA0F;AAC1F,MAAM,UAAU,oBAAoB,CAAC,OAAuB;IAC1D,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAChD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC1B,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC;QAC3C,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,QAAQ,KAAK,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,SAAS,GAAG,CAAC;IACtG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,cAAc,CAAC,OAAuB,EAAE,eAAwB;IAC9E,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CACrD,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,CAAC,CAAC,eAAe,IAAI,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC,CACzF,CAAC;AACJ,CAAC"}