@halo-sdk/core 1.0.0 → 1.0.1

package/dist/model-adapter.d.ts

@@ -1,4 +1,4 @@
-import type { ChatMessage, ToolCall, ToolSpec, Usage } from "./types.js";
+import type { ChatMessage, ToolCall, ToolSpec, Usage, ResponseFormat } from "./types.js";
 import type { TurnChunk } from "./session.js";
 export interface ModelCapabilities {
     toolUse: boolean;
@@ -9,22 +9,34 @@ export interface PricingInfo {
     inputPricePer1k: number;
     cachedInputPricePer1k: number;
 }
+/** Per-request model parameters. Overrides agent-level defaults. */
+export interface ModelCallOptions {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    maxTokens?: number;
+    seed?: number;
+    stop?: string[];
+}
+export { type ResponseFormat } from "./types.js";
+export interface ChatParams {
+    prefix: ChatMessage[];
+    history: ChatMessage[];
+    tools?: ToolSpec[];
+    responseFormat?: ResponseFormat;
+    options?: ModelCallOptions;
+}
 export interface ModelAdapter {
     /**
      * Send a chat request with separated stable prefix and dynamic history.
-     *
-     * The separation lets adapters apply provider-specific caching strategies:
-     * - DeepSeek / OpenAI-compatible: concat `[...prefix, ...history]` (prefix caching)
-     * - Anthropic: mark prefix messages with `cache_control` breakpoints
-     * - Gemini: use prefix to create/manage a `CachedContent` resource
      */
-    chat(prefix: ChatMessage[], history: ChatMessage[], tools?: ToolSpec[]): Promise<{
+    chat(params: ChatParams): Promise<{
         content: string;
         toolCalls: ToolCall[];
         usage: Usage;
     }>;
     /** Stream variant with the same prefix/history separation. */
-    stream(prefix: ChatMessage[], history: ChatMessage[], tools?: ToolSpec[]): AsyncGenerator<TurnChunk>;
+    stream(params: ChatParams): AsyncGenerator<TurnChunk>;
     readonly modelId: string;
     readonly contextWindow: number;
     readonly capabilities: ModelCapabilities;

package/dist/model-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"model-adapter.d.ts","sourceRoot":"","sources":["../src/model-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,IAAI,CACF,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,WAAW,EAAE,EACtB,KAAK,CAAC,EAAE,QAAQ,EAAE,GACjB,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;IAErE,8DAA8D;IAC9D,MAAM,CACJ,MAAM,EAAE,WAAW,EAAE,EACrB,OAAO,EAAE,WAAW,EAAE,EACtB,KAAK,CAAC,EAAE,QAAQ,EAAE,GACjB,cAAc,CAAC,SAAS,CAAC,CAAC;IAE7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAE/B;;;;OAIG;IACH,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACzD"}
+{"version":3,"file":"model-adapter.d.ts","sourceRoot":"","sources":["../src/model-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAE9C,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,OAAO,EAAE,WAAW,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,gBAAgB,CAAC;CAC5B;AAED,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,QAAQ,EAAE,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC;IAE5F,8DAA8D;IAC9D,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,cAAc,CAAC,SAAS,CAAC,CAAC;IAEtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,iBAAiB,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC;IAE/B;;;;OAIG;IACH,SAAS,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE,CAAC;CACzD"}

package/dist/sandbox.d.ts

@@ -0,0 +1,78 @@
+import type { ToolDefinition } from "./types.js";
+export interface Sandbox {
+    /** Read file contents as UTF-8. */
+    readFile(path: string): Promise<string>;
+    /** Write or overwrite a file. Creates parent directories automatically. */
+    writeFile(path: string, content: string): Promise<void>;
+    /** List directory entries. */
+    readdir(path: string): Promise<{
+        name: string;
+        isDirectory: boolean;
+    }[]>;
+    /** Check if a path exists. */
+    exists(path: string): Promise<boolean>;
+    /** Execute a command with structured arguments (no shell). */
+    exec?(command: string, args: string[], opts?: ExecOptions): Promise<ExecResult>;
+    /** Execute a shell command string. Requires `allowShell: true`. */
+    execShell?(command: string, opts?: ExecShellOptions): Promise<ExecResult>;
+    /** Kill all background processes and clean up. Idempotent. */
+    dispose(): Promise<void>;
+    /** Working directory — all relative paths resolve against this. */
+    readonly cwd: string;
+    /** Whether this sandbox supports command execution. */
+    readonly hasExec: boolean;
+    /**
+     * Auto-generate tool definitions matching this sandbox's capabilities.
+     * VirtualSandbox: { readFile, writeFile, readdir }
+     * ContainerSandbox: + { exec, execShell }
+     */
+    tools(): Record<string, ToolDefinition>;
+}
+export interface ExecOptions {
+    /** Working directory for the command (relative to sandbox root). */
+    cwd?: string;
+    /** Additional environment variables. */
+    env?: Record<string, string>;
+    /** Timeout in ms. Default 30s. */
+    timeout?: number;
+    /** If true, returns ProcessHandle instead of waiting. */
+    background?: boolean;
+    /** Expose a port (0 = auto-assign). Requires background: true. */
+    exposePort?: number;
+    /** Host to bind. Default "127.0.0.1". */
+    bindHost?: string;
+    /** Auto-kill after ms of inactivity. Default 300_000 (5 min). */
+    portTTL?: number;
+    /** Authentication for exposed port. */
+    portAuth?: {
+        type: "token";
+        value: string;
+    };
+}
+export interface ExecShellOptions extends ExecOptions {
+    /** Must be explicitly true to use shell mode. */
+    allowShell: boolean;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+export interface ProcessHandle {
+    pid: number;
+    /** URL when exposePort was set. */
+    url?: string;
+    stdout: AsyncIterable<string>;
+    stderr: AsyncIterable<string>;
+    kill(signal?: string): Promise<void>;
+    wait(): Promise<ExecResult>;
+}
+export declare class SandboxError extends Error {
+    code: string;
+    constructor(message: string, code: string);
+}
+/** Second argument passed to tool execute() when the agent has a sandbox. */
+export interface ToolContext {
+    sandbox: Sandbox;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/dist/sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,WAAW,OAAO;IACtB,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC,2EAA2E;IAC3E,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD,8BAA8B;IAC9B,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,OAAO,CAAA;KAAE,EAAE,CAAC,CAAC;IAEzE,8BAA8B;IAC9B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvC,8DAA8D;IAC9D,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAEhF,mEAAmE;IACnE,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IAE1E,8DAA8D;IAC9D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,mEAAmE;IACnE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACzC;AAID,MAAM,WAAW,WAAW;IAC1B,oEAAoE;IACpE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,kCAAkC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,iDAAiD;IACjD,UAAU,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAC7B;AAID,qBAAa,YAAa,SAAQ,KAAK;IACrC,IAAI,EAAE,MAAM,CAAC;gBACD,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAK1C;AAID,6EAA6E;AAC7E,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;CAClB"}

package/dist/session-impl.d.ts

@@ -1,5 +1,6 @@
 import type { ChatMessage, ToolCall, ToolDefinition, ToolSpec } from "./types.js";
-import type { TurnResult, TurnChunk, ToolResult, SessionStats, HaloAgentOptions } from "./session.js";
+import type { TurnResult, TurnChunk, ToolResult, SessionStats, HaloAgentOptions, StreamTextOptions, StreamTextResult, GenerateObjectOptions, GenerateObjectResult } from "./session.js";
+import type { ModelCallOptions } from "./model-adapter.js";
 /** Internal implementation. Exported for testing only. */
 export declare class HaloAgentImpl {
     private _adapter;
@@ -11,9 +12,11 @@ export declare class HaloAgentImpl {
     private _stats;
     private _keepAliveTimer;
     private _toolExecutors;
+    private _modelDefaults;
+    private _sandbox;
     constructor(opts: HaloAgentOptions);
     get stats(): Readonly<SessionStats>;
-    run(input: string, opts?: {
+    generateText(input: string, opts?: {
         maxSteps?: number;
         onToolCall?: (call: ToolCall) => Promise<ToolResult>;
         onStep?: (s: {
@@ -21,10 +24,10 @@ export declare class HaloAgentImpl {
             content: string;
             toolCalls: ToolCall[];
         }) => void;
-    }): Promise<TurnResult>;
-    send(input: string): Promise<TurnResult>;
-    stream(input: string): AsyncGenerator<TurnChunk>;
-    submitToolResult(result: ToolResult): Promise<TurnResult>;
+    } & ModelCallOptions): Promise<TurnResult>;
+    send(input: string, options?: ModelCallOptions): Promise<TurnResult>;
+    stream(input: string, options?: ModelCallOptions): AsyncGenerator<TurnChunk>;
+    submitToolResult(result: ToolResult, options?: ModelCallOptions): Promise<TurnResult>;
     /**
      * Stream-compatible entry for AI SDK (useChat) integration.
      *
@@ -48,10 +51,35 @@ export declare class HaloAgentImpl {
     keepAlive(intervalMs?: number): {
         stop: () => void;
     };
+    /**
+     * Streaming entry with full tool-call loop.
+     * Accepts both a plain string and a ChatMessage[] (for AI SDK useChat integration).
+     */
+    streamText(input: string | ChatMessage[], opts?: StreamTextOptions): StreamTextResult;
+    private _streamWithToolLoop;
+    /**
+     * Generate a structured object from a prompt.
+     *
+     * Schema (Zod or JSON Schema) is sent as `responseFormat` — does NOT
+     * enter StablePrefix. Tools are suppressed for this call.
+     */
+    generateObject<T = unknown>(input: string, opts: GenerateObjectOptions<unknown>): Promise<GenerateObjectResult<T>>;
+    /**
+     * Stream a progressively-built object from a prompt.
+     *
+     * Schema is sent as `responseFormat` — does NOT enter StablePrefix.
+     * Tools are suppressed.
+     */
+    streamObject<T = unknown>(input: string, opts: GenerateObjectOptions<unknown>): AsyncGenerator<T>;
     /** Restore conversation state from external history. */
     hydrate(messages: ChatMessage[]): void;
     clearLog(): void;
     setSystem(system: string): void;
+    /**
+     * Execute a tool call with automatic sandbox injection.
+     * Detects execute.length: 2 params → passes ToolContext.
+     */
+    private _executeTool;
     /** Resolve history, applying ContextStrategy (prefix is read-only). */
     private _resolveHistory;
     private _callModel;

package/dist/session-impl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-impl.d.ts","sourceRoot":"","sources":["../src/session-impl.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,UAAU,EAEV,YAAY,EACZ,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAItB,0DAA0D;AAC1D,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,OAAO,CAAe;IAC9B,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,QAAQ,CAA8B;IAC9C,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,UAAU,CAAsE;IACxF,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,eAAe,CAA+C;IACtE,OAAO,CAAC,cAAc,CAA2E;gBAErF,IAAI,EAAE,gBAAgB;IAiDlC,IAAI,KAAK,IAAI,QAAQ,CAAC,YAAY,CAAC,CAElC;IAEK,GAAG,CACP,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE;QACL,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;QACrD,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;SAAE,KAAK,IAAI,CAAC;KAChF,GACA,OAAO,CAAC,UAAU,CAAC;IA+ChB,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAKvC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC;IAOjD,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAS/D;;;;;;;;;;OAUG;IACI,SAAS,CACd,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAC5C,cAAc,CAAC,SAAS,CAAC;IAmC5B,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAC7B,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAgBhD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI9B,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAGlC,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAMrC,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE;IAyBpD,wDAAwD;IACxD,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAMtC,QAAQ,IAAI,IAAI;IAIhB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAS/B,uEAAuE;IACvE,OAAO,CAAC,eAAe;YAmBT,UAAU;IAyDxB,OAAO,CAAC,KAAK;IAYb,OAAO,CAAC,cAAc;IAOtB,OAAO,CAAC,eAAe;CAOxB"}
+{"version":3,"file":"session-impl.d.ts","sourceRoot":"","sources":["../src/session-impl.ts"],"names":[],"mappings":"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"}

package/dist/session.d.ts

@@ -1,6 +1,7 @@
 import type { ChatMessage, ToolCall, ToolDefinition, ToolSpec, Usage } from "./types.js";
 import type { ContextStrategy, RepairStrategy } from "./strategies.js";
-import type { ModelAdapter } from "./model-adapter.js";
+import type { ModelAdapter, ModelCallOptions } from "./model-adapter.js";
+import type { Sandbox } from "./sandbox.js";
 export interface TurnResult {
     content: string;
     toolCalls: ToolCall[];
@@ -52,9 +53,29 @@ export interface SessionStats {
     pricingSnapshot: PricingSnapshot;
     recentDiagnostics: CacheMissReason[];
 }
+export type { ModelCallOptions } from "./model-adapter.js";
+/** Agent-level model defaults. Does NOT enter StablePrefix — safe to change without cache miss. */
+export interface ModelConfig extends ModelCallOptions {
+}
+/** Metadata extracted from a SKILL.md file. */
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    /** Absolute path to the skill directory (for reading SKILL.md body). */
+    path: string;
+}
 export interface HaloAgentOptions {
     adapter: ModelAdapter;
-    system: string;
+    /**
+     * Prefix messages. All messages go into StablePrefix in order.
+     * The first `role: "system"` message defines the system prompt;
+     * remaining messages act as few-shot examples.
+     *
+     * Mutually exclusive with `system` / `fewShots`.
+     */
+    messages?: ChatMessage[];
+    /** @deprecated Use `messages: [{ role: "system", content: "..." }]` instead. */
+    system?: string;
     /**
      * Tools available to the model.
      *
@@ -64,9 +85,78 @@ export interface HaloAgentOptions {
      * no `onToolCall` callback needed.
      */
     tools?: ToolSpec[] | Record<string, ToolDefinition<any>>;
+    /** @deprecated Use `messages` with `role: "user"` / `role: "assistant"` entries instead. */
     fewShots?: ChatMessage[];
+    /** Agent-level model defaults. Does not enter StablePrefix — safe to change without cache miss. */
+    model?: ModelConfig;
+    /**
+     * Agent Skills (agentskills.io spec).
+     * Name + description enter StablePrefix (system prompt).
+     * Runtime: a `loadSkill` tool is auto-registered.
+     */
+    skills?: SkillMetadata[];
+    /**
+     * Sandbox for file operations and command execution.
+     * Does NOT enter StablePrefix — safe to change without cache miss.
+     */
+    sandbox?: Sandbox;
     context?: ContextStrategy;
     repair?: RepairStrategy;
     on?: (event: AgentEvent, payload: unknown) => void;
 }
+/** Named callbacks for streamText(). */
+export interface StreamTextCallbacks {
+    onChunk?: (event: {
+        chunk: TurnChunk;
+    }) => void;
+    onStepFinish?: (event: {
+        text: string;
+        toolCalls: ToolCall[];
+        usage: Usage;
+        step: number;
+    }) => void;
+    onFinish?: (event: {
+        text: string;
+        usage: Usage;
+        steps: number;
+        toolCalls: ToolCall[];
+    }) => void;
+    onError?: (error: Error) => void;
+}
+export interface StreamTextOptions extends ModelCallOptions, StreamTextCallbacks {
+    maxSteps?: number;
+    onToolCall?: (call: ToolCall) => Promise<ToolResult>;
+}
+export interface GenerateObjectOptions<TSchema = Record<string, unknown>> {
+    schema: TSchema;
+    temperature?: number;
+    topP?: number;
+    maxTokens?: number;
+    seed?: number;
+}
+export interface GenerateObjectResult<T = unknown> {
+    object: T;
+    usage: Usage;
+}
+export interface StreamTextResult {
+    toDataStream(opts?: {
+        headers?: Record<string, string>;
+    }): Response;
+    toReadableStream(): ReadableStream<Uint8Array>;
+    toAsyncIterable(): AsyncIterable<TurnChunk>;
+    text: Promise<string>;
+    usage: Promise<Usage>;
+    on(event: "text-delta", fn: (payload: TurnChunk & {
+        type: "text-delta";
+    }) => void): () => void;
+    on(event: "tool-call-delta", fn: (payload: TurnChunk & {
+        type: "tool-call-delta";
+    }) => void): () => void;
+    on(event: "tool-call-ready", fn: (payload: TurnChunk & {
+        type: "tool-call-ready";
+    }) => void): () => void;
+    on(event: "done", fn: (payload: TurnChunk & {
+        type: "done";
+    }) => void): () => void;
+}
 //# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACzF,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAIvD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,KAAK,CAAC;CACd;AAID,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAID,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACrC;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAClF;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAInC,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,mBAAmB,GAAG,gBAAgB,CAAC;AAI/E,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,YAAY,GAAG,gBAAgB,GAAG,eAAe,GAAG,kBAAkB,GAAG,SAAS,CAAC;IACzF,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IAEd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAE9B,OAAO,CAAC,EAAE;QACR,mBAAmB,EAAE,MAAM,CAAC;QAC5B,oBAAoB,EAAE,MAAM,CAAC;QAC7B,YAAY,EAAE,MAAM,CAAC;QACrB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;KACpC,CAAC;IAEF,eAAe,EAAE,eAAe,CAAC;IAEjC,iBAAiB,EAAE,eAAe,EAAE,CAAC;CACtC;AAID,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf;;;;;;;OAOG;IAEH,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;IACzD,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;IAEzB,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;IAExB,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -0,0 +1,27 @@
+import type { SkillMetadata } from "./session.js";
+import type { Sandbox } from "./sandbox.js";
+/**
+ * Discover Agent Skills from a set of directories.
+ *
+ * Scans each directory for subdirectories containing a `SKILL.md` file,
+ * parses the YAML frontmatter (`name`, `description`), and returns
+ * deduplicated metadata (first skill with a given name wins — allows
+ * project-level overrides).
+ *
+ * When `sandbox` is provided, file operations use the sandbox abstraction
+ * instead of raw Node `fs` (enables cross-platform/browser usage).
+ * Without sandbox, falls back to `node:fs/promises` (**@nodeOnly**).
+ *
+ * @example
+ * ```ts
+ * const skills = await discoverSkills({
+ *   directories: [".halo/skills"],
+ *   sandbox: new VirtualSandbox(),
+ * });
+ * ```
+ */
+export declare function discoverSkills(opts: {
+    directories: string[];
+    sandbox?: Sandbox;
+}): Promise<SkillMetadata[]>;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE;IACzC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CA6C3B"}

package/dist/tool.d.ts

@@ -1,22 +1,19 @@
 import type { ToolDefinition } from "./types.js";
+import type { ToolContext } from "./sandbox.js";
 /**
  * Create a tool definition with an optional built-in execute function.
  *
  * This is a **type-level identity** — at runtime it returns the input unchanged.
  * It exists purely for TypeScript generic inference on `TArgs`.
  *
- * @example
- * ```ts
- * const weatherTool = tool({
- *   description: "Get the weather for a city",
- *   parameters: {
- *     type: "object",
- *     properties: { city: { type: "string" } },
- *     required: ["city"],
- *   },
- *   execute: async ({ city }) => `Sunny, 22°C in ${city}`,
- * });
- * ```
+ * Two overloads support both single-arg and dual-arg execute signatures.
+ * The agent detects `execute.length` at runtime and passes `ctx` only
+ * when the function accepts a second parameter.
  */
-export declare function tool<TArgs = Record<string, unknown>>(def: ToolDefinition<TArgs>): ToolDefinition<TArgs>;
+export declare function tool<TArgs = Record<string, unknown>>(def: ToolDefinition<TArgs> & {
+    execute?: (args: TArgs) => string | Promise<string>;
+}): ToolDefinition<TArgs>;
+export declare function tool<TArgs = Record<string, unknown>>(def: ToolDefinition<TArgs> & {
+    execute?: (args: TArgs, ctx: ToolContext) => string | Promise<string>;
+}): ToolDefinition<TArgs>;
 //# sourceMappingURL=tool.d.ts.map

package/dist/tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,GACzB,cAAc,CAAC,KAAK,CAAC,CAEvB"}
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG;IAC3B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD,GACA,cAAc,CAAC,KAAK,CAAC,CAAC;AACzB,wBAAgB,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAClD,GAAG,EAAE,cAAc,CAAC,KAAK,CAAC,GAAG;IAC3B,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE,GACA,cAAc,CAAC,KAAK,CAAC,CAAC"}

package/dist/tools-builtin.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from "./types.js";
+/** Safe calculator: evaluates arithmetic expressions with a whitelist. */
+export declare function calculator(): ToolDefinition<{
+    expression: string;
+}>;
+/** Time utilities: now, parse, convert between timezones. */
+export declare function datetime(): ToolDefinition<{
+    operation: string;
+    value?: string;
+    tz?: string;
+}>;
+//# sourceMappingURL=tools-builtin.d.ts.map

package/dist/tools-builtin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools-builtin.d.ts","sourceRoot":"","sources":["../src/tools-builtin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,0EAA0E;AAC1E,wBAAgB,UAAU,IAAI,cAAc,CAAC;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,CA8BnE;AAED,6DAA6D;AAC7D,wBAAgB,QAAQ,IAAI,cAAc,CAAC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb,CAAC,CAsED"}

package/dist/types.d.ts

@@ -7,6 +7,8 @@ export interface ChatMessage {
     tool_calls?: ToolCall[];
     tool_call_id?: string;
     name?: string;
+    /** Hint to ContextStrategy: this message can be dropped first when truncating. */
+    discardable?: boolean;
 }
 /** A tool call requested by the model. */
 export interface ToolCall {
@@ -37,6 +39,15 @@ export interface ToolDefinition<TArgs = Record<string, unknown>> {
     /** If provided, run() calls this automatically when the model requests this tool. */
     execute?: (args: TArgs) => string | Promise<string>;
 }
+/** Structured output format. OpenAI-compatible. */
+export interface ResponseFormat {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+}
 /** Token usage for a single model call. */
 export interface Usage {
     promptTokens: number;

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD;AAED,2CAA2C;AAC3C,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,MAAM,MAAM,IAAI,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;AAE5D,6CAA6C;AAC7C,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,2DAA2D;AAC3D,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC7D,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,qFAAqF;IACrF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACrD;AAED,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,aAAa,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAED,2CAA2C;AAC3C,MAAM,WAAW,KAAK;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IAEzB,6DAA6D;IAC7D,OAAO,CAAC,EAAE;QACR,SAAS,EAAE,MAAM,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;CACH"}

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@halo-sdk/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Core types, factory, and session management for Halo AI SDK — cache-aware agent with automatic tool-call loop",
-  "license": "MIT",
   "keywords": [
-    "ai",
-    "llm",
     "agent",
+    "ai",
     "cache-first",
     "deepseek",
+    "llm",
     "tool-calling"
   ],
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/halo-sdk/halo-ai",
@@ -25,7 +25,8 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     }
   },
   "publishConfig": {
@@ -33,11 +34,15 @@
   },
   "devDependencies": {
     "typescript": "^5.8.0",
-    "vitest": "^3.0.0"
+    "vitest": "^3.0.0",
+    "zod": "^4.4.3",
+    "zod-to-json-schema": "^3.25.2"
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
+    "build": "tsc --build --emitDeclarationOnly && tsup",
+    "dev": "tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "publint": "publint",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/dist/halo-agent.js

@@ -1,95 +0,0 @@
-import { HaloAgentImpl } from "./session-impl.js";
-/**
- * A cache-aware AI agent with automatic tool-call loop.
- *
- * Create one via `new HaloAgent(opts)` or `halo.agent(opts)`.
- * Each agent maintains a stable prefix (system prompt + tools + few-shots)
- * that enables prefix caching across turns.
- */
-export class HaloAgent {
-    _impl;
-    constructor(opts) {
-        this._impl = new HaloAgentImpl(opts);
-    }
-    // ── Core ──
-    /** Read-only agent statistics. Updated after every turn. */
-    get stats() {
-        return this._impl.stats;
-    }
-    /**
-     * Run a prompt with automatic tool-call loop.
-     * This is the default entry point for 80% of use-cases.
-     */
-    async run(input, opts) {
-        return this._impl.run(input, opts);
-    }
-    /**
-     * Send a message. Tool calls are returned, NOT automatically executed.
-     * Use submitToolResult() to feed results back.
-     */
-    async send(input) {
-        return this._impl.send(input);
-    }
-    /** Stream a message. */
-    async *stream(input) {
-        yield* this._impl.stream(input);
-    }
-    /** Submit a tool execution result. Triggers another model call. */
-    async submitToolResult(result) {
-        return this._impl.submitToolResult(result);
-    }
-    /**
-     * Stream-compatible entry for AI SDK (useChat) integration.
-     *
-     * Accepts UIMessages from `useChat()`, hydrates prior history,
-     * and streams the response. When tools with `execute` are present,
-     * the full tool-call loop runs automatically via `run()`.
-     */
-    async *sdkStream(messages) {
-        yield* this._impl.sdkStream(messages);
-    }
-    addTool(specOrName, def) {
-        if (typeof specOrName === "string") {
-            this._impl.addTool(specOrName, def);
-        }
-        else {
-            this._impl.addTool(specOrName);
-        }
-    }
-    /** Remove a tool. Same cache-miss semantics. */
-    removeTool(name) {
-        this._impl.removeTool(name);
-    }
-    /** Add a few-shot example. Same cache-miss semantics. */
-    addFewShot(msg) {
-        this._impl.addFewShot(msg);
-    }
-    /** Remove a few-shot example by index. */
-    removeFewShot(index) {
-        return this._impl.removeFewShot(index);
-    }
-    // ── Keep-alive ──
-    /**
-     * Start a keep-alive timer that sends periodic pings to maintain
-     * server-side KV cache warmth. Call stop() when the long-running
-     * task is done.
-     */
-    keepAlive(intervalMs) {
-        return this._impl.keepAlive(intervalMs);
-    }
-    // ── Hydrate ──
-    /** Restore conversation state from external history (e.g. previous API calls). */
-    hydrate(messages) {
-        this._impl.hydrate(messages);
-    }
-    // ── Lifecycle ──
-    /** Clear conversation history without changing the prefix. */
-    clearLog() {
-        this._impl.clearLog();
-    }
-    /** Change the system prompt. Triggers cache miss. */
-    setSystem(system) {
-        this._impl.setSystem(system);
-    }
-}
-//# sourceMappingURL=halo-agent.js.map

package/dist/halo-agent.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"halo-agent.js","sourceRoot":"","sources":["../src/halo-agent.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAElD;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;IACZ,KAAK,CAAgB;IAE7B,YAAY,IAAsB;QAChC,IAAI,CAAC,KAAK,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC;IAED,aAAa;IAEb,4DAA4D;IAC5D,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,GAAG,CACP,KAAa,EACb,IAIC;QAED,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,KAAa;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IAED,wBAAwB;IACxB,KAAK,CAAC,CAAC,MAAM,CAAC,KAAa;QACzB,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAClC,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,gBAAgB,CAAC,MAAkB;QACvC,OAAO,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;IAC7C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,CAAC,SAAS,CACd,QAA6C;QAE7C,KAAK,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAQD,OAAO,CAAC,UAA6B,EAAE,GAAoB;QACzD,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,EAAE,GAAI,CAAC,CAAC;QACvC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACjC,CAAC;IACH,CAAC;IACD,gDAAgD;IAChD,UAAU,CAAC,IAAY;QACrB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IACD,yDAAyD;IACzD,UAAU,CAAC,GAAgB;QACzB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IACD,0CAA0C;IAC1C,aAAa,CAAC,KAAa;QACzB,OAAO,IAAI,CAAC,KAAK,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,mBAAmB;IAEnB;;;;OAIG;IACH,SAAS,CAAC,UAAmB;QAC3B,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;IAED,gBAAgB;IAEhB,kFAAkF;IAClF,OAAO,CAAC,QAAuB;QAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/B,CAAC;IAED,kBAAkB;IAElB,8DAA8D;IAC9D,QAAQ;QACN,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC;IACxB,CAAC;IACD,qDAAqD;IACrD,SAAS,CAAC,MAAc;QACtB,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;CACF"}