@halo-sdk/core 1.0.0 → 1.0.1

package/README.md

@@ -1,8 +1,53 @@
 # @halo-sdk/core
 
-Core types, factory, and session management for Halo AI SDK.
+Core types, factory, and session management for the Halo AI SDK — a cache-first agent framework with automatic prefix caching.
 
-- `Halo` — factory for creating sessions
-- `HaloAgent` — cache-aware AI agent with automatic tool-call loop
-- `StablePrefix` — SHA-256 fingerprinted prefix management
-- `MessageLog` — in-memory message history
+## Installation
+
+```bash
+npm install @halo-sdk/core
+```
+
+Requires Node.js >= 22 and a compatible model adapter (e.g. `@halo-sdk/adapters`).
+
+## Quick Start
+
+```ts
+import { Halo, tool } from "@halo-sdk/core";
+import { DeepSeekAdapter } from "@halo-sdk/adapters";
+
+const halo = new Halo({
+  adapter: new DeepSeekAdapter({ apiKey: process.env.DEEPSEEK_API_KEY! }),
+});
+
+const agent = halo.agent({
+  messages: [{ role: "system", content: "You are a helpful assistant." }],
+  tools: {
+    weather: tool({
+      description: "Get weather for a city",
+      parameters: {
+        type: "object",
+        properties: { city: { type: "string" } },
+        required: ["city"],
+      },
+      execute: async ({ city }) => `Sunny, 22°C in ${city}`,
+    }),
+  },
+});
+
+const result = await agent.generateText("What's the weather in Paris?");
+console.log(result.content);
+// → "The weather in Paris is sunny, 22°C."
+```
+
+## Key Features
+
+- **Cache-first architecture** — `StablePrefix` (system prompt + tools + few-shots) is automatically cached by DeepSeek. Only dynamic conversation history is billed at full rate.
+- **Auto tool loop** — tools with `execute` are automatically called by `generateText()`.
+- **Streaming** — `streamText()` with full tool-loop support, compatible with Vercel AI SDK `useChat`.
+- **Structured output** — `generateObject()` with Zod or JSON Schema.
+- **Agent Skills** — progressive disclosure via `discoverSkills()` + auto-registered `loadSkill` tool.
+
+## Documentation
+
+See the [Halo SDK docs](https://halo-sdk.github.io/halo-ai/en/api-reference/halo-agent) for full API reference and guides.

package/dist/halo-agent.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";
 /**
  * A cache-aware AI agent with automatic tool-call loop.
  *
@@ -13,9 +14,19 @@ export declare class HaloAgent {
     /** Read-only agent statistics. Updated after every turn. */
     get stats(): Readonly<SessionStats>;
     /**
-     * Run a prompt with automatic tool-call loop.
-     * This is the default entry point for 80% of use-cases.
+     * Generate a text response with automatic tool-call loop.
+     * This is the primary entry point for non-streaming use-cases.
      */
+    generateText(input: string, opts?: {
+        maxSteps?: number;
+        onToolCall?: (call: ToolCall) => Promise<ToolResult>;
+        onStep?: (step: {
+            step: number;
+            content: string;
+            toolCalls: ToolCall[];
+        }) => void;
+    } & ModelCallOptions): Promise<TurnResult>;
+    /** @deprecated Use `generateText()` instead. */
     run(input: string, opts?: {
         maxSteps?: number;
         onToolCall?: (call: ToolCall) => Promise<ToolResult>;
@@ -24,16 +35,43 @@ export declare class HaloAgent {
             content: string;
             toolCalls: ToolCall[];
         }) => void;
-    }): Promise<TurnResult>;
+    } & ModelCallOptions): Promise<TurnResult>;
+    /**
+     * Send a single message. Tool calls are returned, NOT auto-executed.
+     * Use `submitToolResult()` to feed results back manually.
+     *
+     * For automatic tool loops, use `generateText()` or `streamText()` instead.
+     */
     /**
      * Send a message. Tool calls are returned, NOT automatically executed.
      * Use submitToolResult() to feed results back.
      */
-    send(input: string): Promise<TurnResult>;
+    send(input: string, options?: ModelCallOptions): Promise<TurnResult>;
     /** Stream a message. */
-    stream(input: string): AsyncGenerator<TurnChunk>;
+    stream(input: string, options?: ModelCallOptions): AsyncGenerator<TurnChunk>;
+    /**
+     * Streaming entry with full tool-call loop and named callbacks.
+     *
+     * Accepts a string (plain input) or `ChatMessage[]` (AI SDK useChat integration).
+     * Returns a `StreamTextResult` with multiple consumption paths.
+     */
+    streamText(input: string | ChatMessage[], opts?: StreamTextOptions): StreamTextResult;
+    /**
+     * Generate a structured object from a prompt.
+     *
+     * Accepts Zod schemas (compile-time type inference) or plain JSON Schema.
+     * 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.
+     *
+     * Yields incremental partial objects as the JSON builds up.
+     */
+    streamObject<T = unknown>(input: string, opts: GenerateObjectOptions<unknown>): AsyncGenerator<T>;
     /** Submit a tool execution result. Triggers another model call. */
-    submitToolResult(result: ToolResult): Promise<TurnResult>;
+    submitToolResult(result: ToolResult, options?: ModelCallOptions): Promise<TurnResult>;
     /**
      * Stream-compatible entry for AI SDK (useChat) integration.
      *

package/dist/halo-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"halo-agent.d.ts","sourceRoot":"","sources":["../src/halo-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAClF,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EACT,UAAU,EACV,YAAY,EACZ,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAGtB;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,KAAK,CAAgB;gBAEjB,IAAI,EAAE,gBAAgB;IAMlC,4DAA4D;IAC5D,IAAI,KAAK,IAAI,QAAQ,CAAC,YAAY,CAAC,CAElC;IAED;;;OAGG;IACG,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,IAAI,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,SAAS,EAAE,QAAQ,EAAE,CAAA;SAAE,KAAK,IAAI,CAAC;KACnF,GACA,OAAO,CAAC,UAAU,CAAC;IAItB;;;OAGG;IACG,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI9C,wBAAwB;IACjB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,SAAS,CAAC;IAIvD,mEAAmE;IAC7D,gBAAgB,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/D;;;;;;OAMG;IACI,SAAS,CACd,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAC5C,cAAc,CAAC,SAAS,CAAC;IAM5B,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI;IAC7B,0DAA0D;IAC1D,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,IAAI;IAQhD,gDAAgD;IAChD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAG9B,yDAAyD;IACzD,UAAU,CAAC,GAAG,EAAE,WAAW,GAAG,IAAI;IAGlC,0CAA0C;IAC1C,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAMrC;;;;OAIG;IACH,SAAS,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG;QAAE,IAAI,EAAE,MAAM,IAAI,CAAA;KAAE;IAMpD,kFAAkF;IAClF,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,IAAI;IAMtC,8DAA8D;IAC9D,QAAQ,IAAI,IAAI;IAGhB,qDAAqD;IACrD,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;CAGhC"}
+{"version":3,"file":"halo-agent.d.ts","sourceRoot":"","sources":["../src/halo-agent.ts"],"names":[],"mappings":"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"}

package/dist/halo.d.ts

@@ -1,17 +1,28 @@
 import { HaloAgent } from "./halo-agent.js";
-import type { AgentEvent } from "./session.js";
+import type { AgentEvent, ModelConfig, SkillMetadata } from "./session.js";
 import type { ModelAdapter } from "./model-adapter.js";
 import type { ContextStrategy, RepairStrategy } from "./strategies.js";
 import type { ToolSpec, ChatMessage, ToolDefinition } from "./types.js";
+import type { Sandbox } from "./sandbox.js";
 export declare class Halo {
     private _adapter;
     constructor(opts: {
         adapter: ModelAdapter;
     });
     agent(opts: {
-        system: string;
+        /** Prefix messages (preferred). Mutually exclusive with `system`. */
+        messages?: ChatMessage[];
+        /** @deprecated Use `messages` with `role: "system"` instead. */
+        system?: string;
         tools?: ToolSpec[] | Record<string, ToolDefinition<any>>;
+        /** @deprecated Use `messages` with `role: "user"` / `role: "assistant"` instead. */
         fewShots?: ChatMessage[];
+        /** Agent-level model defaults. Does not enter prefix — safe to change. */
+        model?: ModelConfig;
+        /** Agent Skills (agentskills.io). Name+description enter system prompt. */
+        skills?: SkillMetadata[];
+        /** Sandbox for file ops and command execution. Does NOT enter prefix. */
+        sandbox?: Sandbox;
         context?: ContextStrategy;
         repair?: RepairStrategy;
         on?: (event: AgentEvent, payload: unknown) => void;

package/dist/halo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"halo.d.ts","sourceRoot":"","sources":["../src/halo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAoB,UAAU,EAAE,MAAM,cAAc,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAExE,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAe;gBAEnB,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE;IAI3C,KAAK,CAAC,IAAI,EAAE;QACV,MAAM,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;QAEzB,OAAO,CAAC,EAAE,eAAe,CAAC;QAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;QAExB,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,GAAG,SAAS;CAad"}
+{"version":3,"file":"halo.d.ts","sourceRoot":"","sources":["../src/halo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAoB,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,qBAAa,IAAI;IACf,OAAO,CAAC,QAAQ,CAAe;gBAEnB,IAAI,EAAE;QAAE,OAAO,EAAE,YAAY,CAAA;KAAE;IAI3C,KAAK,CAAC,IAAI,EAAE;QACV,qEAAqE;QACrE,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;QACzB,gEAAgE;QAChE,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;QACzD,oFAAoF;QACpF,QAAQ,CAAC,EAAE,WAAW,EAAE,CAAC;QACzB,0EAA0E;QAC1E,KAAK,CAAC,EAAE,WAAW,CAAC;QACpB,2EAA2E;QAC3E,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC;QACzB,yEAAyE;QACzE,OAAO,CAAC,EAAE,OAAO,CAAC;QAElB,OAAO,CAAC,EAAE,eAAe,CAAC;QAC1B,MAAM,CAAC,EAAE,cAAc,CAAC;QAExB,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;KACpD,GAAG,SAAS;CAiBd"}