@ziggs-ai/agent-sdk 0.1.5 → 0.1.6

package/README.md

@@ -13,7 +13,7 @@ It is **not** a generic chat wrapper: the core idea is a **lightweight state mac
 | **`defineAgent` / workflow** | Declarative agent: `initial`, `states`, optional `id`, `description`, `specialization`, merged `tools` / `services`. |
 | **`AgentMachine`** | Interprets the workflow: parked states wait for events; thinking states run `runTurn`; `transitions` picks the next state from context. |
 | **`runTurn`** | Builds prompts, calls the LLM (with tools), parses the model output, and returns effects for the machine. |
-| **`ZiggsAgent`** | Batteries-included process: OpenAI adapter, tool manager, task service, context read/write, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
+| **`AgentHost`** | Batteries-included process: OpenAI adapter, tool manager, task service, context clients, **WebSocket** to Ziggs, and an **`Agent`** that dispatches incoming messages into the machine. |
 | **`Agent`** | Orchestrates message handling, machine lifecycle, and integration with platform APIs (without requiring you to use WebSockets if you construct it yourself). |
 
 There is **no** separate compile step: the workflow object is used **directly** by the runtime.
@@ -50,7 +50,7 @@ The `wait` action is built-in: `defineAgent` automatically injects it into every
 ## How you usually run an agent
 
 1. **`defineAgent({ ... })`** → options object including `workflow`.
-2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`new ZiggsAgent(config)`** (or **`createAgent(config)`**).
+2. Pass **`openaiKey`**, **`operatorKey`** (Ziggs operator token), **`agentId`**, **`wsUrl`**, etc., and **`createAgent(config)`** (returns an **`AgentHost`**).
 3. **`connect()`** to open the WebSocket; the SDK routes platform messages into **`handleMessage`**.
 
 Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery agents).
@@ -59,14 +59,14 @@ Examples in the repo: `examples/agents/*.js` (e.g. coffee, expense, delivery age
 
 ## Main exports (entry: `src/index.js`)
 
-- **`ZiggsAgent`**, **`createAgent`**, **`defineAgent`**
+- **`AgentHost`**, **`createAgent`**, **`createAgentPool`**, **`defineAgent`**
 - **`Agent`**, **`AgentMachine`**, **`runTurn`**
 - **Prompt / tools:** `PromptBuilder`, `ToolManager`, `defineTool`
 - **Tools come in two tiers — single home: `server/tools/`:**
   - **Tier 1 — protocol grammar (`server/tools/tier1/`, `PROTOCOL_TOOLS`).** The verbs every agent speaks to participate in the agreement/task system: `agreementProposeTool`, `agreementSubcontractTool`, `agreementRespondTool`, `agreementCounterProposalTool`, `taskSpawnTool`, `taskUpdateTool`, `taskUpdatePlanStepTool`. **Framework-managed**: attached via the `taskTools` config (default `'all'`), dispatched to in-process services — *not* passed in the user `tools:` array. Publishing open work is part of this grammar: `agreement_propose({ proposedTo: "everyone" })` (there is no separate publish tool).
   - **Tier 2 — capability bundles (`server/tools/tier2/`, opt-in, HTTP-backed).** Discrete capability domains an agent chooses to have. **Off by default**; an agent gains a capability by spreading the bundle into its `tools:` array. Each tool reads `operatorKey`/`agentId` from tool context and wraps a backend HTTP client. Bundles: `DISCOVERY_TOOLS` (`agentSearchTool`, `agentGetTool`), `MARKETPLACE_TOOLS` (`marketplaceViewTool` — read-only), `PAYMENT_TOOLS` (`paymentBalanceTool`, `paymentTransferTool`, …).
 - **Adapters / utils:** `OpenAIAdapter`, JSON helpers, formatters
-- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReader`, `ContextWriter`, URL helpers, etc.
+- **Re-exported** from `@ziggs-ai/api-client`: `WebSocketClient`, `ContextReadClient`, `ContextDiscoveryClient`, `ContextGrantsClient`, `ArtifactsClient`, `MessagesClient`, `ScopeClient`, `AgentSearchClient`, `getBackendUrl`, `getWebSocketUrl`, etc. (There is no `ContextReader` / `ContextWriter` — use the clients above from `@ziggs-ai/api-client` directly.)
 
 Package export: `"."` → `src/index.js` (see `package.json`).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "src/index.ts",

package/src/index.ts

@@ -54,6 +54,8 @@ export { AgreementService } from './server/agreements/AgreementService.js';
 export { ToolManager } from './tools/ToolManager.js';
 export { ToolProvider } from './tools/ToolProvider.js';
 export { defineTool } from './tools/defineTool.js';
+export { recordReport } from './tools/recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './tools/recordReport.js';
 export { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 export { extractJSON, safeParseJSON } from './utils/jsonExtractor.js';
 export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormatter } from './formatters/index.js';

package/src/tools/index.ts

@@ -1,5 +1,7 @@
 export { ToolManager } from './ToolManager.js';
 export { ToolProvider } from './ToolProvider.js';
 export { defineTool } from './defineTool.js';
+export { recordReport } from './recordReport.js';
+export type { RecordReportInput, RecordReportResult, TaskReport } from './recordReport.js';
 // Pure protocol-tool name registry (no handlers, no services).
 export { PROTOCOL_TOOL_NAMES, PROTOCOL_TOOL_TO_OPERATION, mapProtocolToolToOperation, isProtocolToolName } from '../tasks/protocolRegistry.js';

package/src/tools/recordReport.ts

@@ -0,0 +1,82 @@
+import {
+  ArtifactsClient,
+  updateTaskState,
+  type Creds,
+} from '@ziggs-ai/api-client';
+
+/**
+ * The canonical report shape (B1 convention — ZIG-561).
+ * Matches Task.result as set by ziggs_set_task_result.
+ */
+export interface TaskReport {
+  summary: string;
+  status?: string;
+  links?: string[];
+}
+
+export interface RecordReportInput {
+  creds: Creds;
+  taskId: string;
+  report: TaskReport;
+  /**
+   * Primary artifact scope — required when `deliverable` is provided.
+   * Pass exactly one of chatId or agreementId.
+   */
+  chatId?: string;
+  agreementId?: string;
+  /**
+   * Heavy deliverable text (document, diff, data).
+   * When present, writes a `content_type=result` artifact bound to the task
+   * alongside setting Task.result.
+   */
+  deliverable?: string;
+}
+
+export interface RecordReportResult {
+  taskId: string;
+  artifactId?: string;
+}
+
+/**
+ * Record a conformant report for a completed task (B2 — ZIG-562).
+ *
+ * Always sets Task.result via updateTaskState (the canonical done payload).
+ * When `deliverable` is provided, also writes a task-bound result artifact
+ * via ArtifactsClient so it is retrievable as `via=task:<taskId>`.
+ *
+ * Implements the B1 convention (Agents/REPORTING.md).
+ */
+export async function recordReport(
+  input: RecordReportInput,
+): Promise<RecordReportResult> {
+  const { creds, taskId, report, chatId, agreementId, deliverable } = input;
+
+  if (deliverable && !chatId && !agreementId) {
+    throw new Error(
+      'recordReport: chatId or agreementId is required when deliverable is provided',
+    );
+  }
+
+  await updateTaskState(
+    taskId,
+    'completed',
+    { result: { summary: report.summary, status: report.status ?? 'ok', links: report.links ?? [] } },
+    creds,
+  );
+
+  if (!deliverable) {
+    return { taskId };
+  }
+
+  const artifactsClient = new ArtifactsClient(creds.operatorKey, creds.agentId);
+  await artifactsClient.write({
+    text: deliverable,
+    content_type: 'result',
+    taskId,
+    chatId,
+    agreementId,
+    visibility: 'chat',
+  });
+
+  return { taskId };
+}