@ziggs-ai/agent-sdk 0.16.1 → 0.17.0

package/dist/{server → platform}/inboxLoop.js

@@ -8,6 +8,62 @@ function log(label, msg) {
 function warn(label, msg) {
     runtimeLog.warn(label, msg);
 }
+/**
+ * Store publish waits on a `probe_*` chat reply, not inbox ack. Act those
+ * rooms before leftover mail so a standing host answers the gate even when
+ * the envelope also carries older chats.
+ */
+export function chatsInWakeOrder(chats) {
+    return [...chats].sort((a, b) => {
+        const ap = isPublishProbeChat(a.chatId) ? 0 : 1;
+        const bp = isPublishProbeChat(b.chatId) ? 0 : 1;
+        if (ap !== bp)
+            return ap - bp;
+        return a.latestAt < b.latestAt ? 1 : -1;
+    });
+}
+function isPublishProbeChat(chatId) {
+    return chatId.startsWith('probe_');
+}
+/**
+ * Store publish waits on a chat reply, not inbox ack. The ordinary pass can
+ * already be inside leftover mail when that room appears, so a side read
+ * answers `probe_*` chats without waiting for the current pass to finish.
+ * It never acks — the main pass still owns the watermark.
+ */
+export async function answerPublishProbes(deps) {
+    const inbox = new InboxClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+    const reader = new ContextReadClient(deps.creds.operatorKey, deps.creds.agentId, deps.baseUrl);
+    const envelope = await inbox.getInbox({});
+    const probes = (envelope.chats ?? []).filter((c) => isPublishProbeChat(c.chatId));
+    if (probes.length === 0)
+        return 0;
+    const mine = (d) => d.assigneeId === deps.ownAgentId;
+    const earliestByChat = new Map();
+    for (const d of envelope.deliveries) {
+        if (!d.chatId || !mine(d) || !isPublishProbeChat(d.chatId))
+            continue;
+        const seen = earliestByChat.get(d.chatId);
+        if (!seen || d.ts < seen)
+            earliestByChat.set(d.chatId, d.ts);
+    }
+    const attempt = async (what, handover) => {
+        try {
+            await handover();
+            return true;
+        }
+        catch (err) {
+            warn(deps.label ?? 'inboxLoop', `publish-probe ${what} was not handled: ${err?.message ?? err}`);
+            return false;
+        }
+    };
+    let delivered = 0;
+    for (const news of probes) {
+        const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
+        delivered += await deliverMessagesForChat(deps, news, earliest, reader, attempt);
+    }
+    return delivered;
+}
 /**
  * Standing proposals share the merged inbox visibility model with deliveries,
  * but older envelopes predate an explicit assignee stamp. Prefer the server's
@@ -116,9 +172,9 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         }
     };
     if (envelope.deliveriesCapped) {
-        // Informational only — does NOT block acking what WAS handed over. The
-        // tail stays unacked and arrives on the next pass; never acking here would
-        // make a badly backed-up agent replay its whole backlog forever.
+        // The listed window is the oldest CAP. Acking it slides the cursor; the
+        // newer tail stays past ackTo and arrives on the next pass. Holding here
+        // was the wedge: the same over-cap window came back forever.
         warn(label, 'inbox deliveriesCapped (more mail than one envelope carries — the tail follows on the next pass)');
     }
     // The single-assign law: a row is MINE to act on iff it carries my stamp.
@@ -136,7 +192,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         if (!seen || d.ts < seen)
             earliestByChat.set(d.chatId, d.ts);
     }
-    for (const news of envelope.chats) {
+    for (const news of chatsInWakeOrder(envelope.chats ?? [])) {
         const earliest = earliestByChat.get(news.chatId) ?? news.latestAt;
         const n = await deliverMessagesForChat(deps, news, earliest, reader, attempt);
         messagesDelivered += n;
@@ -195,7 +251,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     }
     // request channel. Triage is the host's job (exact string compare);
     // a miss must still count as handled so the watermark can advance with 0 tokens.
-    for (const request of envelope.requestsAwaitingMe ?? []) {
+    for (const request of envelope.openRequestsAwaitingMe ?? []) {
         const key = `request:${request.agreementId}:${request.ts}`;
         if (deps.seen.has(key))
             continue;
@@ -245,12 +301,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
     // 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.
     let acked = false;
-    // A capped envelope has unlisted older deliveries behind ackTo;
-    // acking would refuse or bury them. Hold until a later uncapped pass.
-    if (envelope.deliveriesCapped && envelope.ackTo) {
-        warn(label, `holding the watermark at ${envelope.ackTo} — deliveriesCapped; ack would not cover the unlisted tail`);
-    }
-    else if (envelope.ackTo && (failures === 0 || opts.forceAck)) {
+    if (envelope.ackTo && (failures === 0 || opts.forceAck)) {
         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})`);
@@ -261,7 +312,7 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
         const handledResourceIds = [
             ...new Set([
                 ...envelope.deliveries.filter(mine).map((d) => d.resourceId),
-                ...(envelope.requestsAwaitingMe ?? []).map((q) => q.agreementId),
+                ...(envelope.openRequestsAwaitingMe ?? []).map((q) => q.agreementId),
             ]),
         ].filter((id) => typeof id === 'string' && id.length > 0);
         await inbox.ack(envelope.ackTo, { handledResourceIds });
@@ -289,6 +340,16 @@ export async function pollInboxOnce(deps, waitSeconds = 0, opts = {}) {
  * some defaults ship with. Lower it if your deployment sits behind a shorter one.
  */
 const DEFAULT_WAIT_SECONDS = 110;
+/**
+ * Side-poll interval for store-publish `probe_*` rooms.
+ *
+ * Default **off**. A second GET /inbox beside the main long-poll burned the
+ * shared poll ceiling: every hosted agent side-polled, probes got 429s, and
+ * Register saw ALB HTML 504s. Main pass + probe-first ordering + pinned
+ * `probe_*` deliveries are enough; set `probePollMs` only when you knowingly
+ * need the extra loop.
+ */
+const DEFAULT_PROBE_POLL_MS = 0;
 const ERROR_BACKOFF_BASE_MS = 1_000;
 const ERROR_BACKOFF_MAX_MS = 30_000;
 /**
@@ -299,6 +360,14 @@ const ERROR_BACKOFF_MAX_MS = 30_000;
  * 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.
+ */
+export function heldPassAfter(prev, pass) {
+    return !pass.acked && (pass.failures > 0 || pass.truncated) ? prev + 1 : 0;
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -317,21 +386,28 @@ function sleep(ms) {
 export function runInboxLoop(deps, opts = {}) {
     const label = deps.label ?? 'inboxLoop';
     const waitSeconds = opts.waitSeconds ?? DEFAULT_WAIT_SECONDS;
+    const probePollMs = opts.probePollMs ?? DEFAULT_PROBE_POLL_MS;
     let running = true;
     let consecutiveErrors = 0;
     let heldPasses = 0;
+    let lastPassAt = null;
+    let lastAttemptAt = null;
     let first = true;
-    const done = (async () => {
+    const main = (async () => {
         while (running) {
             try {
+                lastAttemptAt = Date.now();
                 const pass = await pollInboxOnce(deps, first ? 0 : waitSeconds, {
                     forceAck: heldPasses >= MAX_HELD_PASSES,
                 });
+                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.
-                heldPasses = pass.failures > 0 && !pass.acked ? heldPasses + 1 : 0;
+                // 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);
             }
             catch (err) {
                 if (!running)
@@ -356,10 +432,42 @@ export function runInboxLoop(deps, opts = {}) {
             }
         }
     })();
+    const probes = (async () => {
+        if (probePollMs <= 0)
+            return;
+        while (running) {
+            const slice = 50;
+            let left = probePollMs;
+            while (left > 0 && running) {
+                const step = Math.min(slice, left);
+                await sleep(step);
+                left -= step;
+            }
+            if (!running)
+                break;
+            try {
+                const n = await answerPublishProbes(deps);
+                if (n > 0)
+                    log(label, `publish-probe side poll delivered ${n} message(s)`);
+            }
+            catch (err) {
+                if (!running)
+                    break;
+                warn(label, `publish-probe side poll failed: ${err?.message ?? err}`);
+            }
+        }
+    })();
+    const done = Promise.all([main, probes]);
     return {
         get running() {
             return running;
         },
+        get lastPassAt() {
+            return lastPassAt;
+        },
+        get lastAttemptAt() {
+            return lastAttemptAt;
+        },
         async stop() {
             running = false;
             await done.catch(() => { });

package/dist/{server → platform}/polls/PollKind.d.ts

@@ -5,12 +5,9 @@
  *
  *   polls: [{ kind: 'sente-email', identityId: 'idt_...' }]
  *
- * It declares; it does not execute. Execution belongs to PollRunner, which the
- * launcher runs once for the whole fleet — polling is a fleet concern the way
- * the health server is, not a per-host behaviour: one loop per (agent, binding)
- * with its own interval, backoff and backpressure, instead of every host
- * hand-rolling a timer inside its message loop. Declaration travels with the
- * agent; execution does not.
+ * The declaration and its PollRunner travel with the Agent. connectAsync starts
+ * both inbox delivery and external polls; disconnect stops both. The process
+ * runner does not own a second copy of the polling lifecycle.
  *
  * A poll answers ONE question: is there work for this agent right now. It never
  * returns the work itself. The agent reads that for itself once woken, through
@@ -26,7 +23,7 @@
  * Kind-specific config, verbatim from the agent's manifest.
  *
  * `chatId` is not kind-specific and is not optional in practice: a wake has to
- * resolve to a lane or AgentHost's session resolver returns null and drops it
+ * resolve to a lane or Agent's session resolver returns null and drops it
  * silently. A poll has no engagement behind it to derive one from, so the
  * binding names the chat the agent thinks in — which also puts its triage
  * somewhere a human can watch. PollRunner refuses to register a binding without

package/dist/{server → platform}/polls/PollKind.js

@@ -5,12 +5,9 @@
  *
  *   polls: [{ kind: 'sente-email', identityId: 'idt_...' }]
  *
- * It declares; it does not execute. Execution belongs to PollRunner, which the
- * launcher runs once for the whole fleet — polling is a fleet concern the way
- * the health server is, not a per-host behaviour: one loop per (agent, binding)
- * with its own interval, backoff and backpressure, instead of every host
- * hand-rolling a timer inside its message loop. Declaration travels with the
- * agent; execution does not.
+ * The declaration and its PollRunner travel with the Agent. connectAsync starts
+ * both inbox delivery and external polls; disconnect stops both. The process
+ * runner does not own a second copy of the polling lifecycle.
  *
  * A poll answers ONE question: is there work for this agent right now. It never
  * returns the work itself. The agent reads that for itself once woken, through

package/dist/{server → platform}/polls/PollRunner.d.ts

@@ -1,11 +1,9 @@
 /**
- * PollRunner — executes declared polls for a whole fleet, outside any host.
+ * PollRunner — executes declared external wake sources for agents.
  *
- * Every host already long-polls its own Ziggs inbox; this applies the same wake
- * discipline to the sources Ziggs cannot see — mailboxes, feeds, whatever a
- * PollKind can ask. It runs in the launcher rather than inside any AgentHost
- * because none of it belongs to a host's message loop: a poll is per
- * (agent, binding) and carries its own interval, backoff and backpressure.
+ * Each Agent owns its runner and starts it with its inbox loop. A poll is per
+ * (agent, binding), with its own interval, backoff and backpressure. This same
+ * lifecycle applies to fleet, MCP-tool, lab and evaluation agents.
  *
  * One loop per (agent, binding), and each loop AWAITS its own wake before
  * scheduling the next tick. That is the whole backpressure story: while an
@@ -73,6 +71,7 @@ export declare class PollRunner {
     private readonly wakeWindowMs;
     private readonly loops;
     private running;
+    private generation;
     constructor({ pool, registry, agents, operatorKey, defaultIntervalMs, maxBackoffMs, wakeTimeoutMs, maxWakesPerWindow, wakeWindowMs, label, }: PollRunnerOptions);
     get size(): number;
     start(): void;

package/dist/{server → platform}/polls/PollRunner.js

@@ -1,11 +1,9 @@
 /**
- * PollRunner — executes declared polls for a whole fleet, outside any host.
+ * PollRunner — executes declared external wake sources for agents.
  *
- * Every host already long-polls its own Ziggs inbox; this applies the same wake
- * discipline to the sources Ziggs cannot see — mailboxes, feeds, whatever a
- * PollKind can ask. It runs in the launcher rather than inside any AgentHost
- * because none of it belongs to a host's message loop: a poll is per
- * (agent, binding) and carries its own interval, backoff and backpressure.
+ * Each Agent owns its runner and starts it with its inbox loop. A poll is per
+ * (agent, binding), with its own interval, backoff and backpressure. This same
+ * lifecycle applies to fleet, MCP-tool, lab and evaluation agents.
  *
  * One loop per (agent, binding), and each loop AWAITS its own wake before
  * scheduling the next tick. That is the whole backpressure story: while an
@@ -30,6 +28,7 @@ export class PollRunner {
     wakeWindowMs;
     loops = [];
     running = false;
+    generation = 0;
     constructor({ pool, registry, agents, operatorKey, defaultIntervalMs = 60_000, maxBackoffMs = 15 * 60_000, wakeTimeoutMs = Number(process.env.CLAUDE_SDK_TICK_TIMEOUT_MS ?? 300_000), maxWakesPerWindow = 20, wakeWindowMs = 60 * 60_000, label = 'PollRunner', }) {
         this.pool = pool;
         this.operatorKey = operatorKey;
@@ -65,6 +64,7 @@ export class PollRunner {
                     chatId: binding.chatId,
                     timer: null,
                     failures: 0,
+                    inFlight: false,
                     wakes: 0,
                     windowStartedAt: Date.now(),
                     capped: false,
@@ -79,14 +79,18 @@ export class PollRunner {
         if (this.running)
             return;
         this.running = true;
+        this.generation++;
         if (!this.loops.length)
             return;
-        for (const loop of this.loops)
-            this.schedule(loop, 0);
+        for (const loop of this.loops) {
+            if (!loop.inFlight)
+                this.schedule(loop, 0);
+        }
         runtimeLog.info(this.label, `started — ${this.loops.length} poll(s): ${this.loops.map((l) => `${l.agentId}:${l.kind.id}`).join(', ')}`);
     }
     stop() {
         this.running = false;
+        this.generation++;
         for (const loop of this.loops) {
             if (loop.timer)
                 clearTimeout(loop.timer);
@@ -97,7 +101,14 @@ export class PollRunner {
     schedule(loop, delayMs = this.nextDelay(loop)) {
         if (!this.running)
             return;
-        loop.timer = setTimeout(() => void this.tick(loop), delayMs);
+        loop.timer = setTimeout(() => {
+            loop.timer = null;
+            loop.inFlight = true;
+            void this.tick(loop, this.generation).finally(() => {
+                loop.inFlight = false;
+                this.schedule(loop);
+            });
+        }, delayMs);
     }
     /** Interval while healthy; doubling up to the ceiling while failing. */
     nextDelay(loop) {
@@ -105,7 +116,7 @@ export class PollRunner {
             return loop.intervalMs;
         return Math.min(loop.intervalMs * 2 ** loop.failures, this.maxBackoffMs);
     }
-    async tick(loop) {
+    async tick(loop, generation = this.generation) {
         if (!this.running)
             return;
         let result;
@@ -119,9 +130,11 @@ export class PollRunner {
         catch (err) {
             loop.failures += 1;
             runtimeLog.error(this.label, `${loop.agentId}:${loop.kind.id} source failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
-            this.schedule(loop);
             return;
         }
+        // A source read may finish after disconnect or a new connection.
+        if (!this.running || generation !== this.generation)
+            return;
         if (result?.actionable && this.claimWake(loop)) {
             const hint = result.hint ?? `New work from ${loop.kind.id}. Check it.`;
             try {
@@ -140,7 +153,6 @@ export class PollRunner {
                 runtimeLog.error(this.label, `${loop.agentId} wake failed (${loop.failures}x, next in ${this.nextDelay(loop)}ms): ${err.message}`);
             }
         }
-        this.schedule(loop);
     }
     /**
      * Take one wake from this binding's budget, or refuse.

package/dist/platform/polls/declaredPollRunner.d.ts

@@ -0,0 +1,4 @@
+import type { AgentOptions } from '../../Agent.js';
+import { PollRunner, type WakeTarget } from './PollRunner.js';
+/** Validate before starting any work, so a declared wake source cannot vanish. */
+export declare function createDeclaredPollRunner(options: AgentOptions, target: WakeTarget): PollRunner | null;

package/dist/platform/polls/declaredPollRunner.js

@@ -0,0 +1,29 @@
+import { PollRegistry } from './PollKind.js';
+import { PollRunner } from './PollRunner.js';
+/** Validate before starting any work, so a declared wake source cannot vanish. */
+export function createDeclaredPollRunner(options, target) {
+    const registry = new PollRegistry();
+    for (const kind of options.pollKinds ?? [])
+        registry.register(kind);
+    if (options.polls === undefined)
+        return null;
+    if (!Array.isArray(options.polls))
+        throw new Error('Agent: polls must be an array');
+    for (const binding of options.polls) {
+        if (!binding || !registry.get(binding.kind)) {
+            throw new Error(`Agent ${options.agentId}: unknown poll kind "${binding?.kind}"; declare its implementation in pollKinds`);
+        }
+        if (typeof binding.chatId !== 'string' || !binding.chatId.trim()) {
+            throw new Error(`Agent ${options.agentId}: poll "${binding.kind}" requires a chatId`);
+        }
+    }
+    if (!options.polls.length)
+        return null;
+    return new PollRunner({
+        pool: target,
+        registry,
+        agents: [{ agentId: options.agentId, polls: options.polls }],
+        operatorKey: options.operatorKey,
+        label: `${options.name || options.agentId}-polls`,
+    });
+}

package/dist/{server → platform}/tools/tier2/mcpConnectionTools.js

@@ -2,7 +2,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
 import { ConnectionsClient } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
-import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
+import { resolveZiggsGatewayTarget } from '../../../mcp/createMcpAgent.js';
 /**
  * Calling a tool on a connected MCP server, one shot.
  *
@@ -15,7 +15,7 @@ import { resolveZiggsGatewayTarget } from '../../../adapters/McpAdapter.js';
  *
  * The gateway (`POST /connections/:id/mcp`) has always been the right door and is
  * already in production; what was missing was a tool that walks through it. The
- * transport, headers and MCP handshake are the same ones `McpAdapter`'s `ziggs`
+ * transport, headers and MCP handshake are the same ones `createMcpAgent`'s `ziggs`
  * transport uses — reused rather than re-derived, so a change to the gateway
  * contract lands in one place.
  *
@@ -66,7 +66,10 @@ async function withClient(ctx, connectionId, grantId, run) {
         grantId,
         operatorKey: ctx['operatorKey'],
         agentId: ctx['agentId'],
-    }, { agentId: ctx['agentId'] });
+    }, {
+        agentId: ctx['agentId'],
+        laneId: ctx['laneId'],
+    });
     const transport = new StreamableHTTPClientTransport(target.url, {
         requestInit: { headers: target.headers },
     });

package/dist/runtime/bootstrapCtx.d.ts

@@ -3,7 +3,7 @@ import type { Ctx, Identity } from '../types.js';
  * The one place a per-lane `Ctx` is constructed.
  *
  * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
- * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * and the Claude Agent SDK brain (`ClaudeBrain.tick`). Before this, each
  * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
  * and they had already drifted (the "default them ONCE here" comment in
  * AgentMachine no longer held). Keep it here so the shape lives in a single spot.

package/dist/runtime/bootstrapCtx.js

@@ -3,7 +3,7 @@ import { migrateLegacyTaskFields } from './taskBookkeeping.js';
  * The one place a per-lane `Ctx` is constructed.
  *
  * Both cognitions bootstrap the same Ctx: the FSM (`AgentMachine` constructor)
- * and the Claude Agent SDK brain (`ClaudeSdkAgent.tick`). Before this, each
+ * and the Claude Agent SDK brain (`ClaudeBrain.tick`). Before this, each
  * carried its own copy of the fresh-Ctx literal and the restore-path defaulting,
  * and they had already drifted (the "default them ONCE here" comment in
  * AgentMachine no longer held). Keep it here so the shape lives in a single spot.

package/dist/runtime/buildOutcome.js

@@ -162,7 +162,7 @@ function singleEventToOutcome(ev, ownAgentId) {
         return null;
     }
     if (ev.type === 'state-timeout') {
-        // Synthetic frame from AgentHost's StateTimers — host-constructed, fields always present.
+        // Synthetic frame from Agent's StateTimers — host-constructed, fields always present.
         return { kind: 'state-timeout', state: ev.state, waitedMs: ev.waitedMs };
     }
     // Only real inbound chat messages should drive the FSM. Backend bookkeeping

package/dist/runtime/runTurn.d.ts

@@ -15,7 +15,7 @@ interface RunTurnInput {
     toolManager: ToolManager;
     promptBuilder: PromptBuilder;
     /**
-     * Agent-private long-term memory, threaded from AgentHost. Currently
+     * Agent-private long-term memory, threaded from Agent. Currently
      * surfaced into `eff` as part of the tool-call effect payload so tools
      * can read/write notes; the prompt builder doesn't consume it yet.
      */

package/dist/runtime/runTurn.js

@@ -1,7 +1,9 @@
+import { isAgreementId } from '@ziggs-ai/api-client';
 import { outcomeFromActionResult } from './buildOutcome.js';
 import { runtimeLog } from '../shared/runtimeLog.js';
 import { safeParseJSON } from '../utils/jsonExtractor.js';
 import { withDeclaredMandate } from './mandateDeclaration.js';
+import { resolveOnBehalfAgreementId, } from '../brain/onBehalfAgreement.js';
 const MAX_TOOL_LOOP_ITERS = 20;
 const MAX_MSG_CHARS = 3500;
 /**
@@ -117,9 +119,7 @@ export async function runTurn(input) {
     // only. a bare agreement id as sessionId is a mis-keyed lane —
     // loud-log the empty snapshot rather than staying silent.
     if (ctxObj.chatMissing) {
-        const looksLikeBareAgreement = typeof sessionId === 'string' &&
-            sessionId.startsWith('agr_') &&
-            !sessionId.startsWith('agrn-');
+        const looksLikeBareAgreement = isAgreementId(sessionId);
         if (looksLikeBareAgreement) {
             runtimeLog.warn('runTurn', `chatMissing on non-chat sessionId=${sessionId} (state=${stateId}) — ` +
                 `lane was keyed by agreementId instead of the agreement's origin/notification chat; ` +
@@ -265,7 +265,9 @@ export async function runTurn(input) {
                 // not. The runtime knows; the model would have to be told.
                 args = withDeclaredMandate(args, toolName, toolManager, ctx.activeAgreementId);
                 const decision = { action: matchingAction, tool: toolName, args };
-                const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
+                const result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, incomingEvent, addToolUsage, ctx.identity.agentId, Array.isArray(ctxObj.agreements)
+                    ? ctxObj.agreements
+                    : null);
                 toolCallResults.push({ tc, matchingAction, result, args, actionDef });
             }
             let hasTerminal = false;
@@ -418,7 +420,9 @@ export async function runTurn(input) {
             try {
                 // effWithTrace, not eff: JSON-path tool calls must carry runId/stateId
                 // and the wake's write keys exactly like tool-loop calls do.
-                result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, null, addToolUsage);
+                result = await executeDecision(decision, actionDef, effWithTrace, sessionId, memory, incomingEvent, addToolUsage, ctx.identity.agentId, Array.isArray(ctxObj.agreements)
+                    ? ctxObj.agreements
+                    : null);
             }
             catch (err) {
                 // Only outbound sends can throw out of executeDecision — executeTool
@@ -642,17 +646,18 @@ function findActionForTool(toolName, allowedActionNames, actions) {
     }
     return null;
 }
-async function executeDecision(decision, actionDef, eff, sessionId, memory, incomingEvent = null, onUsage) {
+async function executeDecision(decision, actionDef, eff, sessionId, memory, incomingEvent = null, onUsage, agentId = null, agreements = null) {
     const boundTool = actionDef?.tool || null;
     if (boundTool) {
         decision.tool = boundTool;
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
     }
     if (decision.action === '_genericDiscoveryTool' && decision.tool) {
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
+    }
+    if (decision.tool) {
+        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage, agentId, agreements);
     }
-    if (decision.tool)
-        return await executeTool(decision, eff, sessionId, memory, incomingEvent, onUsage);
     if (decision.messages && Array.isArray(decision.messages) && decision.messages.length > 0) {
         return await executeSendMessages(decision, eff, sessionId);
     }
@@ -775,7 +780,7 @@ async function executeSendMessages(decision, eff, sessionId) {
  * dependencies (taskService, agreementService, agents list, etc.), and
  * wrapping the call in telemetry / operation-record entries if it wants.
  */
-async function executeTool(decision, eff, sessionId, memory, incomingEvent = null, onUsage) {
+async function executeTool(decision, eff, sessionId, memory, incomingEvent = null, onUsage, agentId = null, agreements = null) {
     const { tool, args } = decision;
     if (!tool)
         return null;
@@ -788,13 +793,8 @@ async function executeTool(decision, eff, sessionId, memory, incomingEvent = nul
             memory,
             senderId: incomingEvent?.senderId != null ? String(incomingEvent.senderId) : undefined,
             senderType: incomingEvent?.senderType != null ? String(incomingEvent.senderType) : undefined,
-            // the subcontract agreement this wake is under (task events carry
-            // it under `result.agreementId`) so a delegated per-user MCP call can
-            // resolve the originating end-user, not the delegating agent (senderId).
-            onBehalfOfAgreementId: (() => {
-                const aid = incomingEvent?.result?.agreementId;
-                return typeof aid === 'string' && aid ? aid : undefined;
-            })(),
+            // Never bind on-behalf to a sub the agent only pays for.
+            onBehalfOfAgreementId: resolveOnBehalfAgreementId(incomingEvent ?? undefined, agreements, agentId, sessionId),
         });
         if (r.usage)
             onUsage?.(r.usage);

package/dist/runtime/validateWorkflow.js

@@ -94,7 +94,7 @@ export function validateWorkflow(workflow) {
                 errors.push(`thinking state "${name}" requires at least one action`);
             }
             if (state.timeoutMs !== undefined) {
-                errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by AgentHost tickTimeoutMs)`);
+                errors.push(`state "${name}" is thinking but declares timeoutMs — liveness timers apply to parked states only (thinking turns are bounded by Agent tickTimeoutMs)`);
             }
         }
         if (state.kind === 'mechanical') {

package/dist/skills/parseSkill.d.ts

@@ -61,9 +61,14 @@ export declare function skillHash(files: SkillFile[]): string;
 export declare function parseSkill(files: SkillFile[], opts?: {
     maxChars?: number;
 }): ParsedSkill;
+/** Catalog name for a reference path (`references/tone.md` → `tone`). */
+export declare function skillReferenceName(path: string): string;
+/** First prose line of a reference, for the on-prompt catalog. */
+export declare function skillReferenceOneLine(content: string): string;
 /**
- * Assemble the skill's role prompt: body first, then each reference under its
- * own header.
+ * Assemble the skill's role prompt: the body, then a catalog of references.
+ * Full reference text is fetched with `skill_read_reference` — it does not
+ * ride every turn.
  *
  * This is only the ROLE block. The Ziggs protocol is prepended separately, by
  * the one place that builds a Claude-brain system prompt — a skill is never in a