@ziggs-ai/agent-sdk 0.20.0 → 0.21.0

package/dist/runtime/AgentMachine.d.ts

@@ -105,6 +105,8 @@ export declare class AgentMachine {
         input: number;
         output: number;
     };
+    /** Last turn skipped the model; host records a no-op naming why. */
+    _skippedReason: string | undefined;
     _lastUserSenderId: string | null;
     _stateTimeoutUnhandled: boolean;
     _transitionTap: ((event: TransitionEvent) => void) | undefined;
@@ -117,6 +119,7 @@ export declare class AgentMachine {
         input: number;
         output: number;
     };
+    get skippedReason(): string | undefined;
     get stateTimeoutUnhandled(): boolean;
     constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, writeKeys }: MachineOptions);
     getSnapshot(): MachineSnapshot;

package/dist/runtime/AgentMachine.js

@@ -41,6 +41,8 @@ export class AgentMachine {
     _draining = false;
     _llmCalls = 0;
     _tokens = { total: 0, input: 0, output: 0 };
+    /** Last turn skipped the model; host records a no-op naming why. */
+    _skippedReason;
     _lastUserSenderId = null;
     _stateTimeoutUnhandled = false;
     _transitionTap;
@@ -49,6 +51,7 @@ export class AgentMachine {
     _maxTurnsWithoutUserInput;
     get llmCalls() { return this._llmCalls; }
     get tokens() { return this._tokens; }
+    get skippedReason() { return this._skippedReason; }
     get stateTimeoutUnhandled() { return this._stateTimeoutUnhandled; }
     constructor({ workflow, executionCore, eff, toolManager, promptBuilder, memory, input, transitionTap, maxTurnsWithoutUserInput, writeKeys }) {
         this.workflow = workflow;
@@ -316,7 +319,7 @@ export class AgentMachine {
         // Thinking: run a turn, produce an outcome, re-step.
         this._running = true;
         try {
-            const { outcome: turnOutcome, toolResults, llmCalls, tokens } = await this.executionCore({
+            const { outcome: turnOutcome, toolResults, llmCalls, tokens, skippedReason } = await this.executionCore({
                 stateId: this.state,
                 statePrompt: sd.prompt,
                 actions: sd.actions,
@@ -331,6 +334,8 @@ export class AgentMachine {
             });
             this.ctx.toolResults = toolResults;
             this._llmCalls += llmCalls;
+            if (skippedReason)
+                this._skippedReason = skippedReason;
             this._turnsSinceUserInput += 1;
             this._tokens.total += tokens.total;
             this._tokens.input += tokens.input;

package/dist/runtime/runTurn.d.ts

@@ -44,6 +44,7 @@ interface RunTurnResult {
         input: number;
         output: number;
     };
+    skippedReason?: string;
 }
 /**
  * Run a single thinking-state turn.

package/dist/runtime/runTurn.js

@@ -112,12 +112,13 @@ export async function runTurn(input) {
         : [];
     const serverContext = await effWithTrace({ kind: 'read-context', sessionId, opts: {} });
     const ctxObj = normalizeContextSnapshot(serverContext);
-    // A message wake whose chat no longer resolves (deleted, or never visible
-    // to this agent) has no world to decide over — deciding anyway means
-    // reasoning about a fabricated empty history plus whatever stale scraps
-    // other fetches returned. Skip the LLM and park. Gated on message wakes
-    // only. a bare agreement id as sessionId is a mis-keyed lane —
-    // loud-log the empty snapshot rather than staying silent.
+    // A wake whose chat no longer resolves (deleted, or never visible to this
+    // agent) has no world to decide over — deciding anyway means reasoning
+    // about a fabricated empty history plus whatever stale scraps other
+    // fetches returned. Skip the LLM and park. Resource wakes used to slip
+    // past a message-only gate and burn a full turn. A bare
+    // agreement id as sessionId is a mis-keyed lane — loud-log the empty
+    // snapshot rather than staying silent.
     if (ctxObj.chatMissing) {
         const looksLikeBareAgreement = isAgreementId(sessionId);
         if (looksLikeBareAgreement) {
@@ -125,15 +126,18 @@ export async function runTurn(input) {
                 `lane was keyed by agreementId instead of the agreement's origin/notification chat; ` +
                 `wake continues with an empty snapshot`);
         }
-    }
-    if (ctxObj.chatMissing && ctx.lastOutcome?.kind === 'message-received') {
-        runtimeLog.warn('runTurn', `chat ${sessionId} not found on backend — skipping message wake (state=${stateId})`);
-        return {
-            outcome: { kind: 'wait' },
-            toolResults: [],
-            llmCalls: 0,
-            tokens: { total: 0, input: 0, output: 0 },
-        };
+        else {
+            // Any wake in a room this agent cannot read — not only
+            // message wakes. Resource notices used to spend a full turn here.
+            runtimeLog.warn('runTurn', `chat ${sessionId} not readable — skipping wake (state=${stateId})`);
+            return {
+                outcome: { kind: 'wait' },
+                toolResults: [],
+                llmCalls: 0,
+                tokens: { total: 0, input: 0, output: 0 },
+                skippedReason: `chat_unreadable:${sessionId}`,
+            };
+        }
     }
     const prompt = promptBuilder.buildFromState({
         statePrompt, actions,

package/dist/runtime/wakeEffects.d.ts

@@ -0,0 +1,35 @@
+import type { Effect } from '../types.js';
+export interface WorkScope {
+    agreementId?: string;
+    taskId?: string;
+}
+/** Never combine a task from one event with an agreement from another. */
+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;
+/** Per-wake observation, including effects nested inside tools and cross-room sends. */
+export declare class WakeEffects {
+    private readonly initialScope;
+    private readonly sessionId?;
+    private readonly inferScope;
+    sentMessage: boolean;
+    taskWrite: boolean;
+    readonly planVersions: Set<string>;
+    readonly sentMessageKeys: Set<string>;
+    /** Agreements the wake's OWN room reported, from its fenced snapshot. */
+    private roomAgreementIds;
+    /** Confirmed task writes: work this wake actually performed. */
+    private taskWrites;
+    constructor(initialScope: WorkScope, sessionId?: string | undefined, inferScope?: boolean);
+    static forWake(event: unknown, sessionId: string): WakeEffects;
+    /**
+     * Structured wake fields first. Otherwise the room's one agreement is the
+     * scope — spend follows who the agent acts for, and in a room that is the
+     * room's agreement — and a confirmed task write names its task only when
+     * the server tied the write to that same agreement. A plan written for
+     * customer A from customer B's room stays billed to B and names no task; a
+     * write whose agreement the server did not report adds nothing but the room.
+     */
+    get scope(): WorkScope;
+    observe(effect: Effect, response: unknown): void;
+}

package/dist/runtime/wakeEffects.js

@@ -0,0 +1,121 @@
+import { agreementIdFromLane } from '@ziggs-ai/api-client';
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const id = (value) => typeof value === 'string' && value.trim() ? value : undefined;
+/** Never combine a task from one event with an agreement from another. */
+export function uniqueWorkScope(scopes) {
+    const agreements = new Set(scopes.map(s => s.agreementId).filter(Boolean));
+    const tasks = new Set(scopes.map(s => s.taskId).filter(Boolean));
+    if (agreements.size > 1 || tasks.size > 1)
+        return {};
+    if (agreements.size && tasks.size && scopes.some(s => s.taskId && !s.agreementId))
+        return {};
+    return {
+        ...(agreements.size ? { agreementId: [...agreements][0] } : {}),
+        ...(tasks.size ? { taskId: [...tasks][0] } : {}),
+    };
+}
+/** Only structured host/backend fields are authority; message text and timer reasons are not. */
+export function workScopeFromWake(event, sessionId) {
+    const rec = record(event);
+    if (rec.type === 'batch' && Array.isArray(rec.events)) {
+        return uniqueWorkScope(rec.events.map(e => workScopeFromWake(e, sessionId)));
+    }
+    const resource = record(rec.resource);
+    const task = rec.type === 'task_result' || rec.type === 'notification' ? record(rec.result) : {};
+    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);
+    return { ...(agreementId ? { agreementId } : {}), ...(taskId ? { taskId } : {}) };
+}
+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 {
+    initialScope;
+    sessionId;
+    inferScope;
+    sentMessage = false;
+    taskWrite = false;
+    planVersions = new Set();
+    sentMessageKeys = new Set();
+    /** Agreements the wake's OWN room reported, from its fenced snapshot. */
+    roomAgreementIds = [];
+    /** Confirmed task writes: work this wake actually performed. */
+    taskWrites = [];
+    constructor(initialScope, sessionId, inferScope = true) {
+        this.initialScope = initialScope;
+        this.sessionId = sessionId;
+        this.inferScope = inferScope;
+    }
+    static forWake(event, sessionId) {
+        const initialScope = workScopeFromWake(event, sessionId);
+        const frame = record(event);
+        const conflictingBatch = frame.type === 'batch' && Array.isArray(frame.events)
+            && !initialScope.agreementId && !initialScope.taskId
+            && frame.events.some(item => Object.keys(workScopeFromWake(item, sessionId)).length > 0);
+        return new WakeEffects(initialScope, sessionId, !conflictingBatch);
+    }
+    /**
+     * Structured wake fields first. Otherwise the room's one agreement is the
+     * scope — spend follows who the agent acts for, and in a room that is the
+     * room's agreement — and a confirmed task write names its task only when
+     * the server tied the write to that same agreement. A plan written for
+     * customer A from customer B's room stays billed to B and names no task; a
+     * write whose agreement the server did not report adds nothing but the room.
+     */
+    get scope() {
+        if (this.initialScope.agreementId || this.initialScope.taskId)
+            return this.initialScope;
+        if (!this.inferScope)
+            return {};
+        const room = new Set(this.roomAgreementIds);
+        if (room.size > 1)
+            return {};
+        const agreementId = [...room][0];
+        if (!agreementId)
+            return uniqueWorkScope(this.taskWrites);
+        const tasks = new Set(this.taskWrites.filter(w => w.agreementId === agreementId).map(w => w.taskId));
+        return { agreementId, ...(tasks.size === 1 ? { taskId: [...tasks][0] } : {}) };
+    }
+    observe(effect, response) {
+        const outer = record(response);
+        if (effect.kind === 'send-message' && outer.ok === true)
+            this.sentMessage = true;
+        // This is the fenced snapshot of the wake's own chat, not an arbitrary
+        // agreement consulted while answering. A room with multiple agreements
+        // remains ambiguous, and cross-room reads cannot change the wake's scope.
+        if (effect.kind === 'read-context' && effect.sessionId === this.sessionId
+            && outer.chatMissing !== true && Array.isArray(outer.agreements)) {
+            for (const row of outer.agreements) {
+                const agreementId = id(record(row).agreementId);
+                if (agreementId)
+                    this.roomAgreementIds.push(agreementId);
+            }
+        }
+        if (effect.kind !== 'tool-call' || outer.ok !== true)
+            return;
+        const result = record(outer.result);
+        if (result.ok === false || result.success === false || result.error)
+            return;
+        const name = effect.name.replace(/^(functions|tools|function|tool)\./, '');
+        if (name === 'chat_send') {
+            this.sentMessage = true;
+            if (id(result.chatId) && id(result.messageId)) {
+                this.sentMessageKeys.add(JSON.stringify([result.chatId, result.messageId]));
+            }
+        }
+        if (TASK_WRITES.has(name))
+            this.taskWrite = true;
+        if ((name === 'task_replace_plan' || name === 'task_update_plan_step') && id(result.taskId)
+            && result.taskId === record(effect.args).taskId && id(result.updatedAt)) {
+            this.planVersions.add(JSON.stringify([result.taskId, result.updatedAt]));
+        }
+        // A confirmed task write identifies work actually performed. A broad
+        // task_list, arbitrary agreement_get or ids in message prose do not.
+        const agreementId = id(result.agreementId);
+        const taskId = id(result.taskId);
+        if (TASK_WRITES.has(name) && taskId) {
+            this.taskWrites.push({ taskId, ...(agreementId ? { agreementId } : {}) });
+        }
+    }
+}

package/package.json

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

package/dist/pricing/fleetFreeTierA.gen.d.ts

@@ -1,6 +0,0 @@
-/**
- * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * Tier A trivial public lookups (free when price omitted).
- */
-export declare const FREE_TIER_A_AGENT_IDS: Set<string>;
-export declare const FREE_TIER_A_COUNT = 4;

package/dist/pricing/fleetFreeTierA.gen.js

@@ -1,11 +0,0 @@
-/**
- * AUTO-GENERATED by scripts/build-fleet-tier-map.mjs — do not edit by hand.
- * Tier A trivial public lookups (free when price omitted).
- */
-export const FREE_TIER_A_AGENT_IDS = new Set([
-    "site-health-checker",
-    "timezone-expert",
-    "uv-index-advisor",
-    "weather-forecaster"
-]);
-export const FREE_TIER_A_COUNT = 4;