@darqlabs/curator-sdk 0.1.3 → 0.1.4

package/README.md

@@ -60,6 +60,7 @@ console.log(reply.content)
 // reply.conversationId  — store this if you want to follow up
 // reply.runId           — useful for log correlation
 // reply.sequence        — per-conversation message index
+// reply.metadata        — structured result from the agent, or null (see below)
 ```
 
 ### 4. Multi-turn conversations
@@ -202,6 +203,28 @@ const reply = await chat.send("Do a deep research pass on this brief.", {
 })
 ```
 
+### Structured results (`metadata`)
+
+An agent whose instructions define a structured output — a booking draft, an extracted form, a plan — returns that object on `reply.metadata` alongside the conversational `reply.content`. It's `null` for plain conversational agents. The shape is whatever the agent emits (schema-agnostic); validate it in your app (e.g. with a zod schema).
+
+```ts
+const reply = await chat.send("Book Acme from Fontana to Ontario on July 1.")
+console.log(reply.content)   // "I've started the booking draft…"
+console.log(reply.metadata)  // { bookingDraft: { origin: {…}, … }, changedFields: [...], clarification: null }
+```
+
+**Live updates:** `chat.send()` returns only the final snapshot. To render progress as the agent fills the object in — turn by turn, before it replies — stream instead and handle `state` events:
+
+```ts
+for await (const event of chat.stream("Book Acme from Fontana to Ontario.")) {
+  if (event.type === "delta") appendText(event.text)          // prose tokens
+  else if (event.type === "state") renderDraft(event.metadata) // live structured snapshot, every turn
+  else if (event.type === "done") finalize(event.message)      // message.metadata = final snapshot
+}
+```
+
+Using React? `@darqlabs/curator-sdk-react`'s `<CuratorChat onState={…} />` wires this up for you.
+
 ---
 
 ## Using from a browser
@@ -267,6 +290,23 @@ Reattach to an existing conversation by id.
 `opts.files?: FileAttachment[]` — attachments.
 `opts.timeoutMs?: number` — override the wait timeout for this call.
 
+Returns the final assistant message. `message.metadata` holds the agent's structured result (or `null`).
+
+### `chat.stream(content, opts?) → AsyncIterable<StreamEvent>`
+
+Same send, streamed. Yields events as they arrive:
+
+| `event.type` | Payload | Terminal |
+| --- | --- | --- |
+| `delta` | `text` — incremental prose tokens | no |
+| `state` | `metadata` — complete structured snapshot for this turn | no |
+| `tool_call.started` / `tool_call.completed` | tool call id / name | no |
+| `done` | `message` (with `message.metadata`) | yes |
+| `error` | `failureClass`, `message` | yes |
+| `paused_for_approval` | `approval` | yes |
+
+`state` fires on every turn the agent reports structured state — see [Structured results](#structured-results-metadata).
+
 ### `chat.history(opts?) → Promise<HistoryPage>`
 
 `opts.limit?: number` — page size (server cap 500).

package/dist/cjs/index.d.ts

@@ -5,6 +5,6 @@ export { Files } from "./files.js";
 export type { PresignUploadInput, PresignUploadResult, OneShotUploadInput, UploadData, } from "./files.js";
 export { CuratorError, CuratorAuthError, CuratorForbiddenError, CuratorNotFoundError, CuratorDeploymentRetiredError, CuratorRateLimitError, CuratorApprovalRequiredError, CuratorAgentError, CuratorTimeoutError, } from "./errors.js";
 export type { AssistantMessage, UserMessage, ToolMessage, ConversationMessage, Environment, FileAttachment, ApprovalDetails, AgentFailureClass, SendOptions, HistoryOptions, HistoryPage, DeploymentConfig, } from "./types.js";
-export type { StreamEvent, StreamDelta, StreamToolCallStarted, StreamToolCallCompleted, StreamDone, StreamError, StreamPausedForApproval, } from "./streamEvents.js";
+export type { StreamEvent, StreamDelta, StreamToolCallStarted, StreamToolCallCompleted, StreamState, StreamDone, StreamError, StreamPausedForApproval, } from "./streamEvents.js";
 export { isTerminalStreamEvent } from "./streamEvents.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAkD;AAAzC,oGAAA,OAAO,OAAA;AAAE,kGAAA,KAAK,OAAA;AAAE,iGAAA,IAAI,OAAA;AAG7B,uCAAkC;AAAzB,iGAAA,KAAK,OAAA;AAOd,yCAUoB;AATlB,yGAAA,YAAY,OAAA;AACZ,6GAAA,gBAAgB,OAAA;AAChB,kHAAA,qBAAqB,OAAA;AACrB,iHAAA,oBAAoB,OAAA;AACpB,0HAAA,6BAA6B,OAAA;AAC7B,kHAAA,qBAAqB,OAAA;AACrB,yHAAA,4BAA4B,OAAA;AAC5B,8GAAA,iBAAiB,OAAA;AACjB,gHAAA,mBAAmB,OAAA;AAyBrB,qDAAyD;AAAhD,wHAAA,qBAAqB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;AAAA,yCAAkD;AAAzC,oGAAA,OAAO,OAAA;AAAE,kGAAA,KAAK,OAAA;AAAE,iGAAA,IAAI,OAAA;AAG7B,uCAAkC;AAAzB,iGAAA,KAAK,OAAA;AAOd,yCAUoB;AATlB,yGAAA,YAAY,OAAA;AACZ,6GAAA,gBAAgB,OAAA;AAChB,kHAAA,qBAAqB,OAAA;AACrB,iHAAA,oBAAoB,OAAA;AACpB,0HAAA,6BAA6B,OAAA;AAC7B,kHAAA,qBAAqB,OAAA;AACrB,yHAAA,4BAA4B,OAAA;AAC5B,8GAAA,iBAAiB,OAAA;AACjB,gHAAA,mBAAmB,OAAA;AA0BrB,qDAAyD;AAAhD,wHAAA,qBAAqB,OAAA"}

package/dist/esm/index.d.ts

@@ -5,6 +5,6 @@ export { Files } from "./files.js";
 export type { PresignUploadInput, PresignUploadResult, OneShotUploadInput, UploadData, } from "./files.js";
 export { CuratorError, CuratorAuthError, CuratorForbiddenError, CuratorNotFoundError, CuratorDeploymentRetiredError, CuratorRateLimitError, CuratorApprovalRequiredError, CuratorAgentError, CuratorTimeoutError, } from "./errors.js";
 export type { AssistantMessage, UserMessage, ToolMessage, ConversationMessage, Environment, FileAttachment, ApprovalDetails, AgentFailureClass, SendOptions, HistoryOptions, HistoryPage, DeploymentConfig, } from "./types.js";
-export type { StreamEvent, StreamDelta, StreamToolCallStarted, StreamToolCallCompleted, StreamDone, StreamError, StreamPausedForApproval, } from "./streamEvents.js";
+export type { StreamEvent, StreamDelta, StreamToolCallStarted, StreamToolCallCompleted, StreamState, StreamDone, StreamError, StreamPausedForApproval, } from "./streamEvents.js";
 export { isTerminalStreamEvent } from "./streamEvents.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,UAAU,EACV,WAAW,EACX,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAClD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,YAAY,EACV,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,UAAU,GACX,MAAM,YAAY,CAAA;AACnB,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AACpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,cAAc,EACd,WAAW,EACX,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,WAAW,EACX,WAAW,EACX,qBAAqB,EACrB,uBAAuB,EACvB,WAAW,EACX,UAAU,EACV,WAAW,EACX,uBAAuB,GACxB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGlD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAOlC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AAwBpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGlD,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAOlC,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,6BAA6B,EAC7B,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,aAAa,CAAA;AAyBpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darqlabs/curator-sdk",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Official Curator SDK — talk to your deployed agents from server-side JavaScript or TypeScript.",
   "license": "MIT",
   "main": "./dist/cjs/index.js",