@ziggs-ai/agent-sdk 0.25.0 → 0.27.0

package/dist/Agent.js

@@ -331,7 +331,7 @@ export class Agent {
             operatorKey: this.options.operatorKey,
             agentId: this.options.agentId,
         };
-        const messageSender = async (message, receiverId, sessionId, messageId, conversationAgreementId) => {
+        const messageSender = async (message, receiverId, sessionId, messageId, conversationAgreementId, underAgreementId, taskId) => {
             const sentId = messageId ?? `sdk_${randomUUID()}`;
             const result = await sendChatMessage({
                 chatId: sessionId,
@@ -345,6 +345,8 @@ export class Agent {
                 // only when absent (matches the old WS path letting the server assign).
                 messageId: sentId,
                 conversationAgreementId,
+                underAgreementId,
+                taskId,
             }, creds);
             if (!result.success)
                 throw new Error('sendChatMessage: the server did not accept this message — nothing was delivered and nobody was woken. Retry with the same messageId, which the backend dedups on.');
@@ -1121,9 +1123,9 @@ export class Agent {
             const sameRoom = 'sessionId' in effect && effect.sessionId === session.sessionId;
             const scopedEffect = sameRoom && effect.kind === 'read-context'
                 ? { ...effect, opts: { ...effect.opts, workScopes: contextScopesFromWake(frame, session.sessionId) } }
-                : sameRoom && agreementId && effect.kind === 'send-message'
-                    ? { ...effect, conversationAgreementId: effect.conversationAgreementId ?? agreementId }
-                    : sameRoom && agreementId && (effect.kind === 'tool-call' || effect.kind === 'record-event')
+                : agreementId && effect.kind === 'send-message'
+                    ? { ...effect, underAgreementId: effect.underAgreementId ?? agreementId }
+                    : agreementId && (effect.kind === 'tool-call' || effect.kind === 'record-event')
                         ? { ...effect, serviceAgreementId: effect.serviceAgreementId ?? agreementId }
                         : effect;
             const operation = this.eff(scopedEffect);

package/dist/brain/claudeSdkProtocol.js

@@ -34,7 +34,7 @@ Your prose and final summary are private host notes, not messages to the people
 You are headless — there is no human to prompt during a wake:
 - When proposals or connection requests need a human decision, DO NOT approve or reject on their behalf. Summarize what needs the operator's attention and stop.
 - When you ask somebody and stop, SAY SO ON THE TASK: \`task_update_plan_step\` with \`waitingOn\` ({ kind, id }), with the step you are ticking or on its own when the ask is all that happened. Until you do, your person sees a task that is running, and a job waiting on them is indistinguishable from one that has stalled. It clears itself when you next post progress without it, so you never have to remember to take it back.
-- When the work needs something only the person who hired you can answer (a business detail, a decision, an access you were not given), ASK THEM: if you already have a conversation, \`chat_send\` with \`to\` set to their user id from \`context_snapshot\`'s \`users\`; first contact still needs \`chat_open\` then \`chat_send\` in the chat it returns — omit receiverId there, that chat has exactly one other member. Say what you need and why, then stop; their reply wakes you. Going quiet instead leaves the job parked with nobody asked. An id starting \`psn_\` is a masked face, not an address: that person belongs to the counterparty, and you reach them by messaging THEIR agent.
+- When the work needs something only the person who hired you can answer (a business detail, a decision, an access you were not given), ASK THEM: if you already have a conversation, \`chat_send\` with \`to\` set to their user id from \`context_snapshot\`'s \`users\`; first contact still needs \`chat_open\` then \`chat_send\` in the chat it returns — name that person as receiverId there; room membership never selects a recipient. Say what you need and why, then stop; their reply wakes you. Going quiet instead leaves the job parked with nobody asked. An id starting \`psn_\` is a masked face, not an address: that person belongs to the counterparty, and you reach them by messaging THEIR agent.
 - When the work needs an answer from somebody you have no way to reach — a teammate of theirs, a partner, a customer, anyone \`chat_open\` refuses you — ASK THE PERSON YOU WORK FOR TO PUT YOU IN A ROOM WITH THEM. Say it plainly in your conversation with them: "I need to ask Dana about the Q3 number — can you open a room with her and add me?" Then stop; you are woken when you are in the room. Name the person, say what you need from them and why, and ask for one room about that one thing. Do NOT go looking for another way in: claiming a listing, proposing a link or sending an invite are for strangers you are doing business with, and they are the wrong move for somebody your person already knows — they cost that person a negotiation for something a click would have done. You inherit nobody's contacts, and asking is not a failure; it is the only door, and it takes them two clicks.
 
 Security:

package/dist/brain/claudeSdkTools.js

@@ -1,4 +1,4 @@
-import { isAgreementId, agreementLaneId, isRoomPresentationRef as isRoomParticipantRef } from '@ziggs-ai/api-client';
+import { isAgreementId, agreementLaneId } from '@ziggs-ai/api-client';
 import { randomUUID } from 'node:crypto';
 import { credsFromToolContext } from '../tools/toolCreds.js';
 import { sendChatMessage, presentSendResult } from '@ziggs-ai/api-client';
@@ -70,11 +70,11 @@ export const contextSnapshotTool = defineTool('context_snapshot', {
 }, { description: 'Read the current wake’s exact task or agreement, governing constraints, dependencies and artifact inventory. No chat is required for task work. For chat wakes, the NEWEST maxMessages of history (chronological order), agreements, participants, and a bounded inventory of readable room artifacts. Artifact bodies are not included: read relevant notes with context_read type=artifacts via=chat:<chatId>, following pagination, before concluding information is missing. Zero direct artifact grants does not mean no readable room notes. Direct grants absent from that room inventory are grantedArtifacts (id and name only); read a body with context_read type=artifacts via=artifact:<id>.' });
 export const chatSendTool = defineTool('chat_send', {
     taskId: { type: 'string', description: 'Work task; the backend resolves its governing agreement.' },
-    replyToMessageId: { type: 'string', description: 'Exact message being answered, preserving its work agreement.' },
-    conversationAgreementId: { type: 'string', description: 'Agreement authorizing this message. Same-room replies inherit the wake agreement; name it explicitly when sending in a different room or choosing between agreements.' },
+    conversationAgreementId: { type: 'string', description: 'Explicit service work requested from the recipient, separate from your own run authority.' },
+    underAgreementId: { type: 'string', description: 'Your run authority, defaulting to the current run in every destination room.' },
     chatId: { type: 'string', description: 'Omit this to send in the chat you were woken in — that is the usual case. Only pass a chatId to send in a DIFFERENT chat, such as one you just opened with chat_open. When chatId is set it wins over `to`.' },
     to: { type: 'string', description: 'User or agent id of someone you already have a conversation with. Sends in that pair room. Does not open contact — first contact still needs chat_open. Ignored when chatId is set (chatId wins; `to` is used as receiverId if receiverId is omitted).' },
-    receiverId: { type: 'string', description: 'Recipient user or agent id, or participant reference read from the destination room. Omit when replying in the room that woke you — the last other writer is inferred. When asking a named person in another room, name them. An omitted recipient in a multi-participant room is refused, not a broadcast. Pass human only for an intentional broadcast to the people in the room. A newly opened one-counterparty room can infer its recipient.' },
+    receiverId: { type: 'string', description: 'Explicit recipient user or agent id, or a participant reference from this destination room. Omit it when the room has one other participant: they are the recipient. With several, Jev chooses when confident; otherwise this is room context with no specific wake. The wake sender and last writer are never defaults. Pass human for an intentional broadcast to people.' },
     text: { type: 'string', required: true },
     idempotencyKey: { type: 'string', description: 'Reuse for retry-safe resend of the same logical message.' },
 }, async (args, ctx) => {
@@ -95,8 +95,8 @@ export const chatSendTool = defineTool('chat_send', {
             text,
             messageId,
             conversationAgreementId: firstFilled(args.conversationAgreementId),
+            underAgreementId: firstFilled(args.underAgreementId, c.serviceAgreementId),
             taskId: firstFilled(args.taskId),
-            replyToMessageId: firstFilled(args.replyToMessageId),
             ...(namedReceiver ? { receiverId: namedReceiver } : {}),
         }, creds);
         // Never presented as a send that happened: the message does not exist,
@@ -112,48 +112,11 @@ export const chatSendTool = defineTool('chat_send', {
         throw new Error('chat_send requires eff in tool context');
     // Same agreement-id-where-a-chat-id-goes slip as context_snapshot, and the
     // same mapping: an agreement's traffic lane is `agrn-<agreementId>`.
-    const wakeChatId = asChatLane(firstFilled(c.chatId, c.sessionId));
     const sessionId = asChatLane(firstFilled(args.chatId, c.chatId, c.sessionId));
     if (!sessionId) {
         throw new Error('chat_send: this wake carries no chat to send in. Pass chatId of the room, or to naming a person you already have a conversation with (first contact still needs chat_open).');
     }
-    // Replying to whoever woke you is the overwhelmingly common case; making
-    // the model spell it out cost a failed tool call + a full extra LLM turn
-    // per reply.
-    //
-    // But ONLY in the room that wake belongs to. The sender an
-    // event carries is usually an `rpb_*` room participant reference, which is
-    // an address inside its own room and a dead id in any other. Defaulting it
-    // into a different chat is how an agent that opened a chat with its own
-    // human — `chat_open` accepted the principal and minted the room — had the
-    // very next `chat_send` refused with INVALID_ROOM_PARTICIPANT_REF, and gave
-    // up on reaching the person who hired it. An explicitly passed foreign-room
-    // ref is dropped only when it is the wake sender carried across rooms.
-    // A DIFFERENT explicit ref can come from the destination's snapshot and
-    // must reach the server, which validates it in that destination room.
-    const sameRoom = sessionId === wakeChatId;
-    const explicit = firstFilled(args.receiverId, args.to);
-    const receiverId = explicit && !(isRoomParticipantRef(explicit) && !sameRoom && explicit === c.senderId)
-        ? explicit
-        : sameRoom
-            ? firstFilled(c.senderId)
-            : undefined;
-    if (!sameRoom && !receiverId) {
-        // A room that also holds the person's old delegate is no longer 1:1.
-        // An omitted recipient there is refused, not a broadcast; name the
-        // person or agent, or pass human for a room broadcast.
-        const snapshot = await c.eff({
-            kind: 'read-context', sessionId, opts: { maxMessages: 1 },
-        });
-        const participantCount = (snapshot?.users?.length ?? 0) + (snapshot?.agents?.length ?? 0);
-        if (participantCount > 2) {
-            throw new Error('chat_send: this destination has several participants. Set receiverId to the person or agent you are asking, using their account id or a participant reference from context_snapshot of this destination. Omit no recipient when expecting a reply. For an intentional human broadcast, explicitly set receiverId="human". No message was sent.');
-        }
-    }
-    // No receiver is a legitimate send, not a failure: the backend resolves the
-    // recipient from the room's own participants and answers with a 1:1 chat's
-    // only other member. That is exactly the case a freshly opened chat is in,
-    // and it is the one case the wake's sender cannot answer.
+    const receiverId = firstFilled(args.receiverId, args.to);
     // Default to the wake's content-derived key: a crash-replay that
     // re-sends the same text re-derives the same messageId and the backend drops
     // the duplicate; a re-think with different text gets a new key
@@ -166,8 +129,8 @@ export const chatSendTool = defineTool('chat_send', {
     return c.eff({
         kind: 'send-message',
         ...(firstFilled(args.taskId) ? { taskId: firstFilled(args.taskId) } : {}),
-        ...(firstFilled(args.replyToMessageId) ? { replyToMessageId: firstFilled(args.replyToMessageId) } : {}),
-        ...(firstFilled(args.conversationAgreementId, sameRoom ? c.serviceAgreementId : undefined) ? { conversationAgreementId: firstFilled(args.conversationAgreementId, sameRoom ? c.serviceAgreementId : undefined) } : {}),
+        ...(firstFilled(args.conversationAgreementId) ? { conversationAgreementId: firstFilled(args.conversationAgreementId) } : {}),
+        ...(firstFilled(args.underAgreementId, c.serviceAgreementId) ? { underAgreementId: firstFilled(args.underAgreementId, c.serviceAgreementId) } : {}),
         sessionId,
         ...(receiverId ? { receiverId } : {}),
         text,

package/dist/index.d.ts

@@ -67,7 +67,7 @@ export { HistoryFormatter, historyFormatter, AgreementFormatter, agreementFormat
 export { ProactiveTrigger } from './platform/proactive/ProactiveTrigger.js';
 export { PollRegistry, declaredPolls, type PollBinding, type PollContext, type PollKind, type PollResult, } from './platform/polls/PollKind.js';
 export { PollRunner, type PollRunnerOptions, type WakeTarget } from './platform/polls/PollRunner.js';
-export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
+export { PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';
 export { hostedModelTools, isHostedCatalogOnly, hostedToolLane } from './brain/hostedToolSurface.js';
 export type { HostedToolExecute } from './brain/hostedToolSurface.js';

package/dist/index.js

@@ -79,7 +79,7 @@ export {
 // Tier 1 — protocol grammar (framework-managed via taskTools).
 PROTOCOL_TOOLS, agreementProposeTool, agreementSubcontractTool, agreementRespondTool, agreementClaimTool, agreementCounterTool, agreementGetTool, agreementRevokeTool, agreementFulfillTool, taskCreateTool, taskSetResultTool, taskUpdatePlanStepTool, dispatchProtocolOp, 
 // Tier 2 — opt-in capability bundles (spread into `tools:`).
-PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
+PAYMENT_TOOLS, paymentBalanceTool, CONNECTION_TOOLS, connectionProxyTool, connectionListGrantsTool, requestConnectionTool, MCP_CONNECTION_TOOLS, mcpToolCallTool, mcpToolsListTool, DISCOVERY_TOOLS, agentSearchTool, agentGetTool, MARKETPLACE_TOOLS, marketplaceViewTool, CONTEXT_TOOLS, contextReadTool, contextRequestTool, accessRequestTool, contextDelegateTool, contextExpandReachTool, contextDiscoverGrantableTool, GRANTS_TOOLS, listGrantsTool, PLAN_TOOLS, taskReplacePlanTool, LINK_TOOLS, linkProposeTool, linkListTool, INTRODUCTION_TOOLS, introductionMintTool, introductionRedeemTool, introductionListTool, introductionRevokeTool, ARTIFACT_TOOLS, recordArtifactTool, CHAT_TOOLS, openConversationTool, } from './platform/tools/index.js';
 // The always-on toolset for the hosted Claude cognition (parity guard
 // reads this as part of the real SDK registry).
 export { CLAUDE_SDK_TOOLS } from './brain/claudeSdkTools.js';

package/dist/ingress/normalizeIncoming.d.ts

@@ -5,6 +5,7 @@ export interface NormalizedEvent {
         senderId?: string;
         senderType?: string;
         receiverId?: string;
+        assigneeId?: string;
         /**
          * Backend per-delivery id of the chat row this event came from. The one
          * field of the event that is identical on live push and on catch-up
@@ -58,6 +59,7 @@ interface WireMetadata {
     };
     /** Inbox rewrite: assigned mail is this agent's even when the chat row names a human. */
     receiverId?: string;
+    assigneeId?: string;
     task?: WireTask;
     service?: {
         conversationAgreementId?: string;

package/dist/ingress/normalizeIncoming.js

@@ -113,6 +113,7 @@ export function normalizeIncomingEvent({ text, metadata = {} }) {
         senderId: metadata.sender?.id,
         senderType,
         receiverId: receiverId || undefined,
+        assigneeId: typeof metadata.assigneeId === 'string' ? metadata.assigneeId : undefined,
         messageId: typeof metadata.messageId === 'string' && metadata.messageId ? metadata.messageId : undefined,
         timestamp: Date.now(),
         ...(entryType ? { entryType } : {}),

package/dist/platform/ZiggsEffectHandler.d.ts

@@ -36,7 +36,7 @@ export interface ZiggsEffectDeps {
     contextReadClient: ContextReadClient;
     taskService: TaskService;
     agreementService: AgreementService;
-    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string) => Promise<unknown>;
+    messageSender: (text: string, receiverId: string | undefined, sessionId: string, messageId?: string, conversationAgreementId?: string, underAgreementId?: string, taskId?: string) => Promise<unknown>;
     /** Sends a streaming chunk to a client. Called per-token during stream-text effects. */
     chunkSender?: (sessionId: string, receiverId: string, text: string, messageId: string) => void;
     toolManager: ToolManager;

package/dist/platform/ZiggsEffectHandler.js

@@ -313,7 +313,7 @@ export function createZiggsEffectHandler(deps) {
                 });
             }
             case 'send-message': {
-                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId);
+                const sent = await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId, effect.conversationAgreementId, effect.underAgreementId, effect.taskId);
                 outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
                 // Carry the send's own report back to whoever asked for the send. A
                 // sender that cannot see where its message went cannot tell a delivered

package/dist/platform/inboxLoop.d.ts

@@ -1,4 +1,4 @@
-import { type InboxChatNews, type InboxDeliveryRef, type InboxRequestRef, type InboxTaskRef, type Creds } from '@ziggs-ai/api-client';
+import { type InboxChatNews, type InboxRequestRef, 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
@@ -60,19 +60,13 @@ export interface InboxPassResult {
  * the wake — it does not buy a canned answer.
  */
 export declare function chatsInWakeOrder(chats: InboxChatNews[]): InboxChatNews[];
-/**
- * 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 declare function soleHireAgreementIdForChat(deliveries: readonly Pick<InboxDeliveryRef, 'chatId' | 'agreementId' | 'assigneeId'>[], chatId: string, ownAgentId: string): string | null;
 /**
  * One long-poll pass: hold up to `waitSeconds` for new inbox content, then read
  * the deltas, deliver them into the host, and ack. Returns what it delivered.
  * Reused each iteration of {@link runInboxLoop}; also usable as a single catch-up
  * read (`waitSeconds: 0`) at bootstrap.
  */
-export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, opts?: {
+export declare function pollInboxOnce(deps: InboxLoopDeps, waitSeconds?: number, _opts?: {
     forceAck?: boolean;
 }): Promise<InboxPassResult>;
 export interface InboxLoopHandle {
@@ -94,11 +88,7 @@ export interface InboxLoopHandle {
      */
     readonly lastAttemptAt: number | null;
 }
-/**
- * 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 declare function heldPassAfter(prev: number, pass: Pick<InboxPassResult, 'acked' | 'failures' | 'truncated'>): number;
 /**
  * Run {@link pollInboxOnce} forever (until stopped). Each iteration long-polls

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.25.0",
+  "version": "0.27.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.24.0",
+    "@ziggs-ai/api-client": "0.26.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",