@ziggs-ai/agent-sdk 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -12,6 +12,11 @@
 
 ## Unreleased
 
+### Added
+
+- `task_cancel` on the hosted Claude surface, same PATCH /tasks/:id/cancel
+  as the MCP catalog verb. A held graph withdraws by cancelling the root.
+
 ### Breaking
 
 - `AgentHostOptions.questMatchTags` is now `requestMatchTags`. The option is an

package/dist/Agent.d.ts

@@ -1,4 +1,5 @@
 import type { PollBinding, PollKind } from './platform/polls/PollKind.js';
+export { workScopeFromWake } from './runtime/wakeEffects.js';
 import type { AgentConfig, Ctx, Workflow } from './types.js';
 import { ZiggsBrain, type TickOutput } from './brain/ZiggsBrain.js';
 import { ClaudeBrain, type CognitionKind } from './brain/ClaudeBrain.js';
@@ -56,11 +57,6 @@ export declare function laneSessionIdForTask(task: {
     originChatId?: string | null;
     agreementId?: string | null;
 }): string;
-/** Pull the cost-record keys off a wake event or session id. */
-export declare function workScopeFromWake(event: unknown, sessionId?: string): {
-    agreementId?: string;
-    taskId?: string;
-};
 interface LlmAdapter {
     chatMessages(messages: unknown[], tools?: unknown[], options?: Record<string, unknown>): Promise<unknown>;
 }
@@ -111,6 +107,12 @@ export interface AgentOptions {
      * Internal mapping: `fsm` → Ziggs brain, `claude-sdk` → Claude brain.
      */
     cognition?: CognitionKind;
+    /**
+     * Spend a model turn on an activation notice for a hire an agent formed.
+     * Default off — the host records a no-op and waits for the assigned task.
+     * A hire a person formed (store claim) still wakes regardless of this flag.
+     */
+    actsOnHireActivation?: boolean;
     /** Max agentic turns per Claude SDK wake. Default 30. */
     claudeMaxTurns?: number;
     /**
@@ -256,6 +258,9 @@ export declare class Agent {
     private askedForAccessLanes;
     /** Tasks left active by the asking turn, failed right after it (per lane). */
     private unmetTasksPendingAsk;
+    private readonly wakeEffects;
+    private readonly outboundMessages;
+    private readonly confirmedPlanVersions;
     private grantProviderCache;
     constructor(options?: AgentOptions);
     private _validate;
@@ -300,7 +305,21 @@ export declare class Agent {
      * wake keys on the live room / hire.
      */
     private dropStaleCancelledAgreementSession;
+    private formedByForHireActivation;
     private laneAgreementIsTerminal;
+    /**
+     * Whether the host answers this wake without spending a model turn.
+     *
+     * One decision, consulted by the live path and by {@link Agent.replayWake},
+     * because a recording is only worth keeping if a replay can tell you what the
+     * host would do now. It used to run only on the live path, so an edit to any
+     * of these rules was invisible to a replay — the tool that exists to answer
+     * "what changed?" could not see the change.
+     *
+     * Every rule here reads a row or the frame itself. None of them reads a lane,
+     * an agent kind, a name or an id shape.
+     */
+    private wakeSuppression;
     /**
      * the trailing turn on work that is already reported.
      *
@@ -384,8 +403,10 @@ export declare class Agent {
      */
     private triageRequestDelivery;
     /** replay task-assigned for an existing active task (demo recovery). */
-    wakeTaskAssignment(taskId: string): Promise<void>;
-    disconnect(): void;
+    wakeTaskAssignment(taskId: string, options?: {
+        fromInbox?: boolean;
+    }): Promise<void>;
+    disconnect(): Promise<void>;
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.
      * A timeout is returned, not thrown — the caller names it (lab verdict, fleet

package/dist/Agent.js

@@ -1,6 +1,9 @@
 import { agreementLaneId, agreementIdFromLane } from '@ziggs-ai/api-client';
 import { createDeclaredPollRunner } from './platform/polls/declaredPollRunner.js';
 import { randomUUID } from 'node:crypto';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { WakeEffects } from './runtime/wakeEffects.js';
+export { workScopeFromWake } from './runtime/wakeEffects.js';
 import { ZiggsBrain } from './brain/ZiggsBrain.js';
 import { ClaudeBrain } from './brain/ClaudeBrain.js';
 import { applyBrainToAgentOptions, isClaudeCognition, } from './brain/index.js';
@@ -14,14 +17,14 @@ import { WAKE_TOOLS } from './platform/tools/tier1/wakeTools.js';
 import { createZiggsEffectHandler } from './platform/ZiggsEffectHandler.js';
 import { normalizeIncomingEvent } from './ingress/normalizeIncoming.js';
 import { PromptBuilder } from './runtime/PromptBuilder.js';
-import { InMemoryStore, memorySectionForWake, partitionMemoryStore, } from './memory/MemoryStore.js';
+import { InMemoryStore, hireIdsFromEvent, memorySectionForWake, partitionMemoryStore, uniqueHireIds, } from './memory/MemoryStore.js';
 import { ToolManager } from './tools/ToolManager.js';
 import { toolName } from './tools/defineTool.js';
 import { PROTOCOL_TOOLS } from './platform/tools/tier1/protocolTools.js';
 import { marketplaceViewTool } from './platform/tools/tier2/marketplaceTools.js';
 import { OpenAIAdapter } from './adapters/OpenAIAdapter.js';
 import { AnthropicAdapter } from './adapters/AnthropicAdapter.js';
-import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, } from '@ziggs-ai/api-client';
+import { ArtifactsClient, ConnectionsClient, ContextReadClient, TelemetryClient, sendChatMessage, presentSendResult, } from '@ziggs-ai/api-client';
 import { normalizeNeeds, unmetNeeds, unmetNeedsMessage, } from './tools/needs.js';
 import { TaskService } from './platform/tasks/TaskService.js';
 import { AgreementService } from './platform/agreements/AgreementService.js';
@@ -30,7 +33,8 @@ import { requestExactMatch } from './platform/requestMatch.js';
 import { SeenMessages } from './platform/SeenMessages.js';
 import { runtimeLog } from './shared/runtimeLog.js';
 import { isTelemetryIngestEnabled, sendTelemetry, } from './platform/telemetryIngest.js';
-import { buildWakeOutcomePayload, classifyWakeOutcome, } from './runtime/wakeOutcome.js';
+import { buildWakeOutcomePayload, classifyWakeOutcome, wakeWasAsked, } from './runtime/wakeOutcome.js';
+import { agreementIdFromWake, formedByFromWake, isHireActivationNotice, shouldSkipAgentFormedHireActivation, } from './brain/hireActivationNotice.js';
 /**
  * The single fleet-wide default model — the one place the fallback lives.
  * Change this (or set `LLM_MODEL`) to move the whole fleet; nothing hardcodes a
@@ -65,26 +69,6 @@ export function laneSessionIdForTask(task) {
     }
     return 'default';
 }
-/** Pull the cost-record keys off a wake event or session id. */
-export function workScopeFromWake(event, sessionId) {
-    const rec = event && typeof event === 'object' ? event : {};
-    const resource = rec.resource && typeof rec.resource === 'object'
-        ? rec.resource
-        : {};
-    const agreementId = (typeof rec.agreementId === 'string' && rec.agreementId) ||
-        (typeof resource.agreementId === 'string' && resource.agreementId) ||
-        agreementIdFromLane(rec.chatId) ||
-        agreementIdFromLane(resource.chatId) ||
-        agreementIdFromLane(sessionId) ||
-        undefined;
-    const taskId = (typeof rec.taskId === 'string' && rec.taskId) ||
-        (typeof resource.taskId === 'string' && resource.taskId) ||
-        undefined;
-    return {
-        ...(agreementId ? { agreementId } : {}),
-        ...(taskId ? { taskId } : {}),
-    };
-}
 function createToolManager(options) {
     const toolManager = new ToolManager();
     const userTools = options.tools || options.services?.tools || [];
@@ -220,6 +204,9 @@ export class Agent {
     askedForAccessLanes = new Set();
     /** Tasks left active by the asking turn, failed right after it (per lane). */
     unmetTasksPendingAsk = new Map();
+    wakeEffects = new AsyncLocalStorage();
+    outboundMessages = new SeenMessages();
+    confirmedPlanVersions = new SeenMessages();
     grantProviderCache = null;
     constructor(options = {}) {
         const resolved = applyBrainToAgentOptions(options);
@@ -258,6 +245,7 @@ export class Agent {
             polls: resolved.polls,
             pollKinds: resolved.pollKinds,
             cognition: resolved.cognition ?? 'fsm',
+            actsOnHireActivation: resolved.actsOnHireActivation === true,
             claudeMaxTurns: resolved.claudeMaxTurns,
             claudeStatelessPerWake: resolved.claudeStatelessPerWake,
         };
@@ -313,18 +301,28 @@ export class Agent {
             operatorKey: this.options.operatorKey,
             agentId: this.options.agentId,
         };
-        const messageSender = (message, receiverId, sessionId, messageId) => sendChatMessage({
-            chatId: sessionId,
-            // Omitted on purpose when the caller has no valid address for THIS
-            // room: the backend infers the recipient from the room's own
-            // participants.
-            receiverId,
-            text: message,
-            // messageId is the backend's (chatId, messageId) dedup key. Callers
-            // pass a wake-derived id for replay-stability; fall back to a fresh id
-            // only when absent (matches the old WS path letting the server assign).
-            messageId: messageId ?? `sdk_${randomUUID()}`,
-        }, creds);
+        const messageSender = async (message, receiverId, sessionId, messageId) => {
+            const sentId = messageId ?? `sdk_${randomUUID()}`;
+            const result = await sendChatMessage({
+                chatId: sessionId,
+                // Omitted on purpose when the caller has no valid address for THIS
+                // room: the backend infers the recipient from the room's own
+                // participants.
+                receiverId,
+                text: message,
+                // messageId is the backend's (chatId, messageId) dedup key. Callers
+                // pass a wake-derived id for replay-stability; fall back to a fresh id
+                // only when absent (matches the old WS path letting the server assign).
+                messageId: sentId,
+            }, 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.');
+            this.outboundMessages.mark(JSON.stringify([result.chatId, result.messageId]));
+            // Presented once, here, so every hosted send — FSM reply, brain tool,
+            // stream follow-up — reports the destination the same way the MCP
+            // surface does.
+            return { ...result, ...presentSendResult(result, { creds, surface: 'sdk' }) };
+        };
         this.taskService = services.taskService;
         this.agreementService = services.agreementService;
         this.telemetryClient = services.telemetryClient;
@@ -366,12 +364,18 @@ export class Agent {
             agentId: this.options.agentId,
             telemetryClient: services.telemetryClient,
             telemetryIngest: this.options.telemetryIngest,
-            effectTap: this.options.effectTap,
+            effectTap: (effect, response) => {
+                const marks = this.wakeEffects.getStore();
+                marks?.observe(effect, response);
+                for (const key of marks?.sentMessageKeys ?? [])
+                    this.outboundMessages.mark(key);
+                this.options.effectTap?.(effect, response);
+            },
             // `wake_at` reaches the lane's timer through here. The handler
             // is built once and has no laneKey, so it derives one the same way the
             // event queue does (see laneKeyFor).
             wakeScheduler: {
-                armWakeAt: (sessionId, at, reason) => this.stateTimers.armWakeAt(laneKeyFor(this.options.agentId, sessionId), at, reason),
+                armWakeAt: (sessionId, at, reason) => this.stateTimers.armWakeAt(laneKeyFor(this.options.agentId, sessionId), at, reason, this.wakeEffects.getStore()?.scope),
             },
         });
         this.brain = isClaudeCognition(this.options.cognition)
@@ -390,6 +394,7 @@ export class Agent {
                 // services from the effect handler's deps like the FSM path.
                 maxTurns: this.options.claudeMaxTurns,
                 statelessPerWake: this.options.claudeStatelessPerWake,
+                actsOnHireActivation: this.options.actsOnHireActivation === true,
             })
             : new ZiggsBrain({
                 workflow,
@@ -513,7 +518,7 @@ export class Agent {
         // the same message being processed twice; leaving it set on a failed wake
         // would make the redelivery this rejection buys us a no-op.
         try {
-            await this.eventQueue.enqueue(normalized.event, laneKey);
+            await this.eventQueue.enqueue({ ...normalized.event, chatId: normalized.chatId }, laneKey);
         }
         catch (err) {
             if (messageId)
@@ -542,7 +547,13 @@ export class Agent {
         const agentId = session.ownAgentId || this.options.agentId;
         const laneKey = laneKeyFor(agentId, session.sessionId);
         runtimeLog.info(this.options.name || 'agent', `wake-outcome agent=${agentId} lane=${laneKey} kind=${outcome.kind}` +
-            (outcome.reason ? ` reason=${outcome.reason}` : ''));
+            (outcome.reason ? ` reason=${outcome.reason}` : '') +
+            // A question nobody answered is the line worth grepping for, so it is
+            // on the line rather than only in the telemetry payload.
+            (outcome.reply
+                ? ` asked=1 answered=${outcome.reply.sent ? 1 : 0}` +
+                    (outcome.reply.sent ? '' : ` unanswered=${outcome.reply.reason}`)
+                : ''));
         sendTelemetry(this.telemetryClient, buildWakeOutcomePayload({
             agentId,
             sessionId: session.sessionId,
@@ -551,12 +562,28 @@ export class Agent {
             llmCalls,
         }), isTelemetryIngestEnabled(this.options.telemetryIngest));
     }
-    memoryForWake(session) {
-        return partitionMemoryStore(this.memory, memorySectionForWake({
+    memoryForWake(session, event) {
+        const fromEvent = hireIdsFromEvent(event);
+        const wakeAgreementIds = uniqueHireIds([
+            ...fromEvent,
+            session.actingHireId,
+        ]);
+        const section = memorySectionForWake({
             sessionId: session.sessionId,
             activeAgreementId: session.ctx
                 ?.activeAgreementId,
-        }));
+            wakeAgreementIds,
+        });
+        const known = uniqueHireIds([
+            session.ctx
+                ?.activeAgreementId,
+            ...wakeAgreementIds,
+        ]);
+        if (known.length === 1)
+            session.actingHireId = known[0];
+        else if (known.length > 1)
+            session.actingHireId = null;
+        return partitionMemoryStore(this.memory, section);
     }
     /**
      * A chat-lane session that still carries a cancelled hire from a previous
@@ -585,6 +612,24 @@ export class Agent {
             // Fail open: a lookup error must not drop a live hire's session.
         }
     }
+    async formedByForHireActivation(event) {
+        const fromWake = formedByFromWake(event);
+        if (fromWake)
+            return fromWake;
+        const agreementId = agreementIdFromWake(event);
+        if (!agreementId || !this.agreementService)
+            return undefined;
+        try {
+            const agreement = await this.agreementService.get(agreementId);
+            const formedBy = agreement?.formedBy;
+            if (formedBy === 'agent' || formedBy === 'principal')
+                return formedBy;
+        }
+        catch {
+            // Fail open: a lookup error must not drop a person's store-claim wake.
+        }
+        return undefined;
+    }
     async laneAgreementIsTerminal(sessionId) {
         const agreementId = agreementIdFromLane(sessionId);
         if (!agreementId || !this.agreementService)
@@ -598,6 +643,43 @@ export class Agent {
             return false;
         }
     }
+    /**
+     * Whether the host answers this wake without spending a model turn.
+     *
+     * One decision, consulted by the live path and by {@link Agent.replayWake},
+     * because a recording is only worth keeping if a replay can tell you what the
+     * host would do now. It used to run only on the live path, so an edit to any
+     * of these rules was invisible to a replay — the tool that exists to answer
+     * "what changed?" could not see the change.
+     *
+     * Every rule here reads a row or the frame itself. None of them reads a lane,
+     * an agent kind, a name or an id shape.
+     */
+    async wakeSuppression(event, sessionId) {
+        if (await this.laneAgreementIsTerminal(sessionId)) {
+            return { reason: 'agreement_terminal', because: 'its agreement is terminal' };
+        }
+        if (this.isSettledTaskEcho(event)) {
+            return {
+                reason: 'task_already_settled',
+                because: 'its task already reported a result',
+            };
+        }
+        if (isHireActivationNotice(event)) {
+            const formedBy = await this.formedByForHireActivation(event);
+            if (shouldSkipAgentFormedHireActivation({
+                event,
+                formedBy,
+                actsOnHireActivation: this.options.actsOnHireActivation === true,
+            })) {
+                return {
+                    reason: 'agent_formed_hire_activation',
+                    because: 'agent-formed hire activation',
+                };
+            }
+        }
+        return null;
+    }
     /**
      * the trailing turn on work that is already reported.
      *
@@ -780,14 +862,30 @@ export class Agent {
         const session = this.sessions.get(laneKey);
         if (!session?.sessionId)
             return;
-        if (await this.laneAgreementIsTerminal(session.sessionId)) {
-            runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its agreement is terminal`);
-            this.recordWakeOutcome(session, { kind: 'no-op', reason: 'agreement_terminal' });
+        // Presentation may call our sender an rpb-* room binding or the person we
+        // stand in for. Only an exact (chat, messageId) we successfully sent proves
+        // an echo; another message from the same binding still gets a full wake.
+        const incoming = event;
+        const events = incoming?.type === 'batch' && Array.isArray(incoming.events) ? incoming.events : [event];
+        const remaining = events.filter((item) => {
+            const e = item;
+            const task = e?.type === 'task_result' ? e.result : undefined;
+            if (this.stateTimers.peek(laneKey)?.kind === 'wake-at'
+                && e?.source === 'active-task-snapshot' && (task?.state === 'active' || task?.state === 'in-progress')
+                && task?.assigneeId === this.options.agentId && task.taskId && task.updatedAt && this.confirmedPlanVersions.has(JSON.stringify([laneKey, JSON.stringify([task.taskId, task.updatedAt])])))
+                return false;
+            return e?.type !== 'message' || !e.messageId || !this.outboundMessages.has(JSON.stringify([e.chatId ?? session.sessionId, e.messageId]));
+        });
+        if (remaining.length === 0) {
+            this.recordWakeOutcome(session, { kind: 'no-op', reason: events.some(e => e?.type === 'task_result') ? 'own_plan_snapshot' : 'own_message_echo' });
             return;
         }
-        if (this.isSettledTaskEcho(event)) {
-            runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — its task already reported a result`);
-            this.recordWakeOutcome(session, { kind: 'no-op', reason: 'task_already_settled' });
+        if (remaining.length !== events.length)
+            event = remaining.length === 1 ? remaining[0] : { type: 'batch', events: remaining };
+        const suppressed = await this.wakeSuppression(event, session.sessionId);
+        if (suppressed) {
+            runtimeLog.info(this.options.name || 'agent', `skipping wake on ${session.sessionId} — ${suppressed.because}`);
+            this.recordWakeOutcome(session, { kind: 'no-op', reason: suppressed.reason });
             return;
         }
         // Before the tick spends anything: work this agent declared it cannot do
@@ -799,9 +897,10 @@ export class Agent {
         const frame = this.stateTimers.stripStale(event, laneKey);
         if (frame === null)
             return;
-        // Any event reaching the machine invalidates the countdown ("clear on any
-        // event for the lane"); re-armed below if the tick settles parked+timed.
-        this.stateTimers.clear(laneKey);
+        // Traffic resets inactivity timers, but must not cancel an appointment
+        // the agent explicitly requested. Only its own fresh timer frame consumes
+        // that wake; a notice-only tick cannot ask the model to restore it.
+        this.stateTimers.consumeForEvent(frame, laneKey);
         // Cold-start recovery: restore FSM state from sessionStore when the
         // in-memory lane has no prior context (e.g. after a container restart).
         if (this.sessionStore && session.ctx === undefined && session.state === undefined) {
@@ -822,7 +921,7 @@ export class Agent {
             sessionId: session.sessionId,
             laneKey,
         };
-        const memory = this.memoryForWake(session);
+        const memory = this.memoryForWake(session, frame);
         // Recorded here rather than after the tick: this is the last point where the
         // input is still exactly what the brain will see, and a wake that goes on to
         // throw is the one most worth replaying.
@@ -850,20 +949,17 @@ export class Agent {
         // a zombie — burning tokens and racing the redelivered retry of the same
         // event (duplicate sends, runaway per-wake input).
         const tickAbort = new AbortController();
-        const marks = { sent: 0, tasks: 0 };
+        const marks = WakeEffects.forWake(frame, session.sessionId);
         const eff = async (effect) => {
-            if (effect.kind === 'send-message')
-                marks.sent += 1;
-            if (effect.kind === 'tool-call') {
-                const name = 'name' in effect ? String(effect.name) : '';
-                if (name.startsWith('task_'))
-                    marks.tasks += 1;
-            }
-            return this.eff(effect);
+            const response = await this.eff(effect);
+            marks.observe(effect, response);
+            for (const key of marks.sentMessageKeys)
+                this.outboundMessages.mark(key);
+            return response;
         };
         try {
             const result = await Promise.race([
-                this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal }),
+                this.wakeEffects.run(marks, () => this.brain.tick({ event: frame, ctx: session.ctx, state: session.state, identity, eff, memory, transitionTap: this.options.transitionTap, signal: tickAbort.signal })),
                 new Promise((_, reject) => {
                     tickWatchdog = setTimeout(() => {
                         tickAbort.abort(new Error('tick timeout'));
@@ -875,11 +971,11 @@ export class Agent {
             session.state = result.state;
             this.sessions.set(laneKey, session);
             this.recordWakeOutcome(session, classifyWakeOutcome({
-                lastOutcomeKind: result.ctx
-                    ?.lastOutcome?.kind,
+                skippedReason: result.skippedReason,
                 llmCalls: result.metrics?.llmCalls ?? 0,
-                sentMessage: marks.sent > 0,
-                taskWrite: marks.tasks > 0,
+                sentMessage: marks.sentMessage,
+                taskWrite: marks.taskWrite,
+                asked: wakeWasAsked(frame, identity.agentId),
             }), result.metrics?.llmCalls ?? 0);
             // One line per wake that actually spent LLM budget — the handle for
             // tracking a hosted agent live (grep `agent=<id>`). Parked no-op ticks
@@ -902,7 +998,7 @@ export class Agent {
                         model: this.options.model ?? 'unknown',
                         cognition: this.options.cognition ?? 'fsm',
                         metrics: result.metrics,
-                        ...workScopeFromWake(event, session.sessionId),
+                        ...marks.scope,
                     });
                 }
                 catch (err) {
@@ -934,6 +1030,14 @@ export class Agent {
                 this.unmetTasksPendingAsk.delete(laneKey);
                 this.askedForAccessLanes.delete(laneKey);
             }
+            // The poll can return the row just written by this wake. Only suppress
+            // that exact version while this lane has an explicit future wake: a
+            // successful but unfinished turn still needs the task poll to recover
+            // when it did not schedule its own continuation.
+            if (this.stateTimers.peek(laneKey)?.kind === 'wake-at') {
+                for (const version of marks.planVersions)
+                    this.confirmedPlanVersions.mark(JSON.stringify([laneKey, version]));
+            }
         }
         catch (err) {
             this.recordWakeOutcome(session, {
@@ -992,17 +1096,26 @@ export class Agent {
             sessionId: record.sessionId,
             laneKey: record.laneKey || record.sessionId,
         };
+        // The host's own answer comes first, exactly as it does live. A replay that
+        // skipped this would report a model turn the host would never have spent,
+        // which is the opposite of what a recording is for.
+        const suppressed = await this.wakeSuppression(record.event, record.sessionId);
+        if (suppressed) {
+            runtimeLog.info(this.options.name || 'agent', `replay: no wake on ${record.sessionId} — ${suppressed.because}`);
+            return { state: record.state };
+        }
         const memory = this.memoryForWake({
             sessionId: record.sessionId,
             ctx: record.ctx,
-        });
+        }, record.event);
         // Same watchdog as a live wake, for the same reason: an unaborted Claude
         // query outlives the promise that abandoned it and keeps spending.
         const abort = new AbortController();
+        const marks = WakeEffects.forWake(record.event, identity.sessionId);
         let watchdog;
         try {
             const result = await Promise.race([
-                this.brain.tick({
+                this.wakeEffects.run(marks, () => this.brain.tick({
                     event: record.event,
                     ctx: record.ctx,
                     state: record.state,
@@ -1011,7 +1124,7 @@ export class Agent {
                     memory,
                     transitionTap: this.options.transitionTap,
                     signal: abort.signal,
-                }),
+                })),
                 new Promise((_, reject) => {
                     watchdog = setTimeout(() => {
                         abort.abort(new Error('tick timeout'));
@@ -1027,7 +1140,7 @@ export class Agent {
                         model: this.options.model ?? 'unknown',
                         cognition: this.options.cognition ?? 'fsm',
                         metrics: result.metrics,
-                        ...workScopeFromWake(record.event, identity.sessionId),
+                        ...marks.scope,
                     });
                 }
                 catch (err) {
@@ -1091,7 +1204,7 @@ export class Agent {
                 // the agent assigned to itself.
                 onTask: async (task) => {
                     try {
-                        await this.wakeTaskAssignment(task.taskId);
+                        await this.wakeTaskAssignment(task.taskId, { fromInbox: true });
                     }
                     catch (err) {
                         runtimeLog.warn(this.options.name || 'agent', `inbox task ${task.taskId} could not be woken: ${err.message}`);
@@ -1129,7 +1242,7 @@ export class Agent {
         });
     }
     /** replay task-assigned for an existing active task (demo recovery). */
-    async wakeTaskAssignment(taskId) {
+    async wakeTaskAssignment(taskId, options) {
         const agentId = this.options.agentId;
         if (!agentId || !this.taskService) {
             throw new Error('wakeTaskAssignment: agent not configured');
@@ -1146,6 +1259,7 @@ export class Agent {
         }
         await this.eventQueue.enqueue({
             type: 'task_result',
+            ...(options?.fromInbox ? { source: 'active-task-snapshot' } : {}),
             result: {
                 ...full,
                 taskId: full.taskId ?? taskId,
@@ -1159,8 +1273,9 @@ export class Agent {
         this.started = false;
         this.pollRunner?.stop();
         this.stateTimers.clearAll();
-        void this.inboxLoop?.stop();
+        const stopping = this.inboxLoop?.stop() ?? Promise.resolve();
         this.inboxLoop = null;
+        return stopping;
     }
     /**
      * Waits for in-flight ticks to finish. Call before process.exit() on SIGTERM.

package/dist/brain/ClaudeBrain.d.ts

@@ -49,6 +49,14 @@ export interface ClaudeBrainOptions {
     statelessPerWake?: boolean;
     /** Injectable for tests. Defaults to @anthropic-ai/claude-agent-sdk query(). */
     queryFn?: typeof query;
+    /** Full authoritative agreement read used to recognize listing bookkeeping. */
+    readAgreement?: (agreementId: string) => Promise<unknown>;
+    /**
+     * Opt in to spending a model turn on an activation notice for a hire
+     * this agent's counterparty formed. Default is off — the host records a
+     * no-op and waits for the task.
+     */
+    actsOnHireActivation?: boolean;
 }
 /**
  * "the transcript you asked me to resume is not here".
@@ -90,6 +98,8 @@ export declare class ClaudeBrain implements Brain {
     private maxTurns;
     private statelessPerWake;
     private queryFn;
+    private readAgreement;
+    private actsOnHireActivation;
     /**
      * Per-lane tool context. One agent object serves every room, and a
      * wake's query can still be running when another lane starts. A single
@@ -100,5 +110,5 @@ export declare class ClaudeBrain implements Brain {
     private toolContextByLane;
     private sdkMcpByLane;
     constructor(opts: ClaudeBrainOptions);
-    tick({ event, ctx, state, identity, eff, signal }: TickInput): Promise<TickOutput>;
+    tick({ event, ctx, state, identity, eff, memory, signal }: TickInput): Promise<TickOutput>;
 }