@ziggs-ai/agent-sdk 0.20.0 → 0.22.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/dist/runtime/wakeOutcome.d.ts

@@ -7,16 +7,49 @@
  * no-op with a reason.
  */
 export type WakeOutcomeKind = 'replied' | 'task-progress' | 'no-op';
+/**
+ * Whether a wake that was ASKED something answered it.
+ *
+ * A wake handed a counterparty's message and a wake handed a notification are
+ * not the same obligation, and the outcome kinds could not tell them apart: an
+ * agent that composed a status answer, wrote it as host output and finished
+ * clean landed on `no-op / llm_no_visible_effect`, the same row a duplicate
+ * echo produces — and an agent that answered by writing the task instead landed
+ * on `task-progress`, which reads like success. Neither says the requester got
+ * nothing.
+ *
+ * `sent: false` carries the reason there was no send, because "it decided not
+ * to" and "it forgot" are both legitimate outcomes and only one of them is a
+ * bug — but they have to be distinguishable to be either.
+ */
+export interface WakeReply {
+    asked: true;
+    sent: boolean;
+    reason?: string;
+}
 export interface WakeOutcome {
     kind: WakeOutcomeKind;
     reason?: string;
+    /** Present only when this wake was handed a question. */
+    reply?: WakeReply;
 }
+/**
+ * Was this wake somebody asking this agent something?
+ *
+ * A counterparty `message` frame is the one shape that earns a reply. Task
+ * results, agreement lifecycle and notifications are news, and the ticket is
+ * explicit that they still finish without sending. The agent's own message
+ * never counts: a self-addressed frame is an echo, not a question.
+ */
+export declare function wakeWasAsked(event: unknown, ownAgentId?: string): boolean;
 export declare function classifyWakeOutcome(input: {
     skippedReason?: string;
     lastOutcomeKind?: string | null;
     llmCalls: number;
     sentMessage?: boolean;
     taskWrite?: boolean;
+    /** This wake was handed a question — see {@link wakeWasAsked}. */
+    asked?: boolean;
 }): WakeOutcome;
 export declare function buildWakeOutcomePayload(input: {
     agentId: string;

package/dist/runtime/wakeOutcome.js

@@ -6,23 +6,67 @@
  * A wake ends in exactly one of: a reply, task progress, or an explicit
  * no-op with a reason.
  */
+const record = (value) => value && typeof value === 'object' && !Array.isArray(value)
+    ? value
+    : {};
+/**
+ * Was this wake somebody asking this agent something?
+ *
+ * A counterparty `message` frame is the one shape that earns a reply. Task
+ * results, agreement lifecycle and notifications are news, and the ticket is
+ * explicit that they still finish without sending. The agent's own message
+ * never counts: a self-addressed frame is an echo, not a question.
+ */
+export function wakeWasAsked(event, ownAgentId) {
+    const frame = record(event);
+    if (frame.type === 'batch' && Array.isArray(frame.events)) {
+        return frame.events.some((item) => wakeWasAsked(item, ownAgentId));
+    }
+    if (frame.type !== 'message')
+        return false;
+    const senderId = typeof frame.senderId === 'string' ? frame.senderId : '';
+    if (!senderId)
+        return false;
+    return !ownAgentId || senderId !== ownAgentId;
+}
 export function classifyWakeOutcome(input) {
+    const sent = Boolean(input.sentMessage) || input.lastOutcomeKind === 'message-sent';
+    // The answer to "was this wake asked something, and did it answer" is
+    // independent of what else the wake did, so it rides alongside the kind
+    // rather than competing with it: a wake can make task progress AND leave the
+    // question it was handed unanswered, and that is exactly the case that used
+    // to disappear.
+    const reply = !input.asked
+        ? undefined
+        : sent
+            ? { asked: true, sent: true }
+            : {
+                asked: true,
+                sent: false,
+                reason: input.skippedReason ??
+                    (input.taskWrite
+                        ? 'recorded_on_the_task_only'
+                        : input.llmCalls > 0
+                            ? 'composed_without_sending'
+                            : 'no_llm'),
+            };
+    const withReply = (outcome) => reply ? { ...outcome, reply } : outcome;
     if (input.skippedReason) {
-        return { kind: 'no-op', reason: input.skippedReason };
+        return withReply({ kind: 'no-op', reason: input.skippedReason });
     }
-    if (input.sentMessage || input.lastOutcomeKind === 'message-sent') {
-        return { kind: 'replied' };
+    if (sent) {
+        return withReply({ kind: 'replied' });
     }
     if (input.taskWrite ||
         input.lastOutcomeKind === 'task-delegated' ||
         input.lastOutcomeKind === 'task-completed' ||
         input.lastOutcomeKind === 'task-progress') {
-        return { kind: 'task-progress' };
+        return withReply({ kind: 'task-progress' });
     }
     if (input.llmCalls > 0) {
-        return { kind: 'no-op', reason: 'llm_no_visible_effect' };
+        return withReply({ kind: 'no-op', reason: 'llm_no_visible_effect' });
     }
-    return { kind: 'no-op', reason: 'no_llm' };
+    return withReply({ kind: 'no-op', reason: 'no_llm' });
 }
 export function buildWakeOutcomePayload(input) {
     return {
@@ -36,6 +80,17 @@ export function buildWakeOutcomePayload(input) {
             effect: 'wake-outcome',
             kind: input.outcome.kind,
             ...(input.outcome.reason ? { reason: input.outcome.reason } : {}),
+            // A wake that was asked something says whether it answered, and why not.
+            // Written flat so a query for unanswered questions is one field compare.
+            ...(input.outcome.reply
+                ? {
+                    asked: true,
+                    answered: input.outcome.reply.sent,
+                    ...(input.outcome.reply.reason
+                        ? { unansweredReason: input.outcome.reply.reason }
+                        : {}),
+                }
+                : {}),
             laneKey: input.laneKey,
             agentId: input.agentId,
         },

package/dist/types.d.ts

@@ -523,8 +523,21 @@ export interface EffectResultMap {
         usage?: LlmResponse['usage'];
     };
     'tool-call': ToolCallResult;
+    /**
+     * `{ ok: true }` said the call did not throw, and a brain reading it had no
+     * way to tell a message that woke the agent it meant to from one the server
+     * widened to the room's humans. The send's own report rides along when the
+     * backend makes one: where it went. Routing is separate from acceptance.
+     */
     'send-message': {
         ok: true;
+        chatId?: string;
+        messageId?: string;
+        delivered?: string;
+        to?: {
+            id: string;
+            type: string;
+        };
     };
     'record-event': {
         ok: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.20.0",
+  "version": "0.22.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.21.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;