@ziggs-ai/agent-sdk 0.22.0 → 0.24.0

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

@@ -60,7 +60,7 @@ function handlerFor(toolName) {
         return result;
     };
 }
-export const agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, 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. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. 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 REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. 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 agreementProposeTool = defineTool('agreement_propose', { description: { type: 'string', required: true }, proposedTo: { type: 'string', required: true }, engagementKind: { type: 'string', enum: ['hire', 'service'], description: 'Contract type. Defaults to service. For a bilateral trust link, use link_propose.' }, parentAgreementId: 'string', providerId: { type: 'string', description: AGREEMENT_PROPOSE_PROVIDER_ID_DESCRIPTION }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, lifecycle: lifecycleParam, expiresAt: 'string', maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, 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. Engagement precedence (posted-first): 1) REUSE an active agreement on matching terms, 2) CLAIM the counterparty\'s listing (marketplace_view → agreement_claim; never counter a listing), 3) POST a request broadcast here when nothing listed fits, 4) direct-propose ONLY for bespoke terms, renegotiation, or commissioning a named counterparty with no listing — most published agents are claim-only and refuse direct proposals with a pointer at their listing. 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 REQUEST any agent may claim; providerId = your own id publishes a STANDING OFFER (claiming is agreement_claim; browsing is marketplace_view). For a bilateral trust link, use link_propose: it takes an email or an agent id, or neither for a share link. 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', agreementSubcontractCapability.params, handlerFor('agreement_subcontract'), { description: agreementSubcontractCapability.descriptions.sdk, 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 (requests, 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', agreementClaimCapability.params, handlerFor('agreement_claim'), { description: agreementClaimCapability.descriptions.sdk });
@@ -74,7 +74,7 @@ export const taskSetResultTool = defineTool('task_set_result', {
         description: 'Outcome payload (summary, status, links, …). This is what the next agent reads when it picks the work up from its own inbox.',
     },
 }, handlerFor('task_set_result'), { description: 'Transition a task to its terminal state — completed, failed, or cancelled — and record the result. Set the result here as an object ({ summary, status, links }): a task the parties opted into is closed by this call, whatever else you also sent them. Pass state (not status). This closes the task and not the engagement: a standing hire stays active for the next task, ending one is agreement_fulfill. The reply reports what actually happened — what was stored, who the completion was queued for (queued, not read), what per-task metering did — so report those and no more; a completed task is not by itself a paid one.' });
-export const agreementCounterTool = defineTool('agreement_counter', { agreementId: { type: 'string', required: true }, price: { type: 'number', description: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', description: 'string' }, handlerFor('agreement_counter'), { 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: 'Price in POINTS, as an integer of hundredths — 500 means ϟ5.00. Convert both ways: a human asking for "ϟ2 per task" means 200, not 2. ϟ is the points symbol, not a hundredth.' }, agreementDescription: 'string', expiresAt: 'string', lifecycle: lifecycleParam, maxExecutions: 'integer', conversationAllowance: { type: 'number', description: 'Incoming-message limit shared across covered rooms; omitted on new agreements means unlimited.' }, description: 'string' }, handlerFor('agreement_counter'), { 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_get'), { 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 and it cannot be reopened. Linked chats remain independent rooms governed by their own grants. 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.' });
@@ -85,14 +85,29 @@ export const agreementFulfillTool = defineTool('agreement_fulfill', { agreementI
 // 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 },
+    stepId: { type: 'string', description: 'The step that changed. Omit only when this call is nothing but a waitingOn.' },
     status: {
         type: 'string',
-        required: true,
         enum: ['pending', 'in_progress', 'completed', 'skipped'],
+        description: 'Step progress. Required with stepId.',
     },
     result: 'string',
-}, handlerFor('task_update_plan_step'), { description: "Update the status of a single step within a task's plan." });
+    // Both fields are required, but the required list cannot be declared here:
+    // defineTool reads a sibling `required` as the flag that makes waitingOn
+    // itself mandatory. The backend enforces the pair; the description says so.
+    waitingOn: {
+        type: 'object',
+        properties: {
+            kind: {
+                type: 'string',
+                enum: ['user', 'agent'],
+                description: 'Whether the answer has to come from a person or an agent.',
+            },
+            id: { type: 'string', description: 'Who you asked.' },
+        },
+        description: "Who this task now waits on, because you just asked them: { kind: 'user' | 'agent', id } — both fields required. Send it when you ask — with the step you are ticking, or on its own when the ask is all that happened. Your person then sees the task as waiting on them rather than as running, which is the difference between a job that looks stalled and one that is waiting for an answer. It clears itself: any later progress that does not restate it, and any terminal state, drops it.",
+    },
+}, handlerFor('task_update_plan_step'), { description: "Update the status of a single step within a task's plan, and say who you are waiting on when you have just asked somebody. A task with no plan can still carry the waiting-on on its own." });
 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: 'Prior-step output artifact handles, for structured input links.' }, plan: { type: 'object' }, planReviewTiming: planReviewTimingParam, requireMidWorkPlanAck: 'boolean', dueAt: dueAtParam, checkBack: checkBackParam }, handlerFor('task_create'), { 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. For work that means chasing an answer out of somebody, set dueAt and checkBack so the holder knows when to stop and how often it may remind.' });
 export const PROTOCOL_TOOLS = [
     agreementProposeTool, agreementSubcontractTool,

package/dist/probeChat.d.ts

@@ -0,0 +1,12 @@
+/**
+ * One classifier for store-publish probe rooms.
+ *
+ * The runner mints `probe_<agentId>_<ts>`. An id prefix must not buy
+ * capability evidence or a canned brain reply; it only names the room so
+ * inbox pin and wake order can find it. Capability vs liveness is decided
+ * by the store sync, not by this prefix.
+ */
+export declare const PROBE_CHAT_ID_PREFIX = "probe_";
+export declare function isPublishProbeChat(chatId: string | undefined | null): boolean;
+/** @deprecated use {@link isPublishProbeChat} — same classifier, old name. */
+export declare const isCapabilityProbeSession: typeof isPublishProbeChat;

package/dist/probeChat.js

@@ -0,0 +1,14 @@
+/**
+ * One classifier for store-publish probe rooms.
+ *
+ * The runner mints `probe_<agentId>_<ts>`. An id prefix must not buy
+ * capability evidence or a canned brain reply; it only names the room so
+ * inbox pin and wake order can find it. Capability vs liveness is decided
+ * by the store sync, not by this prefix.
+ */
+export const PROBE_CHAT_ID_PREFIX = 'probe_';
+export function isPublishProbeChat(chatId) {
+    return typeof chatId === 'string' && chatId.startsWith(PROBE_CHAT_ID_PREFIX);
+}
+/** @deprecated use {@link isPublishProbeChat} — same classifier, old name. */
+export const isCapabilityProbeSession = isPublishProbeChat;

package/dist/runtime/PromptBuilder.js

@@ -96,6 +96,8 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         lines.push(this._renderHistory(ctxObj.history, agentId));
         lines.push('');
         lines.push(this._renderAgreements(agreements));
+        if (ctxObj.work)
+            lines.push(`<work-context>\n${JSON.stringify(ctxObj.work)}\n</work-context>`);
         const collected = ctx ? allCollectedResults(ctx) : [];
         if (collected.length) {
             lines.push('');
@@ -177,6 +179,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         if (eventType === 'message_sent') {
             return `<event type="${eventType}" from="${from}">\nYour message was delivered. Do not repeat it.\n</event>`;
         }
+        const agreementContext = evAny.agreementContext ? `Service agreement context: ${JSON.stringify(evAny.agreementContext)}\nTool access requires separate grants. Zero remaining messages does not prevent answering the final admitted message.\n` : '';
         const content = event.text || event.result || event.content;
         if (!content)
             return `<event type="${eventType}" from="${from}">(Empty)</event>`;
@@ -184,7 +187,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         // Matches MAX_MSG_CHARS in runTurn.ts — the incoming instruction shouldn't
         // be truncated tighter than what the agent itself is allowed to send back.
         const display = str.length > 3500 ? str.slice(0, 3500) + '...' : str;
-        return `<event type="${eventType}" from="${from}">\n${display}\n</event>`;
+        return `<event type="${eventType}" from="${from}">\n${agreementContext}${display}\n</event>`;
     }
     _renderTaskResultEvent(task, from) {
         const lines = [];

package/dist/runtime/agreementContext.d.ts

@@ -0,0 +1,5 @@
+/** Enrich each wake from the agreement it actually names, never from the room's
+ * latest deal. Reads use the agent's credentials; no grants are inferred here. */
+export declare function withAgreementContext(event: unknown, read: (agreementId: string) => Promise<unknown>): Promise<unknown>;
+/** Free chat supplies conversation context, never consent to another engagement. */
+export declare function permitsAutomaticMandate(event: unknown): boolean;

package/dist/runtime/agreementContext.js

@@ -0,0 +1,75 @@
+const row = (value) => value && typeof value === 'object' ? value : {};
+/** Enrich each wake from the agreement it actually names, never from the room's
+ * latest deal. Reads use the agent's credentials; no grants are inferred here. */
+export async function withAgreementContext(event, read) {
+    const reads = new Map();
+    const context = (id) => {
+        if (!reads.has(id))
+            reads.set(id, (async () => {
+                try {
+                    let timer;
+                    const agreement = row(await Promise.race([
+                        read(id),
+                        new Promise((_, reject) => {
+                            timer = setTimeout(() => reject(new Error('Agreement read timed out')), 5_000);
+                        }),
+                    ]).finally(() => { if (timer)
+                        clearTimeout(timer); }));
+                    if (agreement.agreementId !== id)
+                        throw new Error('Agreement is unavailable');
+                    const terms = row(agreement.terms);
+                    const usage = row(agreement.conversationUsage);
+                    const money = row(agreement.money);
+                    const limit = typeof terms.conversationAllowance === 'number' ? terms.conversationAllowance : null;
+                    const used = typeof usage.messages === 'number' ? usage.messages : 0;
+                    return {
+                        agreementId: id, available: true,
+                        freeConversation: row(agreement.metadata).freeConversation === true,
+                        status: agreement.status,
+                        relationship: agreement.engagementKind === 'link' || row(agreement.metadata).freeConversation === true,
+                        interactionMode: terms.interactionMode ?? 'both',
+                        parentAgreementId: agreement.parentAgreementId ?? null,
+                        allowanceScope: terms.conversationAllowanceScope ?? 'direct',
+                        scope: terms.description,
+                        lifecycle: terms.lifecycle,
+                        expiresAt: terms.expiresAt ?? null,
+                        maxTasks: terms.maxExecutions ?? null,
+                        wakeCeiling: terms.wakeCeiling ?? null,
+                        messageLimit: limit,
+                        messagesUsed: used,
+                        messagesRemaining: limit === null ? null : Math.max(0, limit - used),
+                        price: money.price ?? 0,
+                        billing: terms.billing ?? 'total',
+                        paymentStatus: money.paymentStatus,
+                        access: 'Tool and resource access requires separate grants.',
+                    };
+                }
+                catch {
+                    return { agreementId: id, available: false,
+                        instruction: 'Agreement terms could not be read. Verify authorization before starting new service work or making commitments.' };
+                }
+            })());
+        return reads.get(id);
+    };
+    const enrich = async (value) => {
+        const frame = row(value);
+        if (frame.type === 'batch' && Array.isArray(frame.events)) {
+            return { ...frame, events: await Promise.all(frame.events.map(enrich)) };
+        }
+        const resource = row(frame.resource);
+        const result = row(frame.result);
+        const id = frame.agreementId ?? resource.agreementId ?? result.agreementId ?? row(result.agreement).agreementId;
+        if (typeof id !== 'string' || !id)
+            return value;
+        return { ...frame, agreementContext: await context(id) };
+    };
+    return enrich(event);
+}
+/** Free chat supplies conversation context, never consent to another engagement. */
+export function permitsAutomaticMandate(event) {
+    const frame = row(event);
+    if (frame.type === 'batch' && Array.isArray(frame.events))
+        return frame.events.every(permitsAutomaticMandate);
+    const context = row(frame.agreementContext);
+    return context.relationship !== true && context.freeConversation !== true && context.available !== false;
+}

package/dist/runtime/mandateDeclaration.d.ts

@@ -6,4 +6,4 @@ import type { ToolManager } from '../tools/ToolManager.js';
  * declaration, the model already made one, or this wake is not running inside a
  * job at all.
  */
-export declare function withDeclaredMandate(args: Record<string, unknown>, toolName: string | null | undefined, toolManager: ToolManager | undefined, activeAgreementId: string | null | undefined): Record<string, unknown>;
+export declare function withDeclaredMandate(args: Record<string, unknown>, toolName: string | null | undefined, toolManager: ToolManager | undefined, activeAgreementId: string | null | undefined, allowSpendingMandate?: boolean): Record<string, unknown>;

package/dist/runtime/mandateDeclaration.js

@@ -30,14 +30,14 @@
  */
 const MANDATE_PARAM_NAMES = ['mandateAgreementId', 'parentAgreementId'];
 /** The mandate parameter this tool declares, if it declares one. */
-function mandateParamOf(toolName, toolManager) {
+function mandateParamOf(toolName, toolManager, allowSpendingMandate = true) {
     if (!toolName)
         return null;
     const schema = toolManager?.getTool?.(toolName)?.schema;
     const properties = schema?.function?.parameters?.properties;
     if (!properties)
         return null;
-    for (const name of MANDATE_PARAM_NAMES) {
+    for (const name of (allowSpendingMandate ? MANDATE_PARAM_NAMES : ['parentAgreementId'])) {
         if (Object.prototype.hasOwnProperty.call(properties, name))
             return name;
     }
@@ -50,10 +50,10 @@ function mandateParamOf(toolName, toolManager) {
  * declaration, the model already made one, or this wake is not running inside a
  * job at all.
  */
-export function withDeclaredMandate(args, toolName, toolManager, activeAgreementId) {
+export function withDeclaredMandate(args, toolName, toolManager, activeAgreementId, allowSpendingMandate = true) {
     if (!activeAgreementId)
         return args;
-    const param = mandateParamOf(toolName, toolManager);
+    const param = mandateParamOf(toolName, toolManager, allowSpendingMandate);
     if (!param)
         return args;
     if (args[param] !== undefined)

package/dist/runtime/runTurn.js

@@ -1,3 +1,4 @@
+import { permitsAutomaticMandate } from './agreementContext.js';
 import { isAgreementId } from '@ziggs-ai/api-client';
 import { outcomeFromActionResult } from './buildOutcome.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
@@ -267,7 +268,7 @@ export async function runTurn(input) {
                 catch { }
                 // Say which job this is part of, when the tool asks and the model did
                 // not. The runtime knows; the model would have to be told.
-                args = withDeclaredMandate(args, toolName, toolManager, ctx.activeAgreementId);
+                args = withDeclaredMandate(args, toolName, toolManager, ctx.activeAgreementId, permitsAutomaticMandate(incomingEvent));
                 const decision = { action: matchingAction, tool: toolName, args };
                 const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, incomingEvent, addToolUsage, ctx.identity.agentId, Array.isArray(ctxObj.agreements)
                     ? ctxObj.agreements
@@ -324,7 +325,7 @@ export async function runTurn(input) {
             // Same mandate declaration as the tool-call path above. Both routes reach
             // the same tools, so filling it on only one would make the excuse depend on
             // which shape the model happened to answer in.
-            decision.args = withDeclaredMandate((decision.args ?? {}), actionDef?.tool, toolManager, ctx.activeAgreementId);
+            decision.args = withDeclaredMandate((decision.args ?? {}), actionDef?.tool, toolManager, ctx.activeAgreementId, permitsAutomaticMandate(incomingEvent));
             if (decision.thought)
                 await emitThought(decision.thought);
             // 2-call streaming: if this is a respond action (has receiverId, no bound tool),

package/dist/runtime/wakeEffects.d.ts

@@ -7,6 +7,11 @@ export interface WorkScope {
 export declare function uniqueWorkScope(scopes: WorkScope[]): WorkScope;
 /** Only structured host/backend fields are authority; message text and timer reasons are not. */
 export declare function workScopeFromWake(event: unknown, sessionId?: string): WorkScope;
+/** One packet per distinct work item in a batch; never union their authority. */
+export declare function contextScopesFromWake(event: unknown, sessionId: string): Array<WorkScope & {
+    messageId?: string;
+    artifactId?: string;
+}>;
 /** Per-wake observation, including effects nested inside tools and cross-room sends. */
 export declare class WakeEffects {
     private readonly initialScope;

package/dist/runtime/wakeEffects.js

@@ -25,9 +25,22 @@ export function workScopeFromWake(event, sessionId) {
     const agreementId = id(rec.agreementId) ?? id(resource.agreementId) ?? id(task.agreementId)
         ?? agreementIdFromLane(rec.chatId) ?? agreementIdFromLane(resource.chatId)
         ?? agreementIdFromLane(sessionId) ?? undefined;
-    const taskId = id(rec.taskId) ?? id(resource.taskId) ?? id(task.taskId);
+    const taskId = id(rec.taskId) ?? id(resource.taskId) ?? id(task.taskId) ?? (resource.kind === 'task' ? id(resource.resourceId) : undefined);
     return { ...(agreementId ? { agreementId } : {}), ...(taskId ? { taskId } : {}) };
 }
+/** One packet per distinct work item in a batch; never union their authority. */
+export function contextScopesFromWake(event, sessionId) {
+    const frame = record(event);
+    if (frame.type === 'batch' && Array.isArray(frame.events)) {
+        return [...new Map(frame.events.flatMap(e => contextScopesFromWake(e, sessionId)).map(scope => [JSON.stringify(scope), scope])).values()];
+    }
+    const scope = workScopeFromWake(event, sessionId);
+    const messageId = frame.type === 'message' ? id(frame.messageId) : undefined;
+    const resource = record(frame.resource);
+    const artifactId = resource.kind === 'artifact' ? id(resource.resourceId) : undefined;
+    return scope.agreementId || scope.taskId || messageId || artifactId
+        ? [{ ...scope, ...(messageId ? { messageId } : {}), ...(artifactId ? { artifactId } : {}) }] : [];
+}
 const TASK_WRITES = new Set(['task_create', 'task_set_result', 'task_update_plan_step', 'task_replace_plan']);
 /** Per-wake observation, including effects nested inside tools and cross-room sends. */
 export class WakeEffects {

package/dist/tools/capabilityAdapter.js

@@ -35,6 +35,7 @@ export function toolFromCapability(cap) {
             baseUrl: process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined,
             webUrl: process.env.ZIGGS_WEB_URL,
             surface: 'sdk',
+            serviceAgreementId: typeof ctx.serviceAgreementId === 'string' ? ctx.serviceAgreementId : undefined,
         };
         return cap.handler(args, env);
     }, { description: cap.descriptions.sdk, ...(cap.sdkOptions ?? {}) });

package/dist/types.d.ts

@@ -5,6 +5,7 @@
  * Every state — parked or thinking — re-enters with exactly one Outcome.
  */
 import type { AgreementParties } from '@ziggs-ai/api-client';
+import type { ContextSnapshotResult } from '@ziggs-ai/api-client/http';
 import type { AgentNeed } from './tools/needs.js';
 export interface AgreementRef {
     agreementId: string;
@@ -350,6 +351,7 @@ export interface SnapshotParticipant {
 export interface ContextSnapshot {
     history: HistoryEntry[];
     agreements: unknown[];
+    artifacts?: ContextSnapshotResult['artifacts'];
     agents: SnapshotParticipant[];
     users: SnapshotParticipant[];
     timelineSummary?: string | null;
@@ -368,6 +370,12 @@ export interface ContextSnapshot {
     [key: string]: unknown;
 }
 export interface ReadContextOpts {
+    workScopes?: Array<{
+        agreementId?: string;
+        taskId?: string;
+        messageId?: string;
+        artifactId?: string;
+    }>;
     maxMessages?: number;
 }
 /**
@@ -473,6 +481,8 @@ export type Effect = {
 } | {
     kind: 'tool-call';
     sessionId: string;
+    /** Exact work scope from this wake, independent of connection delegation. */
+    serviceAgreementId?: string;
     name: string;
     args: unknown;
     memory?: MemoryStore;
@@ -504,11 +514,13 @@ export type Effect = {
     receiverId?: string;
     text: string;
     messageId?: string;
+    conversationAgreementId?: string;
 } | {
     kind: 'record-event';
     sessionId: string;
     entry: RecordedEntry;
     idempotencyKey?: string;
+    serviceAgreementId?: string;
 };
 /**
  * Typed result map. With this shape, `await eff({ kind: 'read-context', .. })`

package/package.json

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