simple-agents-node 0.2.6 → 0.2.20

package/README.md

@@ -51,7 +51,7 @@ async function main() {
   console.log(response.usage);
   console.log(response.healed); // present when using healed_json/schema mode
 
-  // Streaming
+  // Streaming (legacy chunk callback)
   const streamed = await client.stream(
     model,
     'Say hello in two words.',
@@ -63,6 +63,24 @@ async function main() {
   );
   console.log('streamed content:', streamed.content);
 
+  // Streaming (typed event callback)
+  await client.streamEvents(
+    model,
+    'Say hello in two words.',
+    (event) => {
+      if (event.eventType === 'delta' && event.delta?.content) {
+        process.stdout.write(event.delta.content);
+      }
+      if (event.eventType === 'error') {
+        console.error('\nstream error:', event.error?.message);
+      }
+      if (event.eventType === 'done') {
+        console.log('\nstream done');
+      }
+    },
+    {},
+  );
+
   // Healed JSON
   const healed = await client.complete(
     'gpt-4',
@@ -81,7 +99,16 @@ main().catch((err) => {
 ## Notes
 
 - Canonical env contract for examples/tests is: `CUSTOM_API_BASE`, `CUSTOM_API_KEY`, `CUSTOM_API_MODEL`, `PROVIDER`.
+- Canonical env contract for examples/tests is: `PROVIDER`, `CUSTOM_API_KEY`, `CUSTOM_API_BASE` (optional), `CUSTOM_API_MODEL`.
 - For OpenAI provider compatibility, map `CUSTOM_API_*` to `OPENAI_API_*` when needed (`OPENAI_API_KEY`, `OPENAI_API_BASE`, `OPENAI_MODEL`).
 - `max_tokens`, `temperature`, and `top_p` are optional. Use `mode: "healed_json"` for parsed JSON or `mode: "schema"` with a schema object to coerce/validate.
-- `complete` resolves with the first choice, usage metadata, and optional `healed`/`coerced` metadata. `stream` invokes a chunk callback and resolves with aggregated content (healing/schema not yet supported for streams).
+- `complete` resolves with the first choice, usage metadata, and optional `healed`/`coerced` metadata.
+- `stream` invokes a chunk callback and resolves with aggregated content (healing/schema not yet supported for streams).
+- `streamEvents` is the canonical typed streaming callback API with `delta`, `error`, and `done` events.
 - Set `CUSTOM_API_BASE`, `CUSTOM_API_KEY`, `CUSTOM_API_MODEL`, and `PROVIDER` to run tests/examples consistently across bindings.
+
+## Test Layers
+
+- `npm run test:unit` - runtime/export sanity checks
+- `npm run test:contract` - shared fixture parity contract checks
+- `npm run test:live` - provider-backed live checks (env-gated)

package/index.d.ts

@@ -13,7 +13,7 @@ export interface CompleteOptions {
   schema?: unknown
 }
 export interface MessageInput {
-  role: string
+  role: 'system' | 'user' | 'assistant' | 'tool'
   content: string
   name?: string
   toolCallId?: string
@@ -23,6 +23,15 @@ export interface JsToolCallFunction {
   name: string
   arguments: string
 }
+export interface ToolCallResultFunction {
+  name: string
+  arguments: string
+}
+export interface ToolCallResult {
+  id: string
+  toolType: string
+  function: ToolCallResultFunction
+}
 export interface JsToolCall {
   id: string
   toolType: string
@@ -43,7 +52,7 @@ export interface CompletionResult {
   model: string
   role: string
   content?: string
-  toolCalls?: Array<JsToolCall>
+  toolCalls?: Array<ToolCallResult>
   finishReason?: string
   usage: CompletionUsage
   usageAvailable: boolean
@@ -60,8 +69,33 @@ export interface StreamChunk {
   error?: string
   raw?: string
 }
+export interface StreamDelta {
+  id: string
+  model: string
+  index: number
+  role?: string
+  content?: string
+  finishReason?: string
+  raw?: string
+}
+export interface StreamErrorEvent {
+  message: string
+}
+export interface StreamEvent {
+  eventType: string
+  delta?: StreamDelta
+  error?: StreamErrorEvent
+}
 export declare class Client {
   constructor(provider: string)
   complete(model: string, promptOrMessages: string | MessageInput[], options?: CompleteOptions): Promise<unknown>
   stream(model: string, promptOrMessages: string | MessageInput[], onChunk: (chunk: StreamChunk) => void, options?: CompleteOptions): Promise<unknown>
+  streamEvents(model: string, promptOrMessages: string | MessageInput[], onEvent: (event: StreamEvent) => void, options?: CompleteOptions): Promise<unknown>
+  runEmailWorkflowYaml(workflowPath: string, emailText: string, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): any
+  runWorkflowYaml(workflowPath: string, workflowInput: { email_text?: string; messages?: MessageInput[]; [key: string]: unknown }): any
+  runWorkflowYamlWithEvents(workflowPath: string, workflowInput: { email_text?: string; messages?: MessageInput[]; [key: string]: unknown }, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): any
+  runEmailWorkflowYamlWithEvents(workflowPath: string, emailText: string, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): any
+  runWorkflowYamlStream(workflowPath: string, workflowInput: { email_text?: string; messages?: MessageInput[]; [key: string]: unknown }, onEvent: (err: unknown, eventJson: string) => void, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): Promise<any>
+  runEmailWorkflowYamlStream(workflowPath: string, emailText: string, onEvent: (err: unknown, eventJson: string) => void, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): Promise<any>
+  runWorkflowYamlWithOptions(workflowPath: string, workflowInput: { email_text?: string; messages?: MessageInput[]; [key: string]: unknown }, workflowOptions?: { telemetry?: Record<string, unknown>; trace?: Record<string, unknown> }): any
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-agents-node",
-  "version": "0.2.6",
+  "version": "0.2.20",
   "description": "Node.js bindings for SimpleAgents using napi-rs",
   "main": "index.js",
   "types": "index.d.ts",
@@ -14,7 +14,10 @@
     "build": "napi build --release",
     "build:debug": "napi build",
     "pretest": "npm run build:debug",
-    "test": "node --test test/*.test.js",
+    "test": "npm run test:unit && npm run test:contract",
+    "test:unit": "node --test test/unit.test.js",
+    "test:contract": "node --test test/contract.test.js",
+    "test:live": "node --test test/live.test.js",
     "prepublishOnly": "npm run build"
   },
   "engines": {