@ziggs-ai/agent-sdk 0.9.0 → 0.10.0

package/dist/AgentHost.d.ts

@@ -71,7 +71,10 @@ export interface AgentHostOptions {
     agentId?: string;
     name?: string | null;
     wsUrl?: string;
+    /** Store-facing one-liner. See DefineAgentInput.description. */
     description?: string;
+    /** Claude-brain system prompt (ZIG-1080); falls back to `description`. */
+    systemPrompt?: string;
     specialization?: string | null;
     tools?: ToolDefinition[];
     taskTools?: 'all' | 'none' | string[];

package/dist/AgentHost.js

@@ -90,7 +90,12 @@ function createBackendServices(options) {
     const agentId = options.agentId;
     const artifactsClient = new ArtifactsClient(operatorKey, agentId);
     const contextReadClient = new ContextReadClient(operatorKey, agentId);
-    const promptBuilder = new PromptBuilder({ description: options.description, specialization: options.specialization });
+    // ZIG-1080: the role text is the prompt when the author split the two; the
+    // store-facing `description` is only the fallback for agents that never did.
+    const promptBuilder = new PromptBuilder({
+        description: options.systemPrompt || options.description,
+        specialization: options.specialization,
+    });
     const taskService = new TaskService(operatorKey, agentId);
     const agreementService = new AgreementService(operatorKey, agentId);
     const telemetryClient = new TelemetryClient(operatorKey, agentId);
@@ -145,6 +150,7 @@ export class AgentHost {
             name: resolved.name || null,
             wsUrl: resolved.wsUrl,
             description: resolved.description || 'A helpful assistant',
+            systemPrompt: resolved.systemPrompt,
             specialization: resolved.specialization ?? null,
             tools: resolved.tools || [],
             taskTools: resolved.taskTools,
@@ -268,6 +274,7 @@ export class AgentHost {
                 workflow,
                 toolManager: services.toolManager,
                 description: this.options.description,
+                systemPrompt: this.options.systemPrompt,
                 specialization: this.options.specialization,
                 model: resolveClaudeModel(this.options.model, this.options.services?.llm?.model),
                 anthropicKey: this.options.anthropicKey,

package/dist/agent/ClaudeSdkAgent.d.ts

@@ -21,7 +21,10 @@ export type CognitionKind = 'fsm' | 'claude-sdk';
 export interface ClaudeSdkAgentOptions {
     workflow: Workflow;
     toolManager: ToolManager;
+    /** Store-facing one-liner. Used as the role block only when `systemPrompt` is absent. */
     description: string;
+    /** The agent's system prompt (ZIG-1080). Preferred over `description` for the role block. */
+    systemPrompt?: string;
     specialization?: string | null;
     model: string;
     anthropicKey: string;
@@ -44,7 +47,7 @@ export interface ClaudeSdkAgentOptions {
 export declare class ClaudeSdkAgent {
     workflow: Workflow;
     toolManager: ToolManager;
-    private description;
+    private rolePrompt;
     private specialization;
     private model;
     private anthropicKey;

package/dist/agent/ClaudeSdkAgent.js

@@ -155,7 +155,7 @@ function resolveOnBehalfAgreementId(rawEvent, contextSnap, agentId, sessionId) {
 export class ClaudeSdkAgent {
     workflow;
     toolManager;
-    description;
+    rolePrompt;
     specialization;
     model;
     anthropicKey;
@@ -173,7 +173,10 @@ export class ClaudeSdkAgent {
             throw new Error('ClaudeSdkAgent: anthropicKey is required');
         this.workflow = opts.workflow;
         this.toolManager = opts.toolManager;
-        this.description = opts.description;
+        // ZIG-1080: the prompt and the store blurb are two different strings. Agents
+        // written before the split still carry the prompt in `description`, so fall
+        // back to it rather than silently dropping their role.
+        this.rolePrompt = opts.systemPrompt || opts.description;
         this.specialization = opts.specialization ?? null;
         this.model = opts.model;
         this.anthropicKey = opts.anthropicKey;
@@ -259,7 +262,7 @@ export class ClaudeSdkAgent {
         }
         const roleBlock = [
             `## Your role`,
-            this.description,
+            this.rolePrompt,
             this.specialization ? `Specialization: ${this.specialization}` : '',
         ].filter(Boolean).join('\n');
         const systemPrompt = `${CLAUDE_SDK_PROTOCOL}\n\n${roleBlock}`;
@@ -350,7 +353,7 @@ export class ClaudeSdkAgent {
                     if (text) {
                         // Ordinal drawn synchronously so the fire-and-forget below can't
                         // reorder key assignment against other writes of this wake.
-                        const idempotencyKey = wakeKeys.artifactKey();
+                        const idempotencyKey = wakeKeys.artifactKey({ kind: 'thought', text });
                         void eff({ kind: 'record-event', sessionId: identity.sessionId, entry: { kind: 'thought', text }, idempotencyKey })
                             .catch((err) => runtimeLog.warn('ClaudeSdkAgent', `record thought failed session=${identity.sessionId}: ${err.message}`));
                     }

package/dist/agent/claudeSdkTools.js

@@ -8,18 +8,37 @@ import { listGrantsTool } from '../server/tools/tier2/grantsTools.js';
 // messages cover "what woke me and what was just said"; the model can pass a
 // larger maxMessages explicitly when it genuinely needs deeper history.
 const DEFAULT_SNAPSHOT_MAX_MESSAGES = 12;
+/**
+ * First usable string among the candidates, treating blank as absent.
+ *
+ * ZIG-1081: a model that does not know a value fills the field with `""` rather
+ * than omitting it — the schema shows `chatId`, the agent has no way to know it,
+ * so it sends an empty string. Plain `??` let that blank win over the lane
+ * default, and the very next line rejected it as missing. Every wake opened with
+ * a failed `context_snapshot` and a recovery turn.
+ */
+function firstFilled(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate === 'string' && candidate.trim() !== '')
+            return candidate;
+    }
+    return undefined;
+}
 // Named distinctly from ziggs-mcp's per-type `ziggs_context_read`: this is the
 // one-shot aggregate snapshot (grant-fenced server-side), not a cursored read.
 export const contextSnapshotTool = defineTool('context_snapshot', {
-    chatId: { type: 'string', description: 'Chat/session id. Defaults to the current lane session.' },
+    chatId: { type: 'string', description: 'Omit this to snapshot the chat you were woken in — that is the usual case, and you do not need to know its id. Only pass a chatId to snapshot a DIFFERENT chat.' },
     maxMessages: { type: 'number', description: `Message history cap (default ${DEFAULT_SNAPSHOT_MAX_MESSAGES}). Pass a larger value when you need deeper history.` },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
         throw new Error('context_snapshot requires eff in tool context');
-    const sessionId = args.chatId ?? c.chatId ?? c.sessionId;
-    if (!sessionId)
-        throw new Error('context_snapshot: chatId is required');
+    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    if (!sessionId) {
+        throw new Error('context_snapshot: this wake carries no chat to snapshot. Call it with no arguments ' +
+            'to read the chat you were woken in; if this wake is on an agreement lane with no ' +
+            'single chat, read the agreement instead and pass a chatId from one of its chats.');
+    }
     return c.eff({
         kind: 'read-context',
         sessionId,
@@ -29,22 +48,24 @@ export const contextSnapshotTool = defineTool('context_snapshot', {
     });
 }, { description: 'Read the chat snapshot: the NEWEST maxMessages of history (chronological order), plus agreements, agents, and users for a session.' });
 export const chatSendTool = defineTool('chat_send', {
-    chatId: { type: 'string', description: 'Chat id. Defaults to current session.' },
-    receiverId: { type: 'string', description: 'Recipient user or agent id. Defaults to the sender of the event that woke you — omit when replying to them.' },
+    chatId: { type: 'string', description: 'Omit this to send in the chat you were woken in — that is the usual case. Only pass a chatId to send in a DIFFERENT chat.' },
+    receiverId: { type: 'string', description: 'Recipient user or agent id. Omit when replying to whoever woke you — that is the default.' },
     text: { type: 'string', required: true },
     idempotencyKey: { type: 'string', description: 'Reuse for retry-safe resend of the same logical message.' },
 }, async (args, ctx) => {
     const c = ctx;
     if (!c.eff)
         throw new Error('chat_send requires eff in tool context');
-    const sessionId = args.chatId ?? c.chatId ?? c.sessionId;
-    if (!sessionId)
-        throw new Error('chat_send: chatId is required');
+    const sessionId = firstFilled(args.chatId, c.chatId, c.sessionId);
+    if (!sessionId) {
+        throw new Error('chat_send: this wake carries no chat to send in. Call it with no chatId to reply in ' +
+            'the chat you were woken in, or pass the chatId of the chat you mean.');
+    }
     // Replying to whoever woke you is the overwhelmingly common case; making
     // the model spell it out cost a failed tool call + a full extra LLM turn
     // per reply. Batch/timer wakes carry no sender — those still require an
     // explicit receiverId.
-    const receiverId = args.receiverId ?? c.senderId;
+    const receiverId = firstFilled(args.receiverId, c.senderId);
     if (!receiverId)
         throw new Error('chat_send: receiverId is required (this wake has no sender to default to)');
     // Default to the wake's content-derived key (ZIG-1045): a crash-replay that
@@ -99,12 +120,19 @@ export const listTasksTool = defineTool('task_list', {
     if (!c.agentId)
         throw new Error('task_list: agentId missing from tool context');
     const assignedTo = args.assignedToMe ? c.agentId : args.assignedTo;
+    // ZIG-1092: the lane fences this to the engagement's tasks. Without it the
+    // list is every task the agent's key can reach, across all its customers.
+    const laneId = c.chatId || c.sessionId || undefined;
     return listTasks({
         state: args.state,
         cursor: args.cursor,
         limit: typeof args.limit === 'number' ? args.limit : undefined,
         assignedTo,
-    }, { operatorKey: c.operatorKey, agentId: c.agentId });
+    }, {
+        operatorKey: c.operatorKey,
+        agentId: c.agentId,
+        ...(laneId ? { laneId } : {}),
+    });
 }, {
     description: 'List tasks reachable by this agent (GET /tasks). Scope follows the operator key — same reach as chats and agreements. Optional state / assignee filters and cursor pagination. Use assignedToMe to list your own open work.',
 });

package/dist/defineAgent.js

@@ -35,7 +35,10 @@ export function defineAgent(input) {
     // states/transitions are validated too.
     const workflow = injectTaskIntakeDefault(injectKickoffDefault({
         id: input.agentId,
-        description: input.description,
+        // The workflow description is the agent's role text, which PromptBuilder
+        // renders into <self>. ZIG-1080 split that from the store-facing
+        // `description`: prefer the prompt when the author supplied one.
+        description: input.systemPrompt || input.description,
         initial: input.initial,
         states: input.states,
     }));

package/dist/formatters/HistoryFormatter.js

@@ -126,6 +126,17 @@ export class HistoryFormatter {
             return 'System';
         if (id === agentId)
             return 'You';
+        // ZIG-1137: prefer presentation face when the wire masks the principal.
+        const presentation = participant['presentation'];
+        const faceName = (typeof presentation?.['name'] === 'string' && presentation['name']) ||
+            (typeof presentation?.['persona']?.['name'] === 'string'
+                ? presentation['persona']['name']
+                : null);
+        if (faceName)
+            return `${faceName} (${id})`;
+        if (id.startsWith('rpb_') || id.startsWith('psn_')) {
+            return `${id} (presentation)`;
+        }
         return `${id} (${participant['type'] || 'unknown'})`;
     }
     formatOwner(task, agentId) {

package/dist/ingress/normalizeIncoming.d.ts

@@ -71,6 +71,11 @@ interface WireMetadata {
                 status?: string;
             };
             parties?: WireParties;
+            approvals?: Array<{
+                partyId?: string;
+                status?: string;
+                role?: string;
+            }>;
         };
         agreementId?: string;
     };

package/dist/ingress/normalizeIncoming.js

@@ -45,6 +45,27 @@ function isAlreadyActivatedProposalCreated(metadata) {
     const proposalStatus = agr.proposal?.status;
     return status === 'active' || proposalStatus === 'approved';
 }
+/**
+ * ZIG-1078 — a `proposal_created` notification addressed to a party whose
+ * approval is PENDING is a consent REQUEST, not a status notice. The backend
+ * fans `proposal_created` out specifically to the pending approvers
+ * (ZIG-244), and parking it meant the hand-off provider (ZIG-1059) — or any
+ * agent whose consent a proposal awaits — was alerted and then never looked:
+ * the approval sat pending until a human nudged the chat. Same technique as
+ * isAlreadyActivatedProposalCreated (ZIG-1052): reclassify by what the
+ * embedded agreement SAYS rather than adding a new wake word.
+ */
+function isPendingApprovalRequestNotification(metadata) {
+    if (wireOperation(metadata) !== 'proposal_created')
+        return false;
+    const receiverId = metadata.receiver?.id;
+    if (!receiverId)
+        return false;
+    const approvals = metadata.service?.agreement?.approvals;
+    if (!Array.isArray(approvals))
+        return false;
+    return approvals.some((a) => a && a.partyId === receiverId && a.status === 'pending');
+}
 function isAgreementLifecycleNotification(metadata) {
     const entryType = metadata.entryType || 'message';
     if (entryType !== 'notification')
@@ -53,7 +74,8 @@ function isAgreementLifecycleNotification(metadata) {
     if (typeof operation === 'string' && PROPOSAL_RESOLVED_OPERATIONS.has(operation)) {
         return true;
     }
-    return isAlreadyActivatedProposalCreated(metadata);
+    return (isAlreadyActivatedProposalCreated(metadata) ||
+        isPendingApprovalRequestNotification(metadata));
 }
 function isTerminalTaskState(state) {
     return state === 'completed' || state === 'failed' || state === 'cancelled';

package/dist/pricing/fleetDefaults.d.ts

@@ -19,7 +19,6 @@ export interface ProtocolPricingPayload {
     providerId?: string;
     executorId?: string;
     parentAgreementId?: string;
-    parentTaskId?: string;
     [key: string]: unknown;
 }
 /**
@@ -36,8 +35,6 @@ export declare function applyFleetAgreementPricing(operation: 'agreement-propose
  * out unwidened by `ProtocolPricingPayload`'s `[key: string]: unknown` index.
  */
 export declare function applyFleetCounterPricing<T extends ProtocolPricingPayload>(payload: T, actingAgentId: string): T;
-/** User or agent direct-create / marketplace: default from provider specialist. */
-export declare function resolveDefaultPriceForProvider(providerId: string, description?: string | null, explicitPrice?: number | null): number | null;
 /**
  * Infer fleet actor when tool context omits agentId (ZIG-368 safety net).
  */

package/dist/pricing/fleetDefaults.js

@@ -121,12 +121,6 @@ export function applyFleetCounterPricing(payload, actingAgentId) {
         return payload;
     return { ...payload, price: cents };
 }
-/** User or agent direct-create / marketplace: default from provider specialist. */
-export function resolveDefaultPriceForProvider(providerId, description, explicitPrice) {
-    if (typeof explicitPrice === 'number')
-        return explicitPrice;
-    return resolveDefaultPriceCentsForExecutor(providerId, description);
-}
 /**
  * Infer fleet actor when tool context omits agentId (ZIG-368 safety net).
  */

package/dist/runtime/PromptBuilder.js

@@ -1,6 +1,6 @@
 import { HistoryFormatter, AgreementFormatter } from '../formatters/index.js';
 import { validateContext } from '../cognition/validateContext.js';
-import { isBroadcastTarget } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, isOpaquePresentationRef } from '@ziggs-ai/api-client';
 import { LANE_BOOK_KEY, allCollectedResults, allDelegatedAgreementIds, allPendingSubtasks, } from './taskBookkeeping.js';
 /** Rough chars-per-token ratio for budgeting (English/JSON averages ~4). */
 const CHARS_PER_TOKEN = 4;
@@ -298,16 +298,20 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
                 const pid = parties[field];
                 if (!pid || pid === myAgentId)
                     continue;
+                // Opaque presentation refs are not principal slots (ZIG-1137).
+                if (isOpaquePresentationRef(pid))
+                    continue;
                 if (!agreementParties.has(pid))
                     agreementParties.set(pid, []);
                 agreementParties.get(pid).push({ agreementId: agId ?? '', role });
             }
         }
-        // Chat and transfer surfaces default to the full directory: every chat
-        // counterparty can receive a chat message; every id can receive a transfer
-        // by their principal id until per-wallet routing is wired through.
+        // Chat keeps the full directory — including opaque `rpb_*` / `psn_*` refs
+        // the persona layer may surface. Echo those as chat_send receiverId; the
+        // backend resolves them in-room. Transfer (and any account-id action) must
+        // never list opaque refs — lookup / wake / pay against them 400s (ZIG-1137).
         const chatIds = new Set([...userIds, ...agentIds]);
-        const transferIds = new Set([...userIds, ...agentIds]);
+        const transferIds = new Set([...userIds, ...agentIds].filter((id) => !isOpaquePresentationRef(id)));
         const lines = ['<recipients>'];
         lines.push('<users>');
         if (userIds.size === 0)

package/dist/runtime/runTurn.js

@@ -84,7 +84,7 @@ export async function runTurn(input) {
         if (s.length === 0)
             return;
         try {
-            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s }, idempotencyKey: wakeKeys?.artifactKey() });
+            await eff({ kind: 'record-event', sessionId, entry: { kind: 'thought', text: s }, idempotencyKey: wakeKeys?.artifactKey({ kind: 'thought', text: s }) });
         }
         catch (err) {
             runtimeLog.warn('runTurn', `record-event:thought failed: ${err.message}`);

package/dist/runtime/taskBookkeeping.d.ts

@@ -7,8 +7,6 @@ import type { Ctx, TaskBookkeeping } from '../types.js';
 export declare const LANE_BOOK_KEY = "__lane__";
 export declare function emptyTaskBook(agreementId?: string | null): TaskBookkeeping;
 export declare function ensureTaskBook(ctx: Ctx, taskId: string, agreementId?: string | null): TaskBookkeeping;
-/** Focus task's book, or null when nothing is focused / missing. */
-export declare function focusTaskBook(ctx: Ctx): TaskBookkeeping | null;
 /**
  * Book that receives task-delegated / subtask-finished when we know the parent
  * engagement: focus task if assigned, else the coordinator lane bucket.

package/dist/runtime/taskBookkeeping.js

@@ -25,12 +25,6 @@ export function ensureTaskBook(ctx, taskId, agreementId) {
     }
     return book;
 }
-/** Focus task's book, or null when nothing is focused / missing. */
-export function focusTaskBook(ctx) {
-    if (!ctx.activeTaskId)
-        return null;
-    return ctx.tasks?.[ctx.activeTaskId] ?? null;
-}
 /**
  * Book that receives task-delegated / subtask-finished when we know the parent
  * engagement: focus task if assigned, else the coordinator lane bucket.

package/dist/runtime/wakeWriteKeys.js

@@ -99,10 +99,19 @@ export function createWakeWriteKeys(laneKey, event) {
     let ordinal = 0;
     return {
         wakeKey: wakeHash === null ? null : `wk_${wakeHash}`,
-        artifactKey() {
+        artifactKey(content) {
             if (wakeHash === null)
                 return undefined;
-            return `wk_${wakeHash}_a${ordinal++}`;
+            // Content-derived for the same reason messageKey is (ZIG-1045): the
+            // ordinal restarts at a0 on every wake, so a redelivered event whose
+            // re-think writes different artifacts collided with the first wake's
+            // and the backend discarded the new write. Harmless for a breadcrumb,
+            // not for a result artifact — which is the whole deliverable of an
+            // agent like agent-definer. Callers without content keep the ordinal.
+            if (content === undefined)
+                return `wk_${wakeHash}_a${ordinal++}`;
+            const contentHash = sha(typeof content === 'string' ? content : JSON.stringify(content) ?? '').slice(0, 16);
+            return `wk_${wakeHash}_a_${contentHash}`;
         },
         taskStateKey(taskId, state) {
             if (wakeHash === null)

package/dist/server/ZiggsEffectHandler.js

@@ -113,7 +113,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
         state: 'started',
         tool: effect.name,
         ...(argsPreview ? { args: argsPreview } : {}),
-    }, effect.wakeKeys?.artifactKey());
+    }, effect.wakeKeys?.artifactKey({ s: 'started', t: effect.name, a: argsPreview }));
     try {
         const lastUser = roster.users.find((u) => u.userId || u.id);
         // Accumulate token usage from any nested LLM call the tool makes (llmTool),
@@ -150,11 +150,14 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             reportUsage,
             turnScratch: {},
         });
+        // One clip per tool call: this is a full JSON.stringify of the untruncated
+        // result, and the artifact body and the idempotency key want the same string.
+        const clipped = clipForOperationArtifact(result);
         await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
             state: 'completed',
             tool: effect.name,
-            result: clipForOperationArtifact(result),
-        }, effect.wakeKeys?.artifactKey());
+            result: clipped,
+        }, effect.wakeKeys?.artifactKey({ s: 'completed', t: effect.name, r: clipped }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,
@@ -172,7 +175,7 @@ export async function executeToolWithSideEffects(deps, eff, effect, roster) {
             state: 'failed',
             tool: effect.name,
             error: errMsg,
-        }, effect.wakeKeys?.artifactKey());
+        }, effect.wakeKeys?.artifactKey({ s: 'failed', t: effect.name, e: errMsg }));
         sendTelemetry(deps.telemetryClient, buildToolIngestPayload({
             sessionId: effect.sessionId,
             tool: effect.name,

package/dist/server/tasks/TaskService.d.ts

@@ -1,5 +1,5 @@
 import { type Task, type TaskState } from '@ziggs-ai/api-client';
-import type { CountTasksFilters } from '@ziggs-ai/api-client';
+import type { CountTasksFilters, CreateTaskData } from '@ziggs-ai/api-client';
 export declare class TaskService {
     private creds;
     constructor(operatorKey: string, agentId: string);
@@ -7,16 +7,7 @@ export declare class TaskService {
     getActiveTasksForAgent(agentId: string): Promise<Task[]>;
     getActiveTasksForChat(chatId: string): Promise<Task[]>;
     getSubtasks(parentTaskId: string): Promise<Task[]>;
-    spawnUnderAgreement(agreementId: string, taskData: {
-        description: string;
-        parentTaskId?: string;
-        plan?: unknown;
-        planReviewTiming?: string;
-        requireMidWorkPlanAck?: boolean;
-        assigneeId?: string;
-        inputArtifactIds?: string[];
-        idempotencyKey?: string;
-    }): Promise<Task>;
+    spawnUnderAgreement(agreementId: string, taskData: Omit<CreateTaskData, 'agreementId'>): Promise<Task>;
     updateState(taskId: string, state: TaskState, result?: unknown, idempotencyKey?: string): Promise<Task>;
     updatePlanStep(taskId: string, stepId: string, status: string, result?: unknown): Promise<Task>;
     cancel(taskId: string): Promise<Task>;

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

@@ -1,4 +1,4 @@
-import { linkSummary, } from '@ziggs-ai/api-client';
+import { isBroadcastTarget, linkSummary, } from '@ziggs-ai/api-client';
 import { applyFleetCounterPricing, applyFleetPricingForProtocol, } from '../../../pricing/fleetDefaults.js';
 /**
  * ZIG-957 — same summary shape as MCP link mutations / link_* tools.
@@ -22,8 +22,14 @@ function normalizeState(state) {
 }
 // ZIG-793: the `plan` tool-schema is underspecified (`plan: {type:'object'}`,
 // `planReviewTiming: 'string'`), so the LLM emits steps missing stepId/order and an
-// out-of-enum planReviewTiming, which the backend DTO rejects. Normalize in-place here
-// so every op (propose / subcontract / counter / task-spawn) sends a valid plan.
+// out-of-enum planReviewTiming, which the backend DTO rejects. Normalize in-place
+// before the write.
+//
+// ZIG-1095: task-spawn is the only op left that carries a plan. Propose, counter
+// and subcontract used to run this too — and their plans were then dropped on the
+// floor, since no agreement route has ever accepted one.
+// Returns the clamped review timing rather than only writing it back, so the
+// spawn call gets the narrowed type from the one place that does the clamping.
 function normalizePlanInPlace(payload) {
     const plan = payload.plan;
     if (plan && Array.isArray(plan.steps)) {
@@ -41,16 +47,15 @@ function normalizePlanInPlace(payload) {
             };
         });
     }
-    if (payload.planReviewTiming !== undefined &&
-        payload.planReviewTiming !== 'with_proposal' &&
-        payload.planReviewTiming !== 'before_execution') {
-        payload.planReviewTiming = 'with_proposal';
-    }
+    if (payload.planReviewTiming === undefined)
+        return undefined;
+    return payload.planReviewTiming === 'before_execution'
+        ? 'before_execution'
+        : 'with_proposal';
 }
 export async function dispatchProtocolOp(services, payload, chatId, agents = [], actingAgentId = null, wakeKeys = null) {
     if (!payload?.operation)
         return null;
-    normalizePlanInPlace(payload);
     const { operation } = payload;
     const { agreementService, taskService } = services;
     const actorId = actingAgentId?.trim() || null;
@@ -87,9 +92,6 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
                     lifecycle: counterPayload.lifecycle,
                     maxExecutions: counterPayload.maxExecutions,
                     description: counterPayload.description,
-                    plan: counterPayload.plan,
-                    planReviewTiming: counterPayload.planReviewTiming,
-                    requireMidWorkPlanAck: counterPayload.requireMidWorkPlanAck,
                 });
             }
         case 'agreement-check-proposal':
@@ -159,11 +161,12 @@ export async function dispatchProtocolOp(services, payload, chatId, agents = [],
                     agreementId: spawnAgreementId,
                 };
             }
+            const planReviewTiming = normalizePlanInPlace(payload);
             return taskService.spawnUnderAgreement(spawnAgreementId, {
                 description: payload.description,
                 parentTaskId: payload.parentTaskId,
                 plan: payload.plan,
-                planReviewTiming: payload.planReviewTiming,
+                planReviewTiming,
                 requireMidWorkPlanAck: payload.requireMidWorkPlanAck,
                 assigneeId: payload.assigneeId,
                 inputArtifactIds: Array.isArray(payload.inputArtifactIds)
@@ -219,7 +222,7 @@ async function proposeAgreement(services, payload, chatId, _agents, actingAgentI
         throw new Error('agreement-propose requires `description`');
     if (!payload.proposedTo)
         throw new Error('agreement-propose requires `proposedTo` (userId or agentId). To create a task under an existing agreement, use `task_create` instead.');
-    const isBroadcast = payload.proposedTo === 'everyone' || payload.proposedTo === 'org';
+    const isBroadcast = isBroadcastTarget(payload.proposedTo);
     // ZIG-1022: a link proposal is an agreement with engagementKind 'link' —
     // no chat, no money; the target owner approves. Folds the old request_link.
     if (payload.engagementKind === 'link') {

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

@@ -32,8 +32,8 @@ function handlerFor(operation) {
         return result;
     };
 }
-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 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', 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, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, 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' }, 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 }, payerId: 'string', price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', agreementDescription: 'string' }, 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. 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', {
@@ -46,7 +46,7 @@ export const taskSetResultTool = defineTool('task_set_result', {
         description: 'Outcome payload (summary, status, links, …). Finished work is the task result — never a chat message.',
     },
 }, handlerFor('task-update'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Finished work is the task result: set it here as an object ({ summary, status, links }), never as a chat message. Pass state (not status).' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00. Quote it to a human in the same units the agreement charges.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string', plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean' }, handlerFor('agreement-counter-proposal'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
+export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Amount in CENTS — 500 means $5.00, shown as ϟ5.00 in the UI. Convert both ways: a human asking for "ϟ2" or "$2 per task" means 200, not 2. ϟ is the currency symbol, not a cent.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement-counter-proposal'), { description: 'Counter a pending proposal with revised terms instead of approving or rejecting. Check status first with agreement_get.' });
 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.' });

package/dist/tools/capabilityAdapter.js

@@ -10,12 +10,23 @@ export function toolFromCapability(cap) {
     return defineTool(cap.names.sdk, cap.params, async (args, ctx) => {
         const operatorKey = ctx?.['operatorKey'];
         const agentId = ctx?.['agentId'];
+        // ZIG-1092 — the lane was already threaded to this exact point by
+        // ZIG-775's shared executor (`chatId: effect.sessionId` in
+        // executeToolWithSideEffects); it just was not used to narrow anything.
+        // Reading it here makes the fence brain-agnostic by construction: the
+        // Claude brain and the FSM brain both arrive through this adapter.
+        const laneId = ctx?.['chatId'] ||
+            ctx?.['sessionId'];
         if (!operatorKey)
             throw new Error('operatorKey missing from tool context');
         if (cap.needsAgentId && !agentId)
             throw new Error('agentId missing from tool context');
         const env = {
-            creds: { operatorKey, ...(agentId ? { agentId } : {}) },
+            creds: {
+                operatorKey,
+                ...(agentId ? { agentId } : {}),
+                ...(laneId ? { laneId } : {}),
+            },
             // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the
             // shared clients default to HTTP_URL (api-client convention) otherwise.
             baseUrl: process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined,

package/dist/tools/recordReport.js

@@ -12,10 +12,14 @@ export async function recordReport(input) {
     const { creds, taskId, report, chatId, agreementId, deliverable } = input;
     // 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.
+    // task's parties — a chat or agreement was never what made that work.
+    //
+    // ZIG-1075: the agreement still wins here, and this is now the ONE place that
+    // resolves rather than refuses — deliberately, because the caller is not a
+    // model choosing arguments. `recordReport` is handed both ids by the runtime
+    // (the task's agreement and the chat it is running in), so there is no
+    // mistake to surface and nobody to retry: refusing would fail a finished
+    // task's delivery over a pair of ids it did not choose.
     const scope = agreementId ? { agreementId } : chatId ? { chatId } : {};
     // Deliverable FIRST, then close the task.
     //

package/dist/types.d.ts

@@ -385,8 +385,15 @@ export interface RecordedEntry {
 export interface WakeWriteKeys {
     /** Stable id of this wake, or null when its trigger has no durable delivery identity (timer/synthetic frames) — null means writes go keyless, as before. */
     readonly wakeKey: string | null;
-    /** Key for the next artifact write of this wake. Draws a per-wake ordinal — call exactly once per write, at the call site. */
-    artifactKey(): string | undefined;
+    /**
+     * Key for an artifact write of this wake. Pass the artifact's content so the
+     * key is derived from it (ZIG-1045 semantics): a wake writing several
+     * artifacts gets several keys, and a redelivered wake that re-writes the same
+     * content reuses its key instead of colliding on an ordinal slot and being
+     * discarded. Omitting content falls back to a per-wake ordinal — call exactly
+     * once per write in that case.
+     */
+    artifactKey(content?: unknown): string | undefined;
     /** Key for a task state transition. Derived from (taskId, state), so it is stable regardless of tool-call order within the wake. */
     taskStateKey(taskId: string, state: string): string | undefined;
     /**
@@ -512,7 +519,19 @@ export interface ServicesConfig {
 }
 export interface DefineAgentInput {
     agentId: string;
+    /**
+     * Human-facing one-liner: what this agent does, for a buyer reading the store
+     * row. NOT the system prompt — a claude-sdk agent puts its prompt in
+     * `systemPrompt` (ZIG-1080: every claude-sdk agent used to pass its prompt
+     * here, and `deriveAgentRecord` published it straight to the store).
+     */
     description: string;
+    /**
+     * Claude-brain only: the agent's system prompt (its `## Your role` block).
+     * Falls back to `description` when absent, which is what every FSM agent
+     * relies on. Never surfaced in the store.
+     */
+    systemPrompt?: string;
     specialization?: string;
     initial: string;
     states: Record<string, State>;
@@ -534,7 +553,10 @@ export interface AgentConfig {
     anthropicKey: string | undefined;
     operatorKey?: string;
     agentId: string;
+    /** Store-facing one-liner. See DefineAgentInput.description. */
     description: string;
+    /** Claude-brain system prompt; falls back to `description`. */
+    systemPrompt?: string;
     specialization?: string;
     tools: unknown[];
     model: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.9.0",
+  "version": "0.10.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.8.0",
+    "@ziggs-ai/api-client": "^0.9.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",