@ziggs-ai/agent-sdk 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.9.0 — 2026-07-30
+
+### Changed (breaking)
+
+- `task-update` / `task_set_result` accept `state` only — legacy `status` alias removed (ZIG-1057).
+- Removed export `syncAggregateTaskViews`; read pending/collected/delegated via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`. Ctx aggregate mirrors stay empty.
+
 ## 0.4.0 — 2026-07-23
 
 ### Added

package/dist/index.d.ts

@@ -34,7 +34,7 @@ export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtim
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
-export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, syncAggregateTaskViews, } from './runtime/taskBookkeeping.js';
+export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
 export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
 export type { Outcome, OutcomeKind, Ctx, Identity, HistoryEntry, ToolResultEntry, PendingSubtask, CollectedSubtaskResult, TaskBookkeeping, Workflow, State, ParkedState, ThinkingState, MechanicalState, Action, Transition, PromptDef, ActionPrompt, Produces, ProducesFn, AgreementRef, TaskRef, ProposalRef, AgentConfig, DefineAgentInput, ServicesConfig, Effect, EffectKind, EffectResult, EffectResultMap, EffectHandler, LlmMessage, LlmToolCall, LlmToolSchema, LlmResponse, ContextSnapshot, ReadContextOpts, ToolCallResult, RecordedEntry, WakeWriteKeys, } from './types.js';
 export { default } from './AgentHost.js';

package/dist/index.js

@@ -28,7 +28,7 @@ export { KICKOFF_STATE, injectKickoffDefault, buildKickoffState } from './runtim
 export { validateWorkflow, WorkflowValidationError } from './runtime/validateWorkflow.js';
 export { deriveRespondsToProposals, statesRespondToProposals, } from './runtime/deriveRespondsToProposals.js';
 export { outcomeFromEvent, outcomeFromActionResult, applyOutcomeToCtx } from './runtime/buildOutcome.js';
-export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, syncAggregateTaskViews, } from './runtime/taskBookkeeping.js';
+export { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './runtime/taskBookkeeping.js';
 export { createWakeWriteKeys } from './runtime/wakeWriteKeys.js';
 export { default } from './AgentHost.js';
 // ── Supporting modules ──────────────────────────────────────────────────────

package/dist/runtime/bootstrapCtx.js

@@ -1,4 +1,4 @@
-import { migrateLegacyTaskFields, syncAggregateTaskViews } from './taskBookkeeping.js';
+import { migrateLegacyTaskFields } from './taskBookkeeping.js';
 /**
  * The one place a per-lane `Ctx` is constructed.
  *
@@ -18,16 +18,15 @@ import { migrateLegacyTaskFields, syncAggregateTaskViews } from './taskBookkeepi
 export function bootstrapCtx(identity, existing) {
     if (existing) {
         const legacy = existing;
-        const ctx = {
+        return {
             ...existing,
             identity,
             tasks: migrateLegacyTaskFields(legacy),
+            // ZIG-1057: deprecated mirrors stay empty; use all*() readers.
             pendingSubtasks: {},
             collectedResults: [],
             delegatedAgreementIds: [],
         };
-        syncAggregateTaskViews(ctx);
-        return ctx;
     }
     return {
         identity,

package/dist/runtime/buildOutcome.js

@@ -1,6 +1,6 @@
 import { isProtocolToolName, mapProtocolToolToOperation } from '../tasks/protocolRegistry.js';
 import { getBatchEvents, isTaskResultRelevantToAgent } from '../context/batch.js';
-import { bookForDelegation, ensureTaskBook, findBookHoldingPending, removeTaskBook, syncAggregateTaskViews, } from './taskBookkeeping.js';
+import { bookForDelegation, ensureTaskBook, findBookHoldingPending, removeTaskBook, } from './taskBookkeeping.js';
 // ── outcomeFromEvent: incoming wire event → Outcome ──────────────────────────
 /**
  * Converts a raw incoming event into the single Outcome that re-enters the
@@ -480,5 +480,4 @@ export function applyOutcomeToCtx(ctx, outcome) {
         default:
             break;
     }
-    syncAggregateTaskViews(ctx);
 }

package/dist/runtime/taskBookkeeping.d.ts

@@ -26,10 +26,11 @@ export declare function hasDelegatedAgreement(ctx: Ctx, agreementId: string): bo
  * focused task. Leaves sibling entries (and the coordinator lane bucket) alone.
  */
 export declare function removeTaskBook(ctx: Ctx, taskId: string): void;
-/** Refresh deprecated aggregate views from the per-task map. */
-export declare function syncAggregateTaskViews(ctx: Ctx): void;
 /**
  * Migrate a pre-ZIG-977 persisted ctx (lane-level pendingSubtasks /
  * collectedResults / delegatedAgreementIds) into the tasks map.
+ * ZIG-1057: the deprecated lane aggregates are no longer auto-synced —
+ * readers use allPendingSubtasks / allCollectedResults / allDelegatedAgreementIds.
+ * This migrator stays so a session persisted before the tasks map still boots.
  */
 export declare function migrateLegacyTaskFields(existing: Record<string, unknown>): Record<string, TaskBookkeeping>;

package/dist/runtime/taskBookkeeping.js

@@ -106,15 +106,12 @@ export function removeTaskBook(ctx, taskId) {
         ctx.activeAgreementId = nextId ? (ctx.tasks[nextId]?.agreementId ?? null) : null;
     }
 }
-/** Refresh deprecated aggregate views from the per-task map. */
-export function syncAggregateTaskViews(ctx) {
-    ctx.pendingSubtasks = allPendingSubtasks(ctx);
-    ctx.collectedResults = allCollectedResults(ctx);
-    ctx.delegatedAgreementIds = allDelegatedAgreementIds(ctx);
-}
 /**
  * Migrate a pre-ZIG-977 persisted ctx (lane-level pendingSubtasks /
  * collectedResults / delegatedAgreementIds) into the tasks map.
+ * ZIG-1057: the deprecated lane aggregates are no longer auto-synced —
+ * readers use allPendingSubtasks / allCollectedResults / allDelegatedAgreementIds.
+ * This migrator stays so a session persisted before the tasks map still boots.
  */
 export function migrateLegacyTaskFields(existing) {
     if (existing.tasks && typeof existing.tasks === 'object') {

package/dist/server/tools/tier1/protocolRunner.js

@@ -183,11 +183,9 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
             });
         }
         case 'task-update': {
-            // ZIG-957: canonical tool param is `state` (MCP + REST). Accept legacy
-            // `status` so fleet prompts that still emit it keep working.
-            const terminalRaw = (typeof payload.state === 'string' && payload.state) ||
-                (typeof payload.status === 'string' && payload.status) ||
-                '';
+            // ZIG-1057: `state` only — legacy `status` alias removed. Fleet prompts
+            // must emit state (coffee / fruit / ledger / agent-definer).
+            const terminalRaw = typeof payload.state === 'string' && payload.state ? payload.state : '';
             if (!payload.taskId || !terminalRaw)
                 return null;
             const state = normalizeState(terminalRaw);

package/dist/server/tools/tier1/protocolTools.js

@@ -34,8 +34,8 @@ function handlerFor(operation) {
 }
 export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service', 'link'], description: "Contract type. Defaults to service. 'link' proposes a bilateral trust link (no work, no money)." }, parentAgreementId: 'string', parentTaskId: 'string', providerId: { type: 'string', description: 'Who does the work — required on direct proposals. Pass your own id when YOU are offering to do the work, or the proposedTo id when you are commissioning the RECIPIENT (any other third party needs a matching published offer). On a broadcast: omit for a quest (the claimer works, you pay), or pass your own id to publish a standing offer (you work, the claimer pays). The payer is always derived as the non-providing side.' }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00. Quote it to a human in the same units the agreement charges.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', billing: { type: 'string', enum: ['total', 'per_task'], description: "How price reads: 'total' (default, escrowed and paid at the end) or 'per_task' (a rate settled as each task completes — standing agreements only, and the default for a hire)." }, agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-propose'), { description: 'Propose an agreement — direct, broadcast, or link; there are no separate publish tools. Direction is stated, never guessed: providerId = your own id ("I work, you pay") or providerId = proposedTo ("you work, I pay") on direct proposals. Broadcast with proposedTo="everyone" (fully public) or "org" (your org only): no providerId publishes a QUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). engagementKind "link" with proposedTo = an agent id proposes bilateral trust. engagementKind defaults to service. Agreements are STANDING by default (no expiry, unlimited tasks under one agreement); set expiresAt or maxExecutions only when the engagement should end on its own.', isAgreementCreation: true });
 export const agreementSubcontractTool = defineTool('agreement_subcontract', { description: { type: 'string', required: true }, executorId: { type: 'string', required: true }, parentAgreementId: { type: 'string', required: true }, parentTaskId: 'string', payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00. Quote it to a human in the same units the agreement charges.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string', plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-subcontract'), { description: 'Delegate work to another agent under an existing parent agreement. Requires parentAgreementId.', isAgreementCreation: true });
-export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement-respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass.' });
-export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement-claim'), { description: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.' });
+export const agreementRespondTool = defineTool('agreement_respond', { agreementId: { type: 'string', required: true }, action: { type: 'string', required: true, enum: ['approve', 'reject'] } }, handlerFor('agreement-respond'), { description: 'Approve or reject a pending DIRECT agreement proposal addressed to you. Open broadcasts (quests, standing offers, link invites) have no personal approval slot — claim those with agreement_claim instead, or ignore them to pass. ONE exception: a hand-off that pins YOU as provider carries your pending approval even as an open broadcast — approving consents to serving whoever claims it (the row stays open for claims); rejecting cancels the hand-off. Ignoring it leaves the hand-off unclaimable, so always respond.' });
+export const agreementClaimTool = defineTool('agreement_claim', { agreementId: { type: 'string', required: true, description: 'The open agreement to claim (quest / offer / link invite id)' } }, handlerFor('agreement-claim'), { description: 'Claim an open broadcast agreement by id — a quest (you do the work, the publisher pays), a standing offer (you buy, the publisher works), a hand-off (providerPinned: the publisher\'s hired agent works FOR you — you become the customer, and the payer when it is priced), or a link invite (bilateral trust forms immediately). You become the open party and the agreement activates. A hand-off is claimable only after its provider has accepted (409 until then). Find quests/offers with marketplace_view; direct proposals are approved with agreement_respond instead, not claimed.' });
 export const taskSetResultTool = defineTool('task_set_result', {
     taskId: { type: 'string', required: true },
     // ZIG-957: same param name as MCP ziggs_task_set_result / PATCH /tasks/:id/state.
@@ -50,7 +50,21 @@ export const agreementCounterTool = defineTool('agreement_counter', { agreementI
 export const agreementGetTool = defineTool('agreement_get', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-check-proposal'), { description: 'Read the current proposal status for an agreement (pending, approved, rejected, countered, expired).' });
 export const agreementRevokeTool = defineTool('agreement_revoke', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-revoke'), { description: 'Revoke a pending proposal you created so it can no longer be approved. Use when the user has clearly moved on to a different request before responding to the previous proposal card.' });
 export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementId: { type: 'string', required: true } }, handlerFor('agreement-fulfill'), { description: 'END an agreement you provide — permanently. Fulfilling terminates the whole relationship, not one deliverable: every grant it conferred is revoked, its shared space is torn down, and it cannot be reopened. Finished WORK is reported via task_set_result (the task closes; the agreement stays standing for the next task). Only fulfill when the engagement\'s full scope is delivered and nothing more is expected — never a standing hire that just finished a task.' });
-export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', { taskId: { type: 'string', required: true }, stepId: { type: 'string', required: true }, status: { type: 'string', required: true }, result: 'string' }, handlerFor('task-update-plan-step'), { description: "Update the status of a single step within a task's plan." });
+// `status` names its four values here because nothing else does: the backend is
+// the only place the vocabulary was written down, and it now rejects anything
+// outside it. Every reader (the chat step badge, the SDK's own plan formatter)
+// already treats an unrecognised status as unknown, so a guessed one was never
+// going to render — this makes the model's choice a closed set instead.
+export const taskUpdatePlanStepTool = defineTool('task_update_plan_step', {
+    taskId: { type: 'string', required: true },
+    stepId: { type: 'string', required: true },
+    status: {
+        type: 'string',
+        required: true,
+        enum: ['pending', 'in_progress', 'completed', 'skipped'],
+    },
+    result: 'string',
+}, handlerFor('task-update-plan-step'), { description: "Update the status of a single step within a task's plan." });
 export const taskCreateTool = defineTool('task_create', { agreementId: { type: 'string', required: true }, description: { type: 'string', required: true }, parentTaskId: 'string', assigneeId: { type: 'string', description: 'Explicitly hand this task to one specific agent (e.g. a worker your orchestrator selected via agent search) instead of leaving it unassigned. Must be a party on the agreement (payer, provider, creator, or creator agent).' }, inputArtifactIds: { type: 'array', items: { type: 'string' }, description: 'ZIG-734: prior-step output artifact handles for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('task-spawn'), { description: 'Create a new task under an existing approved agreement. Use when the contract is already in place. Pass assigneeId to delegate the task to a specific agent rather than leaving it open.' });
 export const PROTOCOL_TOOLS = [
     agreementProposeTool, agreementSubcontractTool,

package/dist/tools/recordReport.d.ts

@@ -13,8 +13,10 @@ export interface RecordReportInput {
     taskId: string;
     report: TaskReport;
     /**
-     * Primary artifact scope — required when `deliverable` is provided.
-     * Pass exactly one of chatId or agreementId.
+     * Optional container for the deliverable artifact (ZIG-1037 — it used to be
+     * required). The task binding is what makes the deliverable retrievable and
+     * readable by the task's parties; a chat or agreement only widens where it also
+     * shows up. Pass at most one; when both arrive, agreementId wins.
      */
     chatId?: string;
     agreementId?: string;

package/dist/tools/recordReport.js

@@ -10,21 +10,37 @@ import { ArtifactsClient, updateTaskState, } from '@ziggs-ai/api-client';
  */
 export async function recordReport(input) {
     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');
+    // ZIG-1037: no container needed. The deliverable is bound to its task, which
+    // is what makes it retrievable as `via=task:<taskId>` and readable by the
+    // task's parties — a chat or agreement was never what made that work. Both
+    // containers at once IS still a mistake (only one takes effect), so resolve it
+    // here the way artifact_record does rather than letting the client throw
+    // at the last step of a finished task.
+    const scope = agreementId ? { agreementId } : chatId ? { chatId } : {};
+    // Deliverable FIRST, then close the task.
+    //
+    // The old order completed the task and then wrote the artifact with the
+    // soft-failing `write`, so a wire error left a task marked completed whose
+    // deliverable had silently vanished. Recording first means a failure here
+    // leaves the task open — the honest state, and one a retry can finish. The
+    // idempotency key is derived from the task, so that retry reuses the artifact
+    // row instead of recording the deliverable twice.
+    let artifactId;
+    if (deliverable) {
+        const artifactsClient = new ArtifactsClient(creds.operatorKey, creds.agentId);
+        ({ artifactId } = await artifactsClient.writeStrict({
+            text: deliverable,
+            content_type: 'result',
+            taskId,
+            ...scope,
+            visibility: 'chat',
+            // Deterministic, not random: one deliverable per task, so a replay of this
+            // whole function reproduces the key and dedups server-side.
+            idempotencyKey: `task-result:${taskId}`,
+        }));
     }
     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 };
+    // The artifactId was being discarded even though RecordReportResult declares
+    // it — the caller had no way to reference the deliverable it just recorded.
+    return artifactId ? { taskId, artifactId } : { taskId };
 }

package/dist/types.d.ts

@@ -188,13 +188,13 @@ export interface Ctx {
     activeAgreementId: string | null;
     pendingProposalAgreementId: string | null;
     /**
-     * Aggregate views over `tasks` (all engagements in the lane). Kept in sync by
-     * applyOutcomeToCtx / bootstrapCtx so existing workflow `when` guards that
-     * read these fields (e.g. motifs awaitingAll) keep working after ZIG-977.
-     * Prefer reading `tasks[taskId]` when you need per-task isolation.
+     * @deprecated ZIG-1057 — unused mirrors; always `{}` / `[]` after bootstrap.
+     * Read via `allPendingSubtasks` / `allCollectedResults` / `allDelegatedAgreementIds`.
      */
     pendingSubtasks: Record<string, PendingSubtask>;
+    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
     collectedResults: CollectedSubtaskResult[];
+    /** @deprecated ZIG-1057 — see `pendingSubtasks`. */
     delegatedAgreementIds: string[];
     toolResults: ToolResultEntry[];
     lastOutcome: Outcome;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.7.1",
+    "@ziggs-ai/api-client": "^0.8.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",