@ziggs-ai/agent-sdk 0.23.0 → 0.24.0

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

@@ -370,6 +370,12 @@ export interface ContextSnapshot {
     [key: string]: unknown;
 }
 export interface ReadContextOpts {
+    workScopes?: Array<{
+        agreementId?: string;
+        taskId?: string;
+        messageId?: string;
+        artifactId?: string;
+    }>;
     maxMessages?: number;
 }
 /**
@@ -475,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;
@@ -506,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.23.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.22.0",
+    "@ziggs-ai/api-client": "0.23.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",