@ziggs-ai/agent-sdk 0.24.1 → 0.26.0

package/dist/platform/inboxLoop.js

@@ -49,90 +49,79 @@ function proposalIsMine(proposal, ownAgentId) {
     return (proposal.pendingApprovalPartyIds?.includes(ownAgentId) === true ||
         proposal.proposedTo === ownAgentId);
 }
-/**
- * The one hire a chat's assigned deliveries name, or null when the room
- * has none or more than one. Memory (and acting-for) treat "several
- * customers in one room" as the shared section.
- */
-export function soleHireAgreementIdForChat(deliveries, chatId, ownAgentId) {
-    const ids = new Set();
-    for (const d of deliveries) {
-        if (d.chatId !== chatId || !d.agreementId)
-            continue;
-        if (d.assigneeId && d.assigneeId !== ownAgentId)
-            continue;
-        ids.add(d.agreementId);
-    }
-    return ids.size === 1 ? [...ids][0] : null;
-}
 /**
  * Read the messages behind one chat's deliveries and hand them to the host.
  *
- * The envelope says which chat and how many, not the bodies — so this still
+ * The envelope names exact assigned message ids, not their bodies — so this still
  * reads through `/context/read`, where the agent's own grants fence what it is
  * allowed to see. A delivery reference is an address, never an authorisation.
  */
-async function deliverMessagesForChat(deps, news, earliestTs, reader, attempt, hireAgreementId) {
+async function deliverMessagesForChat(deps, news, refs, reader, attempt, handledIds) {
+    const pending = new Map(refs.map(ref => [ref.resourceId, ref]));
+    for (const id of pending.keys()) {
+        if (deps.seen.has(id)) {
+            pending.delete(id);
+            handledIds.add(id);
+        }
+    }
+    if (!pending.size)
+        return 0;
     let delivered = 0;
-    let remaining = news.count;
-    // `after` is exclusive, so step back a millisecond to include the oldest
-    // delivery itself. Re-reading a neighbour that shares its timestamp is
-    // harmless — `seen` dedups by messageId.
-    let after = new Date(Date.parse(earliestTs) - 1).toISOString();
-    let pages = 0;
-    const maxPages = 20;
-    while (remaining > 0 && pages < maxPages) {
-        const limit = Math.min(READ_PAGE, remaining);
+    const earliest = refs.map(ref => ref.ts).sort()[0];
+    let after = new Date(Date.parse(earliest) - 1).toISOString();
+    let cursor;
+    for (let pages = 0; pending.size && pages < 100; pages++) {
         let page;
         try {
             page = await reader.read('messages', {
-                via: `chat:${news.chatId}`,
-                after,
-                direction: 'forward',
-                limit,
+                via: `chat:${news.chatId}`, after, direction: 'forward', limit: READ_PAGE,
+                ...(cursor ? { cursor } : {}),
             });
         }
         catch (err) {
             const status = err.status;
             if (status !== 403 && status !== 404)
                 throw err;
-            // Addressed but not readable. Since the delivery log and the grants are
-            // now separate, the two can disagree — a grant revoked between the write
-            // and this read, or a chat since deleted. Skipping keeps the pass alive
-            // so the rest of the mail is delivered and the watermark still advances;
-            // failing here would wedge the agent on one unreadable item forever,
-            // re-woken by the same delivery on every pass.
-            warn(deps.label ?? 'inboxLoop', `chat ${news.chatId}: addressed but not readable (${status}) — skipping ${remaining} delivery/deliveries`);
+            // This read explicitly establishes that these deliveries are inaccessible.
+            // The server also excludes out-of-reach rows from its acknowledgment guard.
+            for (const id of pending.keys())
+                handledIds.add(id);
             return delivered;
         }
         for (const row of page.items) {
-            const messageId = String(row.messageId ?? '');
-            if (deps.seen.has(messageId))
-                continue;
-            const text = typeof row.text === 'string' ? row.text : '';
-            if (!text.trim())
+            const id = String(row.messageId ?? '');
+            const ref = pending.get(id);
+            if (!ref)
                 continue;
-            // The host un-marks its own `seen` entry when a message fails, so there is
-            // nothing to forget here — but the failure still holds the watermark.
-            const handled = await attempt(`chat ${news.chatId} message ${messageId}`, () => deps.onMessage(text, {
+            const handled = await attempt(`chat ${news.chatId} message ${id}`, () => deps.onMessage(typeof row.text === 'string' ? row.text : '', {
                 ...row,
                 chatId: news.chatId,
-                // Assigned inbox mail is this agent's to answer. Chat `receiver`
-                // is often the human the stand-in (or any assignee) is covering;
-                // leaving it made ClaudeBrain treat the wake as notice-only.
-                receiverId: deps.ownAgentId,
-                receiver: { id: deps.ownAgentId },
-                ...(hireAgreementId ? { agreementId: hireAgreementId } : {}),
+                // Preserve the message's addressee. Assignment separately authorizes
+                // this carrier to handle it, including a person's stand-in.
+                assigneeId: deps.ownAgentId,
+                ...(ref.agreementId ? { agreementId: ref.agreementId } : {}),
             }));
-            if (handled)
+            if (handled) {
                 delivered++;
-            remaining--;
+                handledIds.add(id);
+            }
+            pending.delete(id);
         }
-        if (!page.hasMore || !page.latestSequence)
+        if (!page.hasMore)
+            break;
+        if (page.nextCursor && page.nextCursor !== cursor)
+            cursor = page.nextCursor;
+        else if (page.latestSequence && page.latestSequence > after) {
+            after = page.latestSequence;
+            cursor = undefined;
+        }
+        else
             break;
-        after = page.latestSequence;
-        pages++;
     }
+    if (pending.size)
+        await attempt(`chat ${news.chatId} missing assigned messages`, async () => {
+            throw new Error(`Assigned message(s) not read: ${[...pending.keys()].join(', ')}`);
+        });
     return delivered;
 }
 /**
@@ -141,7 +130,7 @@ async function deliverMessagesForChat(deps, news, earliestTs, reader, attempt, h
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
+export async function pollInboxOnce(deps, waitSeconds = 0, _opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const inbox = inboxClient(deps);
     const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
@@ -213,37 +202,21 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
             warn(label, `mid-pass ack did not land: ${err?.message ?? err}`);
         }
     };
-    // Oldest ASSIGNED delivery per chat: where to start reading that chat's
-    // messages. Ambient chat rows must not drag the read window earlier.
-    const earliestByChat = new Map();
-    const assignedRowsByChat = new Map();
+    const assignedByChat = new Map();
     for (const d of envelope.deliveries) {
-        if (!d.chatId || !mine(d))
+        if (d.kind !== 'message' || !d.chatId || !mine(d) || d.outOfReach)
             continue;
-        const seen = earliestByChat.get(d.chatId);
-        if (!seen || d.ts < seen)
-            earliestByChat.set(d.chatId, d.ts);
-        const rows = assignedRowsByChat.get(d.chatId);
-        if (rows)
-            rows.push(d.resourceId);
-        else
-            assignedRowsByChat.set(d.chatId, [d.resourceId]);
+        const rows = assignedByChat.get(d.chatId) ?? [];
+        rows.push(d);
+        assignedByChat.set(d.chatId, rows);
     }
-    for (const news of chatsInWakeOrder(envelope.chats ?? [])) {
-        const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
-        const failuresBefore = failures;
-        const n = await deliverMessagesForChat(deps, news, earliest, reader, attempt, soleHireAgreementIdForChat(envelope.deliveries, news.chatId, deps.ownAgentId));
+    const chats = [...assignedByChat].map(([chatId, refs]) => ({
+        chatId, count: refs.length, latestAt: refs.map(ref => ref.ts).sort().at(-1),
+    }));
+    for (const news of chatsInWakeOrder(chats)) {
+        const n = await deliverMessagesForChat(deps, news, assignedByChat.get(news.chatId), reader, attempt, handledSoFar);
         messagesDelivered += n;
-        if (n > 0)
-            log(label, `chat ${news.chatId} delivered ${n} message(s)`);
-        // A fold that dropped a handover has not finished its rows, and the
-        // watermark must wait for the redelivery it is holding open.
-        if (failures === failuresBefore) {
-            for (const id of assignedRowsByChat.get(news.chatId) ?? []) {
-                handledSoFar.add(id);
-            }
-            await ackWhatIsFinished();
-        }
+        await ackWhatIsFinished();
     }
     // Everything that is not chat text is handed over as a resource event, from
     // the delivery itself — the reference already carries the ids the host needs,
@@ -355,23 +328,17 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     // Act, then ack: everything above has been handed to the host, so the
     // watermark may now move past it. A crash before this point redelivers.
     //
-    // "act" now means acted, not attempted. A pass with failures holds
-    // the watermark so the server redelivers the window — unless `forceAck` says
-    // this window has failed too many times in a row and is now poison, in which
-    // case it is dropped loudly rather than wedging the agent forever.
+    // Advance only after every assigned id has an explicit disposition.
+    // Repeated failures never turn unread mail into an acknowledged delivery.
     // One function, shared with the MCP inbox tool — do not restate the list
     // or the allow-gate here.
     let acked = false;
     const ack = planInboxAck(envelope, {
         ownAgentId: deps.ownAgentId,
         failures,
-        forceAck: opts.forceAck,
+        forceAck: false,
     });
-    if (ack.allowed) {
-        if (failures > 0) {
-            runtimeLog.error(label, `acking a window that failed ${failures} handover(s) — giving up on redelivery to keep the ` +
-                `agent alive; this mail is lost (ackTo=${envelope.ackTo})`);
-        }
+    if (ack.allowed && ack.handledResourceIds.every(id => handledSoFar.has(id))) {
         await inbox.ack(envelope.ackTo, { handledResourceIds: ack.handledResourceIds });
         acked = true;
         log(label, `acked up to ${envelope.ackTo}`);
@@ -399,19 +366,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
 const DEFAULT_WAIT_SECONDS = 110;
 const ERROR_BACKOFF_BASE_MS = 1_000;
 const ERROR_BACKOFF_MAX_MS = 30_000;
-/**
- * How many passes in a row may hold the watermark before the window is treated
- * as poison and acked away. Three is enough for the failures we have
- * actually seen — a redeployed container, a wedged backend, a transient throw —
- * and short enough that a frame the host can never handle costs three wakes
- * rather than an unbounded loop.
- */
-const MAX_HELD_PASSES = 3;
-/**
- * How many consecutive passes have refused to advance the watermark.
- * A capped envelope used to reset the counter (zero handover failures),
- * so `forceAck` never fired on the one hold that lasts forever.
- */
+/** Count held windows so retries can back off without discarding mail. */
 export function heldPassAfter(prev, pass) {
     return !pass.acked && (pass.failures > 0 || pass.truncated) ? prev + 1 : 0;
 }
@@ -443,17 +398,13 @@ export function runInboxLoop(deps, opts = {}) {
         while (running) {
             try {
                 lastAttemptAt = Date.now();
-                const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds, {
-                    forceAck: heldPasses >= MAX_HELD_PASSES,
-                });
+                const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds);
                 lastPassAt = Date.now();
                 first = false;
                 consecutiveErrors = 0;
-                // A held pass means the same window comes back; count how many times we
-                // have refused it so a permanently unhandleable frame cannot spin here.
-                // Capped holds used to reset this: failures === 0, so the poison
-                // escape never climbed. Count any pass that refused to advance.
                 heldPasses = heldPassAfter(heldPasses, pass);
+                if (heldPasses)
+                    await sleep(Math.min(ERROR_BACKOFF_MAX_MS, ERROR_BACKOFF_BASE_MS * 2 ** Math.min(heldPasses - 1, 5)));
             }
             catch (err) {
                 if (!running)

package/dist/platform/tools/index.d.ts

@@ -21,7 +21,7 @@ export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discover
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
 export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';
 export { TASK_TOOLS, listTasksTool, cancelTaskTool } from './tier2/taskTools.js';
 export { PLAN_TOOLS, taskReplacePlanTool } from './tier2/planTools.js';

package/dist/platform/tools/index.js

@@ -23,7 +23,7 @@ export { DISCOVERY_TOOLS, agentSearchTool, agentGetTool } from './tier2/discover
 export { MARKETPLACE_TOOLS, marketplaceViewTool } from './tier2/marketplaceTools.js';
 export { PAYMENT_TOOLS, paymentBalanceTool } from './tier2/paymentTools.js';
 export { CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, } from './tier2/connectionTools.js';
-export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
+export { CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, } from './tier2/contextTools.js';
 // one grant lister across every rail (retires context_discover +
 // payment_list_grants). Always-available on the hosted agent — see CLAUDE_SDK_TOOLS.
 export { GRANTS_TOOLS, listGrantsTool } from './tier2/grantsTools.js';

package/dist/platform/tools/tier2/contextTools.d.ts

@@ -2,6 +2,7 @@ import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const contextReadTool: ToolDefinition;
 export declare const openTool: ToolDefinition;
 export declare const accessExplainTool: ToolDefinition;
+export declare const accessRequestTool: ToolDefinition;
 export declare const contextRequestTool: ToolDefinition;
 export declare const contextDelegateTool: ToolDefinition;
 export declare const contextExpandReachTool: ToolDefinition;

package/dist/platform/tools/tier2/contextTools.js

@@ -1,4 +1,4 @@
-import { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextRequestCapability, } from '@ziggs-ai/api-client';
+import { CONTEXT_CAPABILITIES, contextReadCapability, openCapability, accessExplainCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, contextRequestCapability, accessRequestCapability, } from '@ziggs-ai/api-client';
 import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
 // context grant tools ride the same api-client
 // clients as ziggs-mcp; the whole definition (schema + handler) is now shared
@@ -6,6 +6,7 @@ import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabi
 export const contextReadTool = toolFromCapability(contextReadCapability);
 export const openTool = toolFromCapability(openCapability);
 export const accessExplainTool = toolFromCapability(accessExplainCapability);
+export const accessRequestTool = toolFromCapability(accessRequestCapability);
 export const contextRequestTool = toolFromCapability(contextRequestCapability);
 export const contextDelegateTool = toolFromCapability(contextDelegateCapability);
 export const contextExpandReachTool = toolFromCapability(contextExpandReachCapability);

package/dist/runtime/PromptBuilder.js

@@ -382,7 +382,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         lines.push('Return ONE JSON object. ALWAYS include "thought" as the FIRST field — briefly explain your reasoning before choosing an action.');
         lines.push('Set "action" to exactly one of the action names below.');
         lines.push('Message text is rendered as markdown (CommonMark + GFM). You MAY use **bold**, *italic*, `code`, fenced code blocks, lists, links, and tables when they improve clarity — plain text is also fine.\n');
-        const replyTo = senderMeta.defaultReplyReceiverId || '<receiverId>';
+        const replyTo = '<receiverId from <recipients>>';
         const pendingProposals = (ctxObj.agreements || []).filter((a) => a.proposal?.status === 'pending' && (a.proposedToIsYou || isBroadcastTarget(a.parties?.proposedTo?.principal)));
         if (pendingProposals.length > 0) {
             lines.push(`PRIORITY: You have ${pendingProposals.length} pending proposal(s) directed at you. Respond BEFORE other actions.`);
@@ -439,23 +439,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         const senderId = String(ev?.senderId || 'system');
         const senderType = ev?.senderType ? String(ev.senderType).toUpperCase() : 'SYSTEM';
         const myId = this._getMyAgentId(ctxObj);
-        const isNonRoutableSenderType = (t) => t === 'SYSTEM' || t === 'SERVICE';
-        let defaultReplyReceiverId = senderId;
-        const isNonRoutable = isNonRoutableSenderType(senderType);
-        if (isNonRoutable) {
-            const history = ctxObj.history || [];
-            for (let i = history.length - 1; i >= 0; i--) {
-                const row = history[i];
-                const sender = row.sender;
-                const id = String(sender?.id || '');
-                const type = String(sender?.type || '').toUpperCase();
-                if (id && id !== myId && !isNonRoutableSenderType(type)) {
-                    defaultReplyReceiverId = id;
-                    break;
-                }
-            }
-        }
-        return { senderId, senderType, myAgentId: myId, defaultReplyReceiverId: defaultReplyReceiverId || senderId };
+        return { senderId, senderType, myAgentId: myId };
     }
     _getMyAgentId(ctxObj) {
         const agents = ctxObj.agents || [];

package/dist/runtime/buildOutcome.d.ts

@@ -36,6 +36,14 @@ export interface EmittedEvent {
     senderId?: string;
     [key: string]: unknown;
 }
+/**
+ * A chat message whose stated receiver is a DIFFERENT party. `receiverId` is
+ * the sender's addressing decision, carried on every wire frame; the
+ * human-broadcast sentinel counts as "elsewhere" for an agent (a broadcast is
+ * addressed to the room's humans). A frame with NO receiver keeps the turn —
+ * we cannot know it is not ours, and skipping on absence would deafen agents
+ * to malformed or legacy frames.
+ */
 export declare function isMessageAddressedElsewhere(ev: RawEvent | null | undefined, ownAgentId: string | null | undefined): boolean;
 /**
  * Converts a raw incoming event into the single Outcome that re-enters the

package/dist/runtime/buildOutcome.js

@@ -9,24 +9,11 @@ import { bookForDelegation, ensureTaskBook, findBookHoldingPending, removeTaskBo
  * we cannot know it is not ours, and skipping on absence would deafen agents
  * to malformed or legacy frames.
  */
-function isSyntheticOrgReceiver(id) {
-    if (/^([a-z0-9][a-z0-9-]*)\1@ziggs\.local$/i.test(id))
-        return true;
-    const sep = id.indexOf(':::');
-    if (sep > 0)
-        return /@ziggs\.local$/i.test(id.slice(sep + 3));
-    return false;
-}
 export function isMessageAddressedElsewhere(ev, ownAgentId) {
     if (!ev || ev.type !== 'message' || !ownAgentId || !ev.receiverId) {
         return false;
     }
-    if (ev.receiverId === ownAgentId)
-        return false;
-    // Fleet synthetic users are not a party that will answer. A hire room
-    // born with the org ghost as the other face used to address the human's
-    // message there, and the agent skipped the turn — claimed, acked, silence.
-    if (isSyntheticOrgReceiver(String(ev.receiverId)))
+    if (ev.assigneeId === ownAgentId || ev.receiverId === ownAgentId)
         return false;
     return true;
 }

package/dist/types.d.ts

@@ -515,6 +515,8 @@ export type Effect = {
     text: string;
     messageId?: string;
     conversationAgreementId?: string;
+    underAgreementId?: string;
+    taskId?: string;
 } | {
     kind: 'record-event';
     sessionId: string;

package/package.json

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