@ziggs-ai/agent-sdk 0.5.0 → 0.7.0

package/dist/runtime/runTurn.js

@@ -105,8 +105,18 @@ export async function runTurn(input) {
     // 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: agreement-keyed task lanes (sessionId = agreementId) always trip
-    // chatMissing and must still run.
+    // only. ZIG-975: 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 = typeof sessionId === 'string' &&
+            sessionId.startsWith('agr_') &&
+            !sessionId.startsWith('agrn-');
+        if (looksLikeBareAgreement) {
+            runtimeLog.warn('runTurn', `chatMissing on non-chat sessionId=${sessionId} (state=${stateId}) — ` +
+                `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 {
@@ -367,10 +377,18 @@ export async function runTurn(input) {
                     lastActionDef = actionDef;
                 }
                 catch (err) {
-                    // Both the streaming path AND the non-streaming fallback failed —
-                    // the user got nothing. End the turn with a loud send-failed error.
-                    runtimeLog.error('runTurn', `respond send failed after stream fallback: ${err.message}`);
-                    turnError = { source: 'protocol', cause: 'send-failed' };
+                    if (isReplySlotTaken(err)) {
+                        runtimeLog.warn('runTurn', `reply already persisted under ${streamMessageId} (idempotency 409) — a replay or second host answered this wake first; dropping duplicate`);
+                        allEmittedEvents.push({ type: 'message_duplicate_skipped', receiverId: decision.receiverId, chatId: sessionId, senderId: 'system' });
+                        lastAction = chosenAction;
+                        lastActionDef = actionDef;
+                    }
+                    else {
+                        // Both the streaming path AND the non-streaming fallback failed —
+                        // the user got nothing. End the turn with a loud send-failed error.
+                        runtimeLog.error('runTurn', `respond send failed after stream fallback: ${err.message}`);
+                        turnError = { source: 'protocol', cause: 'send-failed' };
+                    }
                 }
                 break;
             }
@@ -550,7 +568,7 @@ function annotateToolCallDedup(toolCalls, toolManager, initialSawCreate = false)
             sawCreate = true;
             return { tc, skipExecute: false };
         }
-        if (name === 'task_update') {
+        if (name === 'task_set_result') {
             let taskId = null;
             try {
                 const a = JSON.parse(tc.function.arguments || '{}');
@@ -559,7 +577,7 @@ function annotateToolCallDedup(toolCalls, toolManager, initialSawCreate = false)
             catch { }
             const key = taskId || tc.id || '_';
             if (seenUpdateTaskIds.has(key))
-                return { tc, skipExecute: true, skipReason: 'duplicate task_update for same taskId' };
+                return { tc, skipExecute: true, skipReason: 'duplicate task_set_result for same taskId' };
             seenUpdateTaskIds.add(key);
             return { tc, skipExecute: false };
         }
@@ -642,6 +660,20 @@ function truncateMsg(msg) {
         return msg;
     return msg.slice(0, MAX_MSG_CHARS) + `\n\n[truncated to ${MAX_MSG_CHARS} of ${msg.length} chars]`;
 }
+/**
+ * A send rejected with 409 hit the backend's (chatId, messageId) idempotency
+ * gate on a wake-derived id: this wake's reply already exists. Two legal ways
+ * that happens — a crash-replay re-ran the wake, or a second host raced the
+ * same at-least-once delivery — and in both the re-run LLM produced different
+ * text, so the backend rejects instead of no-op'ing (ZIG-932 treats
+ * same-key-same-content as replay, same-key-different-content as conflict).
+ * The user already has the winner's reply. Re-sending under a fresh id would
+ * double-message; failing the turn marks an answered wake as an error. Treat
+ * it as delivered-by-the-other-attempt and move on.
+ */
+function isReplySlotTaken(err) {
+    return err?.status === 409;
+}
 async function executeSendMessage(decision, eff, sessionId) {
     // Callers (executeDecision) guarantee message + receiverId, and sessionId is
     // always ctx.identity.sessionId. A send failure throws to the turn loop,
@@ -652,7 +684,15 @@ async function executeSendMessage(decision, eff, sessionId) {
     // to the current session otherwise.
     const targetSessionId = decision.chatId || sessionId;
     const safeMessage = truncateMsg(decision.message);
-    await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: decision.receiverId, text: safeMessage });
+    try {
+        await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: decision.receiverId, text: safeMessage });
+    }
+    catch (err) {
+        if (!isReplySlotTaken(err))
+            throw err;
+        runtimeLog.warn('runTurn', `reply already persisted for this wake (idempotency 409) — a replay or second host answered first; dropping duplicate to ${decision.receiverId}`);
+        return [{ type: 'message_duplicate_skipped', receiverId: decision.receiverId, chatId: targetSessionId, senderId: 'system' }];
+    }
     const events = [{ type: 'message_sent', receiverId: decision.receiverId, chatId: targetSessionId, message: safeMessage, senderId: 'system' }];
     if (targetSessionId !== sessionId)
         events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
@@ -683,6 +723,11 @@ async function executeSendMessages(decision, eff, sessionId) {
             await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: msg.receiverId, text: safeMessage });
         }
         catch (err) {
+            if (isReplySlotTaken(err)) {
+                runtimeLog.warn('runTurn', `reply already persisted for this wake (idempotency 409) — dropping duplicate to ${msg.receiverId}`);
+                events.push({ type: 'message_duplicate_skipped', receiverId: msg.receiverId, chatId: targetSessionId, senderId: 'system' });
+                continue;
+            }
             // Scenario: backend rejected or transport dropped this one send. Record
             // it and keep going — remaining recipients must still get their message.
             failures.push({ receiverId: msg.receiverId, error: err.message });

package/dist/runtime/taskIntake.d.ts

@@ -0,0 +1,18 @@
+import type { ThinkingState, Workflow } from '../types.js';
+/** Reserved state name for the injected assigned-task-intake default. */
+export declare const TASK_INTAKE_STATE = "workingAssignedTask";
+export declare function buildTaskIntakeState(initial: string): ThinkingState;
+/**
+ * Assigned-task-intake default — the task-side twin of the agreement-kickoff
+ * default (kickoff.ts). For every state whose transitions do not already match
+ * a task-assigned outcome, append a transition to the injected
+ * `workingAssignedTask` state. Appended LAST so any user transition on the
+ * same outcome always wins (first match wins in
+ * AgentMachine._evaluateTransitions). Returns a NEW workflow — input states
+ * are not mutated.
+ *
+ * Why: a standing hire receives task #2, #3, … months after approval. Without
+ * this default a parked state with no task-assigned route (e.g. a hire parked
+ * in `engaged`) swallowed the wake and the task sat active forever.
+ */
+export declare function injectTaskIntakeDefault(workflow: Workflow): Workflow;

package/dist/runtime/taskIntake.js

@@ -0,0 +1,113 @@
+import { thinkingDefaults } from './defaults.js';
+import { KICKOFF_STATE } from './kickoff.js';
+import { PROBE_CTX } from './validateWorkflow.js';
+/** Reserved state name for the injected assigned-task-intake default. */
+export const TASK_INTAKE_STATE = 'workingAssignedTask';
+// Synthetic outcome used to ask "does this state already route an assigned
+// task?" — same probe pattern as kickoff.ts / validateWorkflow.
+const PROBE_TASK_ASSIGNED = {
+    kind: 'task-assigned',
+    task: { taskId: '__task_intake_probe__' },
+};
+const TASK_INTAKE_TRANSITION = {
+    to: TASK_INTAKE_STATE,
+    when: o => o.kind === 'task-assigned',
+};
+// A state "handles" task-assigned if some transition would fire for it. An
+// unconditional (when-less) transition counts — it catches every outcome, so
+// the intake transition appended LAST would be unreachable there anyway.
+function stateHandlesTaskAssigned(state) {
+    return state.transitions.some(t => {
+        if (!t.when)
+            return true;
+        try {
+            return !!t.when(PROBE_TASK_ASSIGNED, PROBE_CTX);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+export function buildTaskIntakeState(initial) {
+    const dflt = thinkingDefaults({ initial });
+    return {
+        kind: 'thinking',
+        prompt: {
+            role: 'A task was just assigned to you under one of your active agreements, and your workflow has no explicit route for it. This injected default exists so an assigned task is NEVER silently dropped — under a standing hire, new tasks keep arriving for the lifetime of the agreement.',
+            goal: 'Resolve the assigned task this turn: deliver the result if you can produce it, otherwise fail it with a reason.',
+            constraints: 'The task is in <event> (and as activeTaskId / activeAgreementId in <machine_context>). If the deliverable can be produced in this turn (an answer, summary, plan, draft — most representation work), call task_set_result with status "completed" and the deliverable as result — the result is what the counterparty consumes, so make it the actual deliverable, not a status note. If the task genuinely needs abilities or tools you do not have, call task_set_result with status "failed" and a one-line reason — a visible failure the counterparty can re-route beats a silent drop. Never leave the task dangling or answer with a chat message alone.',
+        },
+        actions: {
+            ...dflt.actions,
+            completeTask: {
+                prompt: {
+                    when: 'You can produce the deliverable for the assigned task in this turn.',
+                    instruction: 'Complete the assigned task, with the deliverable itself as the result.',
+                    format: '{"taskId": "<assigned task id from <event>>", "status": "completed", "result": "<the full deliverable>"}',
+                },
+                tool: 'task_set_result',
+                // Function form so a failed task_set_result surfaces as an error outcome
+                // (→ dflt error transition) instead of a phantom task-closed.
+                produces: (result) => {
+                    const r = result;
+                    const status = r?.task?.state ?? r?.state ?? r?.status;
+                    return status === 'completed' || status === 'failed' ? 'task-closed' : 'error';
+                },
+                terminatesLoop: true,
+            },
+            failTask: {
+                prompt: {
+                    when: 'The task needs abilities, tools, or information you cannot obtain this turn.',
+                    instruction: 'Fail the assigned task with a one-line reason so the counterparty can re-route it.',
+                    format: '{"taskId": "<assigned task id from <event>>", "status": "failed", "result": "<one-line reason>"}',
+                },
+                tool: 'task_set_result',
+                produces: (result) => {
+                    const r = result;
+                    const status = r?.task?.state ?? r?.state ?? r?.status;
+                    return status === 'completed' || status === 'failed' ? 'task-closed' : 'error';
+                },
+                terminatesLoop: true,
+            },
+        },
+        transitions: [
+            { to: initial, when: o => o.kind === 'task-closed' },
+            ...dflt.transitions, // wait / message-sent / error → initial
+        ],
+    };
+}
+/**
+ * Assigned-task-intake default — the task-side twin of the agreement-kickoff
+ * default (kickoff.ts). For every state whose transitions do not already match
+ * a task-assigned outcome, append a transition to the injected
+ * `workingAssignedTask` state. Appended LAST so any user transition on the
+ * same outcome always wins (first match wins in
+ * AgentMachine._evaluateTransitions). Returns a NEW workflow — input states
+ * are not mutated.
+ *
+ * Why: a standing hire receives task #2, #3, … months after approval. Without
+ * this default a parked state with no task-assigned route (e.g. a hire parked
+ * in `engaged`) swallowed the wake and the task sat active forever.
+ */
+export function injectTaskIntakeDefault(workflow) {
+    if (workflow.states[TASK_INTAKE_STATE]) {
+        throw new Error(`[defineAgent] state name "${TASK_INTAKE_STATE}" is reserved for the injected assigned-task-intake default — rename the state`);
+    }
+    const states = {};
+    let injected = false;
+    for (const [name, state] of Object.entries(workflow.states)) {
+        // Injected defaults never feed each other: the kickoff state's own lack of
+        // a task-assigned route must not force the intake state into a workflow
+        // whose author states all handle assignment.
+        if (name === KICKOFF_STATE || stateHandlesTaskAssigned(state)) {
+            states[name] = state;
+            continue;
+        }
+        states[name] = { ...state, transitions: [...state.transitions, TASK_INTAKE_TRANSITION] };
+        injected = true;
+    }
+    if (!injected)
+        return workflow; // every state routes task-assigned — nothing to add
+    states[TASK_INTAKE_STATE] = buildTaskIntakeState(workflow.initial);
+    return { ...workflow, states };
+}

package/dist/server/ConnectionPool.d.ts

@@ -11,7 +11,7 @@
  * This is how a single Node process serves a fleet of agents without
  * holding 1000 open sockets — typical config: 1000+ registered, ~50 live.
  */
-import { type InboxOperatorAgentEntry } from '@ziggs-ai/api-client';
+import { type InboxOperatorAgentEntry, type StartAgentOptions } from '@ziggs-ai/api-client';
 import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
 interface ConnectionManagerMeta {
     domain?: string;
@@ -50,7 +50,14 @@ export declare class ConnectionPool {
      * `AgentHost` constructed + connected) the first time it's referenced.
      */
     register(configs: AgentHostOptions[], metaArr?: ConnectionManagerMeta[]): void;
-    startAgent(agentId: string): Promise<AgentHost>;
+    /**
+     * Start (or return) an agent's host. `pinned` keeps it up for the process's
+     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
+     * named rather than ones work happened to reach.
+     */
+    startAgent(agentId: string, opts?: StartAgentOptions): Promise<AgentHost>;
+    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
+    listPinned(): string[];
     sleep(agentId: string): Promise<void>;
     disconnectAll(): Promise<void>;
     /**

package/dist/server/ConnectionPool.js

@@ -46,7 +46,14 @@ export class ConnectionPool {
                 const pool = this;
                 const host = new AgentHost({
                     ...cfg,
+                    // Inbox activity and in-flight effects both reset the idle timer:
+                    // previously only pool.sendTo() touched it, so a host woken by its
+                    // own inbox loop was torn down every idleTimeoutMs (default 60s)
+                    // regardless of the work it was doing — losing lane ctx, Claude
+                    // session ids, and armed timers each time.
+                    onActivity: () => pool.manager.touch(agentId),
                     effectTap(effect, response) {
+                        pool.manager.touch(agentId);
                         if (effect.kind === 'send-message') {
                             const listeners = pool.responseListeners.get(agentId);
                             if (listeners?.length)
@@ -64,8 +71,17 @@ export class ConnectionPool {
             }, metaByAgentId.get(agentId));
         }
     }
-    async startAgent(agentId) {
-        return await this.manager.startAgent(agentId);
+    /**
+     * Start (or return) an agent's host. `pinned` keeps it up for the process's
+     * lifetime — no idle sweep, last to be evicted; use it for hosts the operator
+     * named rather than ones work happened to reach.
+     */
+    async startAgent(agentId, opts = {}) {
+        return await this.manager.startAgent(agentId, opts);
+    }
+    /** Agents kept up explicitly (launcher `preStart`), not by demand. */
+    listPinned() {
+        return this.manager.listPinned();
     }
     async sleep(agentId) {
         return this.manager.sleep(agentId);

package/dist/server/ZiggsEffectHandler.d.ts

@@ -59,7 +59,7 @@ export interface ZiggsEffectDeps {
  * side effects — that is the whole point of funneling both paths here.
  *
  * `eff` is threaded into the tool context so eff-backed tools
- * (`ziggs_context_snapshot`, `ziggs_send_message`) resolve through this same path
+ * (`context_snapshot`, `chat_send`) resolve through this same path
  * regardless of which cognition invoked them.
  */
 export declare function executeToolWithSideEffects(deps: Pick<ZiggsEffectDeps, 'toolManager' | 'artifactsClient' | 'telemetryClient' | 'telemetryIngest' | 'operatorKey' | 'agentId' | 'taskService' | 'agreementService' | 'contextReadClient' | 'messageSender'>, eff: EffectHandler, effect: Extract<Effect, {

package/dist/server/ZiggsEffectHandler.js

@@ -98,7 +98,7 @@ async function emitToolOperationArtifact(client, chatId, phase, payload, idempot
  * side effects — that is the whole point of funneling both paths here.
  *
  * `eff` is threaded into the tool context so eff-backed tools
- * (`ziggs_context_snapshot`, `ziggs_send_message`) resolve through this same path
+ * (`context_snapshot`, `chat_send`) resolve through this same path
  * regardless of which cognition invoked them.
  */
 export async function executeToolWithSideEffects(deps, eff, effect, roster) {
@@ -214,7 +214,7 @@ export function createZiggsEffectHandler(deps) {
                 // Grant-fenced aggregate read: the backend composes the ContextSnapshot
                 // (GET /context/snapshot) through the same access + temporal fence as
                 // the per-type reads. Every producer — ClaudeSdkAgent.tick, runTurn,
-                // and the on-demand ziggs_context_snapshot tool — routes through here.
+                // and the on-demand context_snapshot tool — routes through here.
                 const snap = await buildSnapshot(deps, effect.sessionId, deps.agentId, {
                     limit: effect.opts?.maxMessages,
                 });

package/dist/server/agreements/AgreementService.d.ts

@@ -19,6 +19,19 @@ export declare class AgreementService {
     publishOffer(payload: PublishOfferPayload): Promise<Agreement>;
     delegate(payload: DelegateAgreementData): Promise<Agreement>;
     respond(agreementId: string, action: 'approve' | 'reject'): Promise<Agreement>;
+    /**
+     * ZIG-1021 — claim any open broadcast (quest, standing offer, link invite).
+     * Routing (offer vs agreement claim endpoint) is decided in the shared flow.
+     */
+    claim(agreementId: string): Promise<{
+        agreement: Agreement;
+        kind: 'link' | 'offer' | 'quest';
+    }>;
+    /**
+     * ZIG-1022 — a link proposal is an agreement (engagementKind 'link') to one
+     * agent; the target owner approves. Folds the old request_link tool.
+     */
+    requestLink(providerId: string, description?: string): Promise<Agreement>;
     counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement>;
     getStatus(agreementId: string): Promise<unknown | null>;
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;

package/dist/server/agreements/AgreementService.js

@@ -1,4 +1,4 @@
-import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createAgreement, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
+import { proposeAgreement, proposeBroadcast as proposeBroadcastApi, delegateAgreement, respondToAgreement, counterAgreement, claimOpenAgreement, getAgreementStatus, listAgreements, getMyAgreements, getAgreement, publishOffer as publishOfferApi, createAgreement, revokeAgreement, fulfillAgreement, linkAgreementToChat, getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement, linkUserToAgreement, getUsersForAgreement, } from '@ziggs-ai/api-client';
 export class AgreementService {
     creds;
     constructor(operatorKey, agentId) {
@@ -37,6 +37,21 @@ export class AgreementService {
     respond(agreementId, action) {
         return respondToAgreement(agreementId, action, this.creds);
     }
+    /**
+     * ZIG-1021 — claim any open broadcast (quest, standing offer, link invite).
+     * Routing (offer vs agreement claim endpoint) is decided in the shared flow.
+     */
+    claim(agreementId) {
+        return claimOpenAgreement(agreementId, this.creds);
+    }
+    /**
+     * ZIG-1022 — a link proposal is an agreement (engagementKind 'link') to one
+     * agent; the target owner approves. Folds the old request_link tool.
+     */
+    async requestLink(providerId, description) {
+        const { agreement } = await createAgreement({ engagementKind: 'link', providerId, ...(description ? { description } : {}) }, this.creds);
+        return agreement;
+    }
     counter(agreementId, counter) {
         return counterAgreement(agreementId, counter || {}, this.creds);
     }

package/dist/server/inboxLoop.d.ts

@@ -1,13 +1,17 @@
-import { type Creds } from '@ziggs-ai/api-client';
+import { type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
 import { SeenMessages } from './SeenMessages.js';
 /**
  * Per-agent inbox long-poll loop (delivery law, phase 4). This is the ONLY way
- * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of the delta
- * → deliver into the host's lane/tick machinery → `POST /inbox/ack`. No socket,
- * no push, no separate catch-up channel — a crash-replay is just the next
- * iteration (the cursor is server-side), and writes carry idempotency keys so
- * re-processing a redelivered window is wasteful, never harmful. Act-before-ack
- * is the one ordering rule.
+ * a hosted agent consumes: `GET /inbox?wait=` → grant-fenced reads of what was
+ * addressed to it → deliver into the host's lane/tick machinery →
+ * `POST /inbox/ack`. No socket, no push, no separate catch-up channel — a
+ * crash-replay is just the next iteration (the watermark is server-side), and
+ * writes carry idempotency keys so re-processing a redelivered window is
+ * wasteful, never harmful. Act-before-ack is the one ordering rule.
+ *
+ * The envelope now names the chats directly, so this loop no longer expands
+ * scopes into chat ids itself — that cost an extra grant/agreement lookup per
+ * scope, per pass, purely to rediscover what the server already knew.
  */
 export interface InboxLoopDeps {
     creds: Creds;
@@ -16,13 +20,24 @@ export interface InboxLoopDeps {
     seen: SeenMessages;
     onMessage: (text: string, metadata: Record<string, unknown>) => Promise<void>;
     onResourceEvent: (event: Record<string, unknown>) => Promise<void>;
+    /**
+     * An open task assigned to this agent (ZIG-973). Delivered from the inbox's
+     * own task channel, so work reaches the agent even when no chat row exists
+     * for it (chat-less agreement, self-assigned task).
+     */
+    onTask?: (task: InboxTaskRef) => Promise<void>;
     label?: string;
 }
 export interface InboxPassResult {
-    scopes: number;
+    /** Delivery references this envelope carried. */
+    deliveries: number;
     messagesDelivered: number;
     resourceEvents: number;
-    acked: number;
+    /** Assigned open tasks delivered this pass (ZIG-973). */
+    tasksDelivered: number;
+    /** True when the watermark advanced this pass. */
+    acked: boolean;
+    /** True when there was more mail than one envelope carries. */
     truncated: boolean;
 }
 /**
@@ -42,8 +57,13 @@ export interface InboxLoopHandle {
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls
  * for `waitSeconds`; a passing envelope returns instantly, an empty one holds.
  * Errors retry with exponential backoff + jitter and never exit the loop —
- * there is nothing to resynchronize (the cursor is server-side), so recovery is
- * just the next iteration.
+ * there is nothing to resynchronize (the watermark is server-side), so recovery
+ * is just the next iteration.
+ *
+ * The FIRST pass is an immediate read. A held poll only answers to new mail, so
+ * a host that just started (or restarted after a crash) would otherwise sit
+ * waiting while the work it was already assigned — open tasks, pending
+ * decisions — went unseen until something unrelated arrived.
  */
 export declare function runInboxLoop(deps: InboxLoopDeps, opts?: {
     waitSeconds?: number;