@ziggs-ai/agent-sdk 0.30.0 → 0.32.0

package/dist/Agent.js

@@ -1,5 +1,5 @@
 import { withAgreementContext } from './runtime/agreementContext.js';
-import { agreementLaneId, agreementIdFromLane } from '@ziggs-ai/api-client';
+import { agreementLaneId, agreementIdFromLane, isContextAccessRequest } from '@ziggs-ai/api-client';
 import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js';
 import { randomUUID } from 'node:crypto';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -515,6 +515,29 @@ export class Agent {
         const ownAgentId = this.options.agentId;
         if (!ownAgentId)
             return;
+        // A permission decision is a notice about a grant, not authority to run
+        // work under the (now fulfilled/cancelled) request. Resume the hire that
+        // the server recorded when it validated the request; ordinary read/write
+        // gates still recheck that hire. Ignore the duplicate lifecycle echo.
+        let resumeAgreementId;
+        const reason = typeof event.reason === 'string' ? event.reason : '';
+        if (event.kind === 'agreement' && /^(context_request_|approval:|status:cancelled)/.test(reason)) {
+            const requestId = String(event.resourceId || event.agreementId || '');
+            try {
+                const row = await this.agreementService.get(requestId);
+                const request = row?.grantRequest;
+                if (isContextAccessRequest(request) && typeof request.resumeAgreementId === 'string' && request.resumeAgreementId) {
+                    if (!reason.startsWith('context_request_'))
+                        return;
+                    resumeAgreementId = request.resumeAgreementId;
+                }
+            }
+            catch {
+                // A revoked or unavailable agreement must not pin the inbox cursor.
+                // Route the original event; normal tool authorization still applies.
+                runtimeLog.debug('Agent', 'Access-decision lookup unavailable; using original event');
+            }
+        }
         // Map the event to a candidate session key using the configured resolver
         // on a synthetic normalized-event shape. Default resolver buckets by
         // chatId; agents using a different sessionResolver (agreementId, taskId,
@@ -543,7 +566,8 @@ export class Agent {
         if (!this.sessions.has(laneKey)) {
             this.sessions.set(laneKey, { sessionId, ownAgentId });
         }
-        const agreementId = (typeof event.agreementId === 'string' && event.agreementId) ||
+        const agreementId = resumeAgreementId ||
+            (typeof event.agreementId === 'string' && event.agreementId) ||
             (event.kind === 'agreement' && typeof event.resourceId === 'string'
                 ? event.resourceId
                 : undefined);
@@ -560,6 +584,14 @@ export class Agent {
     }
     /** Wire entry. Normalize → resolve session → enqueue on the right lane. */
     async handleMessage(text, metadata = {}) {
+        // Permission decisions also arrive as a chat notification. The dedicated
+        // context_request_* resource event owns continuation; processing this echo
+        // would answer twice, once under the permission request instead of the hire.
+        const notice = metadata.service;
+        if (metadata.entryType === 'notification' &&
+            ['proposal_approved', 'proposal_rejected'].includes(notice?.operation ?? '') &&
+            isContextAccessRequest(notice?.agreement?.grantRequest))
+            return;
         const messageId = metadata.messageId;
         if (messageId && this.seenMessages.has(messageId)) {
             runtimeLog.debug('Agent', `skip duplicate messageId=${messageId}`);

package/dist/brain/claudeCognition.js

@@ -224,7 +224,8 @@ function renderEventLines(event, lines, now) {
         const decisionActor = (typeof resource.actorId === 'string' && resource.actorId) ||
             (typeof event.actorId === 'string' && event.actorId) ||
             null;
-        const decisionAgreementId = (typeof event.agreementId === 'string' && event.agreementId) ||
+        const decisionAgreementId = (resource.kind === 'agreement' && typeof resource.resourceId === 'string' && resource.resourceId) ||
+            (typeof event.agreementId === 'string' && event.agreementId) ||
             (typeof resource.agreementId === 'string' && resource.agreementId) ||
             (resource.kind === 'agreement' &&
                 typeof resource.resourceId === 'string' &&
@@ -238,11 +239,11 @@ function renderEventLines(event, lines, now) {
             surface: 'sdk',
         });
         if (reason === 'context_request_fulfilled' || reason === 'context_request_rejected') {
-            lines.push('Work signal: the owner answered your artifact access request. ' +
+            lines.push('Work signal: the owner answered your context access request. ' +
                 (decision ? `${decision.sentence} ` : '') +
-                'Read the agreement and this conversation to recover the pending work. ' +
+                'Read the permission request and this conversation to recover the pending work. The wake agreementId is the ongoing hire to act under; the resourceId identifies the permission decision. ' +
                 (reason === 'context_request_fulfilled'
-                    ? 'Open the original artifact using the approved grant, verify the read succeeds, and deliver the requested answer to its original recipient. '
+                    ? 'Read the original resource using the approved grant (context_read for a workspace), verify the read succeeds, and deliver the requested answer to its original recipient. '
                     : 'Access was rejected: report the unresolved dependency to the original requester. ') +
                 'This is an access decision, not a new hire; do not create a new task or repeat your introduction.');
         }
@@ -286,18 +287,6 @@ function renderEventLines(event, lines, now) {
                 lines.push(`Agreement: ${agreementId}`);
             }
         }
-        // The other side of the same policy: a message this agent sent to a
-        // published agent landed and was NOT rung through. Nothing is wrong and
-        // nothing is lost, so this must not read as a refusal — but without it the
-        // sender waits on a reply that is never coming and its rational next move
-        // is to send again.
-        if (reason === 'contact_policy_withheld') {
-            lines.push('Your message was delivered and is readable, but the agent you wrote ' +
-                'to is not woken for it: its listing is claim-first, so it starts ' +
-                'work once you claim the listing. Do not resend — claim the listing ' +
-                '(ziggs_marketplace_view to find it, then ziggs_agreement_claim), or ' +
-                'wait if somebody else is claiming on your behalf.');
-        }
     }
     if (event?.agreementContext) {
         lines.push(`Service agreement context (server read): ${JSON.stringify(event.agreementContext)}`);

package/dist/brain/claudeSdkProtocol.js

@@ -27,6 +27,7 @@ Your prose and final summary are private host notes, not messages to the people
 - Closing a task closes the TASK, and only the task. It stores your result where the next agent reads it, queues a wake for whoever the platform addresses, and on an agreement that bills per completed task it meters that one execution. It does not end the hire — a standing agreement stays active for the next task — it does not prove anyone has read you, and it does not prove you were paid. The reply tells you which of those actually happened: report that and nothing beyond it. A completion whose reply you never saw is recovered by READING the task back, never by completing it a second time; your retry carries the same write key, so a redelivered completion no-ops instead of doubling the result, the wake and the charge.
 - Enumerate open work with \`task_list\` (use assignedToMe for your own active tasks).
 - Chat is where you talk to whoever you are working with, and where a human reads what you delivered — sending it to them there is delivery, not duplication. It is not where another AGENT collects a deliverable: that one reads the task result, so a chat message never stands in for closing the task. Deliver into the working conversation the hire already has; do not repeat it into every room you can reach.
+- Use any room you can write in, or open one (newChat for a separate subject). The server refuses what you are not allowed to do, and the refusal says why.
 - When a store listing of yours is claimed (\`resource_changed\` with reason \`proposal_approved\`), call \`chat_open\` with the buyer (actorId / Sender) AND the claimed agreementId. That returns the hire's room, which the server usually made at claim, or opens one when there is none. Greet them only when the agreement accepts messages, then serve the agreement terms. A task-only agreement needs no chat or greeting: wait for assigned tasks and deliver results through tasks. Do not \`chat_send\` to an \`agrn-*\` session id — open a real chat first.
 - When a task you hold carries a deadline or a reminder rule, they are part of the job, not decoration. Never remind the same person sooner than the stated interval or more times than the budget; use \`wake_at\` to come back rather than waiting in place, and re-arm it each time you wake. When the budget is spent, stop asking and say what you have. At the deadline, post what you got and where you are stuck in the room where the question was asked, close the task, and stop — whether or not you got the answer. Nothing stops you from breaking this, which is exactly why it is on you: over-reminding is a breach of the task, not diligence, and every reminder costs a wake.
 - Hand off by completing your task — the platform notifies the next agent.

package/dist/brain/claudeSdkTools.js

@@ -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.' },
-    conversationAgreementId: { type: 'string', description: 'Explicit service work requested from the recipient, separate from your own run authority.' },
+    conversationAgreementId: { type: 'string', description: 'The agreement this message is under. In the room you were woken in, leave it out unless you mean a different agreement than this wake. When a send is refused with WORK_SELECTION_REQUIRED, name one of its choices.' },
     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. Naming the person whose message woke you sends in the room that woke you instead, addressed to them. 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: '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.' },
+    receiverId: { type: 'string', description: 'Name someone only when you mean them. Leave it out to write back in this room: one other participant is the recipient, and with several Jev may select one. Otherwise the message stays in the room with no specific wake. To name a masked party, pass its rpb_ ref as it came. Pass human to address the people in the room.' },
     text: { type: 'string', required: true },
     idempotencyKey: { type: 'string', description: 'Reuse for retry-safe resend of the same logical message.' },
 }, async (args, ctx) => {

package/dist/brain/hostedToolSurface.js

@@ -8,7 +8,8 @@
  * The tools stay registered on the ToolManager — the FSM brain and the
  * dispatcher both call them — they just stop riding every wake as schemas.
  */
-import { EVERYDAY_SDK_TOOLS, annotationForSdkTool } from '@ziggs-ai/api-client';
+import { EVERYDAY_SDK_TOOLS, annotationForSdkTool, backendToolPick } from '@ziggs-ai/api-client';
+import { credsFromToolContext } from '../tools/toolCreds.js';
 import { defineTool, toolName } from '../tools/defineTool.js';
 /**
  * Platform tools written by hand, not as a shared capability. Their lane is
@@ -132,6 +133,7 @@ async function callCatalogTarget(name, payload, ctx, execute) {
 function catalogTools(present, execute) {
     const list = () => [...present.values()].map(rowFor).sort((a, b) => a.name.localeCompare(b.name));
     const toolsTool = defineTool('tools', {
+        need: { type: 'string', description: 'Describe what you need to do. Suggests a tool and its schema; falls back to the catalog when unsure.' },
         search: {
             type: 'string',
             description: 'Filter by name or the one-line description. Omit to list every tool.',
@@ -141,7 +143,7 @@ function catalogTools(present, execute) {
             items: { type: 'string' },
             description: 'Tool names whose full schema you want before calling them.',
         },
-    }, async (args) => {
+    }, async (args, ctx) => {
         const describe = Array.isArray(args.describe) ? args.describe.map(String) : [];
         if (describe.length > 0) {
             return describe.map((name) => {
@@ -152,10 +154,22 @@ function catalogTools(present, execute) {
                 return { ...rowFor(tool), schema: tool.schema.function };
             });
         }
+        const need = typeof args.need === 'string' ? args.need.trim() : '';
+        if (need) {
+            const rows = list();
+            try {
+                const pick = await backendToolPick(credsFromToolContext(ctx, 'tools'))(need, rows.map(({ name, line }) => ({ name, line })));
+                const tool = pick?.how === 'pick' && pick.tool ? present.get(pick.tool) : undefined;
+                if (tool)
+                    return { suggestion: { ...rowFor(tool), schema: tool.schema.function }, confidence: pick?.confidence };
+            }
+            catch { /* Missing credentials or picker failure still leaves every tool available. */ }
+            return { tools: rows, note: 'No confident suggestion. Choose from the catalog; no action was taken.' };
+        }
         const q = typeof args.search === 'string' ? args.search.toLowerCase() : '';
         return list().filter((row) => !q || row.name.includes(q) || row.line.toLowerCase().includes(q));
     }, {
-        description: 'Every Ziggs tool that exists: name plus one line. A handful are already loaded by name; the rest are called through tool_read or tool_write. Pass describe with tool names to get their full schemas. Nothing is hidden.',
+        description: 'Every Ziggs tool that exists: name plus one line. A handful are already loaded by name; the rest are called through tool_read or tool_write. Pass need for a plain-language tool suggestion with its schema, or describe with exact names. Suggestions never execute tools. Nothing is hidden.',
     });
     const dispatch = (via) => async (args, ctx) => {
         const name = typeof args.tool === 'string' ? args.tool : '';

package/dist/runtime/PromptBuilder.d.ts

@@ -89,7 +89,7 @@ export declare class PromptBuilder {
     _renderAgreements(agreements: AnyObj[]): string;
     _renderRecipients(users: AnyObj[], otherAgents: AnyObj[], agreements: AnyObj[], myAgentId: string | null | undefined): string;
     _renderDecisionSchemaFromActions(actions: Record<string, Action>, senderMeta: SenderMeta, ctxObj: ServerContext, omitMessage?: boolean): string;
-    _buildActionSchema(name: string, replyTo: string, omitMessage?: boolean): string;
+    _buildActionSchema(name: string, omitMessage?: boolean): string;
     _getSenderMeta(event: RawEvent | AnyObj | null, ctxObj: ServerContext): SenderMeta;
     _getMyAgentId(ctxObj: ServerContext): string | null;
 }

package/dist/runtime/PromptBuilder.js

@@ -322,9 +322,10 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
             }
         }
         // Chat keeps the full directory — including opaque `rpb_*` / `psn_*` refs
-        // the persona layer may surface. Echo those as chat_send receiverId; the
-        // backend resolves them in-room. Transfer (and any account-id action) must
-        // never list opaque refs — lookup / wake / pay against them 400s.
+        // the persona layer may surface. To name a masked party, pass its `rpb_`
+        // ref as it came; the backend resolves it in-room. Transfer (and any
+        // account-id action) must never list opaque refs — lookup / wake / pay
+        // against them 400s.
         const chatIds = new Set([...userIds, ...agentIds]);
         const transferIds = new Set([...userIds, ...agentIds].filter((id) => !isOpaquePresentationRef(id)));
         const lines = ['<recipients>'];
@@ -381,8 +382,8 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         const lines = ['<decision_schema>'];
         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('Name "receiverId" only when you mean a specific recipient. Leave it out to write back in this room; an answer without one is sent without one.');
         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 = '<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.`);
@@ -402,7 +403,7 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
                 lines.push(`Response: {"thought": "...", "action": "${name}", "args": {...}}`);
             }
             else {
-                lines.push(this._buildActionSchema(name, replyTo, omitMessage));
+                lines.push(this._buildActionSchema(name, omitMessage));
             }
             if (actionDef.prompt?.examples?.length) {
                 lines.push('Examples:');
@@ -417,22 +418,14 @@ ${this._renderDecisionSchemaFromActions(actions, senderMeta, ctxObj, omitMessage
         lines.push('</decision_schema>');
         return lines.join('\n');
     }
-    _buildActionSchema(name, replyTo, omitMessage) {
+    _buildActionSchema(name, omitMessage) {
         if (name === 'wait') {
             return `Response: {"thought": "...", "action": "${name}"}`;
         }
-        // Never pre-fill a non-routable id (the literal 'system' or 'service'
-        // buckets) as the default receiverId. Fall back to an explicit placeholder
-        // so the model picks a real recipient from <recipients>.
-        const isSystemReplyTo = !replyTo ||
-            replyTo === 'system' ||
-            replyTo === 'service' ||
-            replyTo.startsWith('<');
-        const renderedReplyTo = isSystemReplyTo ? '<receiverId from <recipients>>' : replyTo;
         if (omitMessage) {
-            return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}"}`;
+            return `Response: {"thought": "...", "action": "${name}"}`;
         }
-        return `Response: {"thought": "...", "action": "${name}", "receiverId": "${renderedReplyTo}", "message": "..."}`;
+        return `Response: {"thought": "...", "action": "${name}", "message": "..."}`;
     }
     _getSenderMeta(event, ctxObj) {
         const ev = event;

package/dist/runtime/runTurn.js

@@ -450,7 +450,7 @@ export async function runTurn(input) {
                 repromptedForDecision = true;
                 runtimeLog.warn('runTurn', `unexecutable decision — reprompting once: action "${chosenAction}" missing required fields`);
                 messages.push({ role: 'assistant', content: llmResponse.content ?? '' });
-                messages.push({ role: 'user', content: `Your last output was not a valid action: action "${chosenAction}" was missing required fields (for a message this means both "receiverId" and "message"). Respond with exactly one action from the schema.` });
+                messages.push({ role: 'user', content: `Your last output was not a valid action: action "${chosenAction}" was missing required fields (for a message this means "message"). Respond with exactly one action from the schema.` });
                 continue;
             }
             const events = (Array.isArray(result) ? result : [result]);
@@ -666,7 +666,7 @@ async function executeDecision(decision, actionDef, eff, sessionId, memory, inco
     if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
         return await executeSendMessages(decision, eff, sessionId);
     }
-    if (decision.message && decision.receiverId) {
+    if (decision.message) {
         return await executeSendMessage(decision, eff, sessionId);
     }
     // Fallback: LLM may place message/receiverId inside args due to format ambiguity
@@ -707,7 +707,8 @@ function isReplySlotTaken(err) {
     return err?.status === 409;
 }
 async function executeSendMessage(decision, eff, sessionId) {
-    // Callers (executeDecision) guarantee message + receiverId, and sessionId is
+    // Callers guarantee message text. receiverId is set only when the model
+    // named someone; an answer without one is sent without one. sessionId is
     // always ctx.identity.sessionId. A send failure throws to the turn loop,
     // which converts it into the 'send-failed' error outcome — no silent nulls,
     // and message_sent is only emitted after the send effect resolved.
@@ -716,16 +717,22 @@ async function executeSendMessage(decision, eff, sessionId) {
     // to the current session otherwise.
     const targetSessionId = decision.chatId || sessionId;
     const safeMessage = truncateMsg(decision.message);
+    const receiverId = decision.receiverId || undefined;
     try {
-        await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: decision.receiverId, text: safeMessage });
+        await eff({
+            kind: 'send-message',
+            sessionId: targetSessionId,
+            ...(receiverId ? { 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' }];
+        runtimeLog.warn('runTurn', `reply already persisted for this wake (idempotency 409) — a replay or second host answered first; dropping duplicate${receiverId ? ` to ${receiverId}` : ''}`);
+        return [{ type: 'message_duplicate_skipped', ...(receiverId ? { receiverId } : {}), chatId: targetSessionId, senderId: 'system' }];
     }
-    const events = [{ type: 'message_sent', receiverId: decision.receiverId, chatId: targetSessionId, message: safeMessage, senderId: 'system' }];
+    const events = [{ type: 'message_sent', ...(receiverId ? { receiverId } : {}), chatId: targetSessionId, message: safeMessage, senderId: 'system' }];
     if (targetSessionId !== sessionId)
         events.push({ type: 'report_sent', message: 'Reported to owner.', senderId: 'system' });
     return events;
@@ -744,15 +751,20 @@ async function executeSendMessages(decision, eff, sessionId) {
     const failures = [];
     let attempted = 0;
     for (const msg of decision.messages ?? []) {
-        if (!msg.receiverId || !msg.message) {
-            failures.push({ receiverId: msg.receiverId || '<missing>', error: 'missing receiverId or message' });
+        if (!msg.message) {
+            failures.push({ receiverId: msg.receiverId || '<missing>', error: 'missing message' });
             continue;
         }
         const targetSessionId = msg.chatId || sessionId;
         const safeMessage = truncateMsg(msg.message);
         attempted++;
         try {
-            await eff({ kind: 'send-message', sessionId: targetSessionId, receiverId: msg.receiverId, text: safeMessage });
+            await eff({
+                kind: 'send-message',
+                sessionId: targetSessionId,
+                ...(msg.receiverId ? { receiverId: msg.receiverId } : {}),
+                text: safeMessage,
+            });
         }
         catch (err) {
             if (isReplySlotTaken(err)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.30.0",
+  "version": "0.32.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.284",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.29.0",
+    "@ziggs-ai/api-client": "0.31.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",