@hearsay-tools/squawk 0.0.0-stage → 0.17.0-dev.5682

package/dist/delegation/service.js

@@ -0,0 +1,807 @@
+import { commandText } from '../home/command.js';
+import { WAIT_KINDS } from '../workflows/run/wait-kinds.js';
+import { projectPaths } from '../project-paths.js';
+import { assertReplyDirection, sendRequestContext, sendAdmission, sendMessage, sendInput } from './conversation-send.js';
+import { discoverTasks } from './task-discovery.js';
+import { discoveredRunners, missingModelChoices } from '../discovery/catalog.js';
+import { assertConversationCapacity, assertFamilySender, byCreatedAtAndId, commitAccepted, familyPair, inboxEntryIn, orphanedPeerMessage, peerPair, takesPart, projectConversationEvents, reconcileConversationState, replyOutcomes } from './conversations.js';
+export { rootDelegation } from './conversations.js';
+import { collectWorkerEvidence, revalidateRetainedWorkerResult, workerRevision } from './results.js';
+import { prepareWorkerContext, workerContextTask } from './context.js';
+import { acceptedWorkerIdentitySchema, workerContextHash, workerWorkflowHash } from './execution-identity.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { discoveryRequestSchema, } from '../contract/index.js';
+import { CONVERSATION_PAGE_MESSAGES, conversationSendEffectSchema, decodeConversationCursor, encodeConversationCursor, conversationSendRequestSchema, conversationInspectRequestSchema, conversationCancelRequestSchema, inboxReceiptRequestSchema, requestWaitRequestSchema, } from '../contract/index.js';
+import { workerSpawnRequestSchema, workerSteerRequestSchema, workerWaitRequestSchema, peerWaitRequestSchema, workerParamsSchema, workerCancelWaitRequestSchema, } from '../contract/index.js';
+import { messagingAllowed } from '../contract/index.js';
+import { completionWaitEntry, peerWaitView, workerCompletionWaitProjection, workerWaitEntryToLegacy } from '../contract/index.js';
+import { assertConversationIdFree, ConversationIdInUseError } from '../runs/conversation-identity.js';
+import { workerDestroyView, workerOutcome } from '../runs/delegation-state.js';
+import { QUICK_TASK_WORKFLOW, skillTaskSteps, plannedWorkflow, allowedToolsForStep, stepKind } from '../workflows/types.js';
+import { discoverSkills } from '../skills.js';
+import { findWorkflow } from '../workflows/load.js';
+import { isAuthenticatedCaller } from './credentials.js';
+import { parseDelegationEffort } from './effort.js';
+import { authorizeWorkerList, authorizeSpawn, authorizeSpawnReplay, authorizeWorker, authorizeCancelWait, authorizeRetainedResult, DelegationPolicyError, MESSAGING_OFF, requireWorkersAllowed } from './policy.js';
+import { planOwnedWorkspace, readOwnedDiff, resolveWorkerBaseline } from './workspace.js';
+import { WorkerCleanup } from './worker-cleanup.js';
+/**
+ * Resolve an explicit workflow or skill. With neither, use the built-in quick-task constant, not
+ * a repo override. Require at least one agent step and resolve its runner/account independently.
+ */
+async function resolveSpawnWorkflow(project, request) {
+    const root = project.root;
+    if (request.skill !== undefined) {
+        const skills = await discoverSkills(root, { builtin: project.manager.builtinSkills?.() ?? [] }, project.home);
+        if (!skills.some(skill => skill.name === request.skill))
+            throw new DelegationPolicyError('invalid_input', `Unknown skill "${request.skill}"; available: ${skills.map(skill => skill.name).join(', ')}`);
+        return plannedWorkflow(skillTaskSteps(request.skill));
+    }
+    if (request.workflow === undefined)
+        return QUICK_TASK_WORKFLOW;
+    const workflow = await findWorkflow(root, request.workflow);
+    if (!workflow)
+        throw new DelegationPolicyError('invalid_input', `Unknown workflow "${request.workflow}"; the catalog holds the built-in quick-task and .ai/cezar/workflows/*.yaml`);
+    if (!workflow.steps.some(step => stepKind(step) === 'agent'))
+        throw new DelegationPolicyError('invalid_input', `Workflow "${request.workflow}" has no agent step for a worker to run`);
+    return workflow;
+}
+/**
+ * Intersect authored step grants with parent grants. Unset step grants inherit; unset parent
+ * tools use the runner default and unset Bash rules mean unrestricted Bash. Native enforcement
+ * remains runner-specific.
+ */
+function narrowGrants(parent, step, runner) {
+    const parentTools = step.allowedTools === undefined ? parent.allowedTools : parent.allowedTools ?? allowedToolsForStep(undefined, runner);
+    const allowedTools = step.allowedTools === undefined ? parent.allowedTools : step.allowedTools.filter(tool => parentTools.includes(tool));
+    const bashAllowlist = step.bashAllowlist === undefined ? parent.bashAllowlist
+        : parent.bashAllowlist === undefined ? [...step.bashAllowlist] : step.bashAllowlist.filter(command => parent.bashAllowlist.includes(command));
+    return { ...(allowedTools === undefined ? {} : { allowedTools: [...allowedTools] }), ...(bashAllowlist === undefined ? {} : { bashAllowlist: [...bashAllowlist] }) };
+}
+/**
+ * Resolve each agent step before acceptance. Step choices override spawn defaults; equal
+ * selections share resolution. Bind account, runner, model, effort and narrowed grants together.
+ */
+async function resolveSpawnSteps(manager, parentId, request, workflow, validateModel) {
+    const cache = new Map();
+    const resolved = [];
+    for (const step of workflow.steps) {
+        if (stepKind(step) === 'check')
+            continue;
+        const selection = {
+            ...(step.runner ?? request.backend) === undefined ? {} : { backend: step.runner ?? request.backend },
+            ...(step.model ?? request.model) === undefined ? {} : { model: step.model ?? request.model },
+            ...(step.effort ?? request.effort) === undefined ? {} : { effort: step.effort ?? request.effort },
+            ...(step.agentProfile === undefined ? {} : { agentProfile: step.agentProfile }),
+        };
+        const key = JSON.stringify(selection);
+        let pending = cache.get(key);
+        if (!pending) {
+            pending = manager.selectDelegationExecutionSettings(parentId, selection, settings => validateModel(step, settings));
+            cache.set(key, pending);
+        }
+        const settings = await pending;
+        resolved.push({ step, settings, grants: narrowGrants({ ...(settings.allowedTools === undefined ? {} : { allowedTools: settings.allowedTools }),
+                ...(settings.bashAllowlist === undefined ? {} : { bashAllowlist: settings.bashAllowlist }) }, step, settings.runner) });
+    }
+    return resolved;
+}
+function stepIdentityFields({ settings, grants }) {
+    return { account: settings.accountBinding, grants, ...(settings.model === undefined ? {} : { model: settings.model }), ...(settings.effort === undefined ? {} : { effort: settings.effort }) };
+}
+function spawnRequestHash(request) {
+    const effortPin = parseDelegationEffort(request.effort);
+    return createHash('sha256').update(JSON.stringify({ task: request.task, baseline: request.baseline,
+        ...(request.context === undefined ? {} : { context: request.context }),
+        ...(request.backend === undefined ? {} : { backend: request.backend }),
+        ...(request.model === undefined ? {} : { model: request.model }),
+        ...(effortPin === undefined ? {} : { effort: effortPin }),
+        ...(request.workflow === undefined ? {} : { workflow: request.workflow }),
+        ...(request.skill === undefined ? {} : { skill: request.skill }),
+    })).digest('hex');
+}
+function replayedSpawn(project, parent, requestId, requestHash) {
+    if (parent.delegation?.role !== 'root')
+        return;
+    const receipt = parent.delegation.receipts.find(r => r.requestId === requestId);
+    if (!receipt)
+        return;
+    if (receipt.requestHash !== requestHash)
+        throw new DelegationPolicyError('invalid_input', 'Request ID payload conflict');
+    const worker = project.store.getRun(receipt.workerId);
+    if (worker?.delegation?.role !== 'worker' || worker.delegation.parentRunId !== parent.id || worker.delegation.workspace.ownerRunId !== worker.id)
+        throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+    return { workerId: worker.id, baselineSha: worker.delegation.workspace.baselineSha };
+}
+/** The public definition carries what each agent step RESOLVED to — runner, account,
+ *  model, effort and the narrowed grants — so the bound `workflowDef` and the private
+ *  per-step identity describe the same launch and the manager can hold them against each
+ *  other. Check steps run as authored. */
+function boundSpawnWorkflow(catalog, resolvedSteps) {
+    return { ...catalog, steps: catalog.steps.map(step => {
+            const entry = resolvedSteps.find(candidate => candidate.step === step);
+            if (!entry)
+                return step;
+            const { model: _model, effort: _effort, allowedTools: _tools, bashAllowlist: _bash, ...authored } = step;
+            return { ...authored, runner: entry.settings.runner, agentProfile: entry.settings.accountBinding.profileId,
+                ...(entry.settings.model === undefined ? {} : { model: entry.settings.model }),
+                ...(entry.settings.effort === undefined ? {} : { effort: entry.settings.effort }),
+                ...entry.grants };
+        }) };
+}
+async function acceptSpawnedWorker(args) {
+    const { project, parent, request, catalog, resolvedSteps, settings, identity, workspace, baselineSha, requestHash, prepared, caller } = args;
+    const context = prepared?.recipe;
+    let accepted = false;
+    try {
+        // Ref resolution yields to Finish, revocation and project disposal; recheck before acceptance.
+        if (args.current() !== project)
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        authorizeSpawn(caller, project.store.getRun(parent.id), project.id, id => project.store.getRun(id));
+        const workflowDef = boundSpawnWorkflow(catalog, resolvedSteps);
+        const worker = project.store.createOwnedRun({
+            title: request.task.slice(0, 200), task: context ? workerContextTask(request.task, context) : request.task, workflow: workflowDef.name,
+            runner: settings.runner, model: settings.model, effort: settings.effort, agentProfile: identity.account.profileId,
+            systemPrompt: settings.systemPrompt, workflowDef,
+            autonomous: parent.autonomous,
+            steps: workflowDef.steps.map(step => ({ id: step.id, name: step.name ?? step.id, kind: stepKind(step) })),
+        }, parent.id, request.requestId, { role: 'worker', permissions: [], parentRunId: parent.id, workspace, ...(context ? { context } : {}) }, requestHash, {
+            ...identity, ...(context ? { contextHash: workerContextHash(context) } : {}),
+            // A named catalog chain or skill is bound like the context recipe; the default quick-task leaves the identity as before.
+            ...(request.workflow === undefined && request.skill === undefined ? {} : { workflowHash: workerWorkflowHash(workflowDef) }),
+        });
+        accepted = true;
+        project.manager.enqueueOwnedRun(worker.id);
+        return { workerId: worker.id, baselineSha };
+    }
+    finally {
+        if (!accepted)
+            await prepared?.discard();
+    }
+}
+/** Messaging off refuses new peer sends (hearsay-tools/cezarion#2784). Called after an exact retry of
+ *  an accepted message has returned; a reply to a request accepted earlier still passes. */
+function assertNewPeerSend(pair, request) {
+    if (pair.relationship === 'peer' && request.kind !== 'reply' && !messagingAllowed(pair.sender))
+        throw new DelegationPolicyError('incompatible_state', MESSAGING_OFF);
+}
+/** A single controller's shared policy adapter; managers retain scheduling and lifecycle ownership. */
+export class DelegationService {
+    cleanupOptions;
+    discovery;
+    setDiscovery(discovery) { this.discovery = discovery; }
+    async discover(caller, value) {
+        const project = this.context(caller);
+        const request = discoveryRequestSchema.parse(value);
+        if (request.kind === 'tasks')
+            return discoverTasks(project.store, caller.runId, request);
+        // Discovery accompanies spawn authority, including roots persisted before this command existed.
+        const callerRun = project.store.getRun(caller.runId);
+        authorizeSpawnReplay(caller, callerRun, project.id);
+        requireWorkersAllowed(callerRun);
+        if (!this.discovery)
+            throw new DelegationPolicyError('unavailable_transport', 'Host discovery is unavailable');
+        return request.kind === 'models' ? this.discovery.models.get(request.runner) : discoveredRunners(await this.discovery.providers());
+    }
+    async validateModels(request, resolved) {
+        if (!this.discovery)
+            return;
+        const checked = new Set();
+        for (const { step, settings } of resolved) {
+            // The host catalog says nothing authoritative about a different named account.
+            if (settings.accountBinding?.profileId !== 'default')
+                continue;
+            const model = (step.model ?? request.model)?.trim();
+            if (!model)
+                continue; // Inherited/default models keep their existing resolution path.
+            const runner = settings.runner;
+            const key = JSON.stringify([runner, model]);
+            if (checked.has(key))
+                continue;
+            checked.add(key);
+            const choices = await missingModelChoices(this.discovery, runner, model, settings.model, settings.modelIdentity);
+            if (!choices)
+                continue;
+            const alternatives = choices.otherRunners.join(', ') || 'none';
+            const available = choices.availableModels.map(row => `${row.id}${row.effortLevels ? ` (effort: ${row.effortLevels.join(', ') || 'none advertised'})` : ''}`).join('; ');
+            // Full choices remain structured even when the human-readable error reaches its bound.
+            throw new DelegationPolicyError('invalid_input', `Model "${model}" is not in the ${runner} catalog. Available models: ${available.slice(0, 1200)}. Other runners listing "${model}": ${alternatives}. ${commandText(`Use cez discover models --runner=${runner}.`)}`, choices);
+        }
+    }
+    projects = new Map();
+    serial = new Map();
+    cleanups = new Map();
+    constructor(cleanupOptions = {}) {
+        this.cleanupOptions = cleanupOptions;
+    }
+    registerProject(project) {
+        const existing = this.projects.get(project.id);
+        if (existing?.store === project.store && existing.manager === project.manager)
+            return () => { };
+        this.cleanups.get(project.id)?.detach();
+        existing?.manager.pauseWorkerCleanup();
+        this.projects.set(project.id, project);
+        this.cleanups.set(project.id, new WorkerCleanup(project, () => this.projects.get(project.id) === project, (key, operation) => this.serialized(key, operation), this.cleanupOptions));
+        return () => { if (this.projects.get(project.id) === project) {
+            this.cleanups.get(project.id)?.detach();
+            project.manager.pauseWorkerCleanup();
+            this.projects.delete(project.id);
+            this.cleanups.delete(project.id);
+        } };
+    }
+    /** Called only after manager recovery, when persisted destroy intents may be retried. */
+    armDestroyRetries(projectId) { this.cleanups.get(projectId)?.armAfterRecovery(); }
+    /** The data directory of the caller's project, for the listener's migration admission. */
+    projectDataDir(caller) {
+        const project = isAuthenticatedCaller(caller) ? this.projects.get(caller.projectId) : undefined;
+        return project ? projectPaths(project.root).write : undefined;
+    }
+    context(caller) {
+        const project = isAuthenticatedCaller(caller) ? this.projects.get(caller.projectId) : undefined;
+        if (!project)
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        return project;
+    }
+    async serialized(key, operation) {
+        const previous = this.serial.get(key) ?? Promise.resolve();
+        const next = previous.catch(() => { }).then(operation);
+        this.serial.set(key, next);
+        try {
+            return await next;
+        }
+        finally {
+            if (this.serial.get(key) === next)
+                this.serial.delete(key);
+        }
+    }
+    target(caller, params, operation) {
+        const project = this.context(caller);
+        const { workerId } = workerParamsSchema.parse(params);
+        const parent = project.store.getRun(caller.runId);
+        const worker = project.store.getRun(workerId);
+        authorizeWorker(caller, worker, operation, parent, project.id);
+        return { project, parent: parent, worker: worker };
+    }
+    /**
+     * The relationship resolver (spec 2026-10-27-task-communication-protocol § 2): `family` for a
+     * root and its direct owned worker, `peer` for two root tasks of the caller's project, and
+     * `denied_scope` with one text for everything else. `send` asks for the live pair a new message
+     * needs; without it the pair is checked for reading. A peer's own durable records (history, its
+     * requests, its inbox) are read through `peerRecords` instead, which a deleted peer does not block.
+     */
+    conversationPair(caller, recipientRunId, send = false) {
+        const project = this.context(caller);
+        const sender = project.store.getRun(caller.runId);
+        const recipient = project.store.getRun(recipientRunId);
+        const peer = peerPair(sender, recipient, send);
+        if (peer)
+            return { project, ...peer };
+        const { root, worker } = familyPair(sender, recipient);
+        assertFamilySender(sender, root, send);
+        return { project, relationship: 'family', sender: sender, recipient: recipient, root, worker };
+    }
+    /** The caller's own peer records need only its participation: a root task whose own history is
+     *  not being deleted. The record read names the counterpart; a deleted peer does not block it. */
+    peerRecords(caller) {
+        const project = this.context(caller);
+        const self = project.store.getRun(caller.runId);
+        if (self?.delegation?.role !== 'root' || self.delegation.historyDeletion)
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        return { project, self };
+    }
+    /** The ledger a new message lands in (spec § 2, Which ledger holds a message): a new request or
+     *  progress message in the sender's family ledger, a follow-up or reply with the request it names. */
+    ledgerFor(pair, request) {
+        if (pair.relationship === 'family')
+            return pair.root;
+        const ledger = request.kind === 'reply' ? pair.recipient : pair.sender;
+        // A peer that never opened a session has no ledger, so it holds no request to reply to.
+        if (ledger.delegation?.role !== 'root')
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        return ledger;
+    }
+    currentConversation(project, root) {
+        // A ledger whose history is being deleted is read as it stands: reconciliation would write to it.
+        if (root.delegation?.role === 'root' && root.delegation.historyDeletion)
+            return root.delegation.conversation ?? { messages: [], outcomes: [] };
+        const state = reconcileConversationState(root, (id) => project.store.getRun(id), new Date().toISOString(), run => run.delegation?.role === 'worker'
+            ? project.store.readWorkerExecution(run.id)?.phase === 'complete' : !project.manager.isActive(run.id), id => project.store.isUnreadable(id));
+        if (root.delegation?.role === 'root' && state && state !== root.delegation.conversation)
+            project.store.commitConversation(root.id, state);
+        return state ?? { messages: [], outcomes: [] };
+    }
+    conversationReceipt(project, ledgerId, message) {
+        const recipient = project.store.getRun(message.recipientRunId);
+        const input = recipient?.agentInputs?.find(input => input.id === message.id);
+        const ledger = project.store.getRun(ledgerId);
+        const state = ledger?.delegation?.role === 'root' ? ledger.delegation.conversation : undefined;
+        const outcome = state?.outcomes.find(outcome => outcome.requestId === (message.requestId ?? message.id));
+        return { message, delivery: input?.consumedAt ? 'consumed' : input?.deliveredAt ? 'delivered' : input ? 'queued' : 'not-delivered', ...(outcome ? { outcome } : {}) };
+    }
+    async send(caller, value) {
+        const request = conversationSendRequestSchema.parse(value);
+        const initial = this.conversationPair(caller, request.recipientRunId, true);
+        return this.serialized(`conversation:${initial.project.id}:${this.ledgerFor(initial, request).id}`, async () => {
+            return this.sendLocked(caller, request);
+        });
+    }
+    /** Runs entirely under the ledger lock; mutable records are read at the queue head. */
+    sendLocked(caller, request) {
+        const pair = this.conversationPair(caller, request.recipientRunId, true);
+        const { project, sender, recipient } = pair;
+        const root = this.ledgerFor(pair, request);
+        this.assertSendScope(pair, root, request);
+        if (pair.relationship === 'peer' && sender.delegation?.role === 'root')
+            assertReplyDirection(sender.delegation.conversation ?? { messages: [], outcomes: [] }, request, sender, recipient);
+        const requestHash = createHash('sha256').update(JSON.stringify({ senderRunId: sender.id, ...request })).digest('hex');
+        const state = this.currentConversation(project, root);
+        const existing = state.messages.find(message => message.id === request.id);
+        if (existing)
+            return this.retrySend(pair, root, existing, requestHash);
+        assertNewPeerSend(pair, request);
+        const { original, settled } = sendRequestContext(state, request, sender, recipient);
+        const now = new Date().toISOString();
+        const { destroyed, resumable, resume, instruction } = sendAdmission(pair, root, request);
+        // A new continuation is new worker work: the parent's switch gates it (hearsay-tools/cezarion#2784).
+        if (resume)
+            requireWorkersAllowed(root);
+        const message = sendMessage(pair, request, requestHash, now, settled, { destroyed, resumable, resume, instruction });
+        const enqueue = !destroyed && (!resumable || resume);
+        // Open worker questions reserve ledger room for their replies (hearsay-tools/cezarion#505); the reply spends its
+        // own. The reply is also always admitted to the worker's inbox, one past its soft 32-input
+        // bound: while the question is pending nothing else there can drain, and a worker has at
+        // most one pending question, so this admits at most one extra input.
+        const answering = request.kind === 'reply' && !settled && !!original?.question;
+        // An answer the worker can no longer receive (stopping, stopped, destroyed) would record
+        // the question as replied while nothing delivers it; the human answers it instead.
+        if (answering && !enqueue)
+            throw new DelegationPolicyError('incompatible_state', 'The worker can no longer receive this answer; its question goes back to the human');
+        assertConversationCapacity(state, pair, request.kind, enqueue, request.kind === 'reply' && !settled, answering);
+        const outcomes = replyOutcomes(state, request, settled, now);
+        const input = sendInput(pair, root, message, requestHash, now);
+        const next = { messages: [...state.messages, message], outcomes };
+        this.commitSend(pair, root, next, input, resume, enqueue);
+        try {
+            projectConversationEvents(project.store, project.store.getRun(root.id));
+            project.manager.reconcileWorkerWaits();
+            if (enqueue)
+                project.manager.deliverConversationInput(recipient.id);
+        }
+        catch {
+            // The ledger and input already committed. Preserve their receipt; an exact retry repairs delivery.
+        }
+        return { ...this.conversationReceipt(project, root.id, message), effect: enqueue ? conversationSendEffectSchema.enum.applied : conversationSendEffectSchema.enum.refused };
+    }
+    assertSendScope(pair, root, request) {
+        const { project, sender, recipient, relationship } = pair;
+        const peer = relationship === 'peer';
+        if (request.resume && (peer || sender.id !== root.id || recipient.delegation?.role !== 'worker')) {
+            throw new DelegationPolicyError('denied_scope', 'Only an active parent may use --resume for its owned worker');
+        }
+        if (project.store.containsSessionSecret(JSON.stringify(request)))
+            throw new DelegationPolicyError('invalid_input', 'Credentials cannot be included in delegated input');
+    }
+    retrySend(pair, root, existing, requestHash) {
+        const { project, recipient } = pair;
+        if (existing.requestHash !== requestHash)
+            throw new DelegationPolicyError('invalid_input', 'Message ID payload conflict');
+        try {
+            projectConversationEvents(project.store, project.store.getRun(root.id));
+            project.manager.reconcileWorkerWaits();
+            if (recipient.agentInputs?.some(input => input.id === existing.id && !input.deliveredAt))
+                project.manager.deliverConversationInput(recipient.id);
+        }
+        catch {
+            // Repair cannot revoke the stored receipt or turn an exact retry into a new send.
+        }
+        return { ...this.conversationReceipt(project, root.id, existing), effect: conversationSendEffectSchema.enum.unchanged };
+    }
+    commitSend(pair, root, next, input, resume, enqueue) {
+        const { project, recipient, relationship } = pair;
+        const peer = relationship === 'peer';
+        if (resume) {
+            try {
+                assertConversationIdFree(root, input, id => project.store.getRun(id), (runId, id) => project.store.hasProjection(runId, id));
+            }
+            catch (error) {
+                if (error instanceof ConversationIdInUseError)
+                    throw new DelegationPolicyError('invalid_input', error.message);
+                throw error;
+            }
+            const result = project.manager.continueRun(recipient.id, {
+                text: `Your parent resumed this worker with a new instruction.\nAgent conversation ${JSON.stringify({ id: input.id, ...input.conversation })}\n${input.text}`,
+            }, true, { rootId: root.id, state: next, input });
+            if (!result.ok)
+                throw new DelegationPolicyError('incompatible_state', `Worker was not resumed: ${result.error}. No message was accepted; resolve this condition and retry the same command`);
+        }
+        else
+            commitAccepted(project.store, root.id, next, enqueue ? input : undefined, peer && !recipient.delegation);
+    }
+    async followUp(caller, value) {
+        if (value.kind !== 'follow-up')
+            throw new DelegationPolicyError('invalid_input', 'Expected follow-up');
+        return this.send(caller, value);
+    }
+    async reply(caller, value) {
+        if (value.kind !== 'reply')
+            throw new DelegationPolicyError('invalid_input', 'Expected reply');
+        return this.send(caller, value);
+    }
+    /**
+     * One pair's history. A family pair reads its one ledger; a peer pair reads both roots' ledgers
+     * and merges them in `(createdAt, id)` order, newest `CONVERSATION_PAGE_MESSAGES` first, with
+     * `nextBefore` when older messages exist (spec § 2). A deleted peer leaves the caller's ledger.
+     */
+    async conversation(caller, value) {
+        const request = conversationInspectRequestSchema.parse(value);
+        const { project, ledgers, self, other } = this.historyLedgers(caller, request.recipientRunId);
+        const between = (message) => { return (message.senderRunId === self && message.recipientRunId === other) || (message.senderRunId === other && message.recipientRunId === self); };
+        const states = ledgers.map(ledger => {
+            const state = this.currentConversation(project, ledger);
+            projectConversationEvents(project.store, project.store.getRun(ledger.id) ?? ledger);
+            return state;
+        });
+        const before = request.before === undefined ? undefined : decodeConversationCursor(request.before);
+        const merged = states.flatMap(state => state.messages.filter(between)).sort(byCreatedAtAndId)
+            .filter(message => !before || byCreatedAtAndId(message, before) < 0);
+        const messages = merged.slice(-CONVERSATION_PAGE_MESSAGES);
+        const ids = new Set(messages.map(message => message.id));
+        const outcomes = states.flatMap(state => state.outcomes.filter(outcome => ids.has(outcome.requestId)));
+        const inputs = project.store.getRun(caller.runId)?.agentInputs ?? [];
+        const unread = messages.some(message => message.recipientRunId === caller.runId &&
+            inputs.some(input => input.id === message.id && !input.deliveredAt));
+        return { messages, outcomes,
+            ...(merged.length > messages.length ? { nextBefore: encodeConversationCursor(messages[0]) } : {}),
+            ...(unread ? { hint: commandText('This history includes unread messages. Run cez message inbox to receive and mark them delivered. Inbox will show them again intentionally; after acknowledgement, Cezar will not queue them again for normal end-of-turn delivery.') } : {}) };
+    }
+    /** The ledgers a history read covers: the family's one, or each peer root's own while it exists.
+     *  A peer whose history is being deleted, or is deleted, stays readable to a participant (spec § 2). */
+    historyLedgers(caller, otherId) {
+        let pair;
+        try {
+            pair = this.conversationPair(caller, otherId);
+        }
+        catch (error) {
+            if (!(error instanceof DelegationPolicyError) || error.code !== 'denied_scope')
+                throw error;
+        }
+        if (pair?.relationship === 'family')
+            return { project: pair.project, ledgers: [pair.root], self: caller.runId, other: otherId };
+        const { project, self } = this.peerRecords(caller);
+        const other = project.store.getRun(otherId);
+        if (!pair && !takesPart(self, other, otherId))
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        return { project, ledgers: [self, ...(other?.delegation?.role === 'root' ? [other] : [])], self: self.id, other: otherId };
+    }
+    async inbox(caller) {
+        const project = this.context(caller);
+        const run = project.store.getRun(caller.runId);
+        if (!run || (run.delegation?.role !== 'root' && run.delegation?.role !== 'worker'))
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        const selected = [];
+        let characters = 0;
+        const states = new Map();
+        const ledgerState = (ledger) => {
+            let state = states.get(ledger.id);
+            if (!state) {
+                state = this.currentConversation(project, ledger);
+                states.set(ledger.id, state);
+            }
+            return state;
+        };
+        for (const input of run.agentInputs ?? []) {
+            if (!input.conversation || input.conversation.recipientRunId !== run.id || !project.manager.canClaimInboxInput(run.id, input.id))
+                continue;
+            const found = input.conversation.relationship === 'peer' ? this.peerInboxEntry(project, run, input, ledgerState) : this.familyInboxEntry(caller, run, input, ledgerState);
+            if (!found)
+                continue;
+            if (selected.length >= 32 || (selected.length > 0 && characters + found.message.text.length > 100_000))
+                break;
+            characters += found.message.text.length;
+            selected.push(found);
+        }
+        if (!selected.length)
+            return { messages: [], outcomes: [] };
+        const receipt = project.manager.reserveInboxInputs(run.id, caller.generation, selected.map(entry => entry.message.id));
+        if (!receipt)
+            return { messages: [], outcomes: [] };
+        const claimed = new Set(receipt.inputIds);
+        const returned = selected.filter(entry => claimed.has(entry.message.id));
+        if (!returned.length)
+            throw new DelegationPolicyError('incompatible_state', 'Inbox claim returned no messages');
+        const outcomes = [...new Map(returned.flatMap(entry => entry.outcome ? [[entry.outcome.requestId, entry.outcome]] : [])).values()];
+        return { messages: returned.map(entry => entry.message), outcomes,
+            receiptId: receipt.receiptId, expiresAt: receipt.expiresAt };
+    }
+    /** A peer input addressed to the caller: its participation is the whole check (spec § 2, two
+     *  levels). When the sender's ledger went with its deletion, the input still carries the message. */
+    peerInboxEntry(project, run, input, ledgerState) {
+        if (run.delegation?.role !== 'root')
+            return undefined;
+        const ledger = project.store.getRun(input.parentRunId);
+        if (!ledger) {
+            const message = orphanedPeerMessage(input);
+            return message && { message };
+        }
+        return ledger.delegation?.role === 'root' ? inboxEntryIn(ledgerState(ledger), input, run.id) : undefined;
+    }
+    /** A family input: the pair must still be admitted, as before peers existed. */
+    familyInboxEntry(caller, run, input, ledgerState) {
+        let pair;
+        try {
+            pair = this.conversationPair(caller, input.conversation.senderRunId);
+        }
+        catch (error) {
+            if (error instanceof DelegationPolicyError && error.code === 'denied_scope')
+                return undefined;
+            throw error;
+        }
+        return pair.relationship === 'family' ? inboxEntryIn(ledgerState(pair.root), input, run.id) : undefined;
+    }
+    inboxReceipt(caller, value) {
+        const { receiptId } = inboxReceiptRequestSchema.parse(value);
+        const project = this.context(caller);
+        const run = project.store.getRun(caller.runId);
+        const members = run?.agentInputs?.filter(input => input.inboxClaim?.receiptId === receiptId && input.inboxClaim.generation === caller.generation) ?? [];
+        if (!members.length || members.some(input => !input.conversation || input.conversation.recipientRunId !== caller.runId))
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        // A peer member is checked against the caller's own record only: a sender deleted between
+        // reserve and acknowledge does not refuse the batch (spec § 2).
+        for (const input of members) {
+            if (input.conversation.relationship === 'peer')
+                this.peerRecords(caller);
+            else
+                this.conversationPair(caller, input.conversation.senderRunId);
+        }
+        return { project, receiptId };
+    }
+    async ackInbox(caller, value) {
+        const { project, receiptId } = this.inboxReceipt(caller, value);
+        try {
+            return { receiptId, status: project.manager.acknowledgeInbox(caller.runId, caller.generation, receiptId) };
+        }
+        catch {
+            throw new DelegationPolicyError('incompatible_state', 'Inbox acknowledgement failed; retry the same receipt while it remains live');
+        }
+    }
+    async releaseInbox(caller, value) {
+        const { project, receiptId } = this.inboxReceipt(caller, value);
+        try {
+            return { receiptId, status: project.manager.releaseInbox(caller.runId, caller.generation, receiptId) };
+        }
+        catch {
+            throw new DelegationPolicyError('incompatible_state', 'Inbox release failed');
+        }
+    }
+    /** A request the caller sent, from its family ledger. A peer request needs only the caller's own
+     *  record: wait and cancel still work after the peer's deletion (spec § 2). */
+    ownRequest(caller, requestId) {
+        const project = this.context(caller);
+        const sender = project.store.getRun(caller.runId);
+        const root = sender?.delegation?.role === 'root' ? sender : sender?.delegation?.role === 'worker' ? project.store.getRun(sender.delegation.parentRunId) : undefined;
+        const message = root?.delegation?.role === 'root' ? root.delegation.conversation?.messages.find(message => message.id === requestId && message.kind === 'request' && message.state === 'accepted' && message.senderRunId === caller.runId) : undefined;
+        if (!message)
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        if (message.relationship === 'peer')
+            return { ...this.peerRecords(caller), root: root, message };
+        const pair = this.conversationPair(caller, message.recipientRunId);
+        if (pair.relationship !== 'family')
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        return { project: pair.project, root: pair.root, message };
+    }
+    async cancelRequest(caller, value) {
+        const { requestId } = conversationCancelRequestSchema.parse(value);
+        const { project, root } = this.ownRequest(caller, requestId);
+        const state = this.currentConversation(project, root);
+        const existing = state.outcomes.find(outcome => outcome.requestId === requestId);
+        if (existing) {
+            projectConversationEvents(project.store, project.store.getRun(root.id));
+            project.manager.reconcileWorkerWaits();
+            return existing;
+        }
+        const outcome = { requestId, status: 'cancelled', observedAt: new Date().toISOString() };
+        project.store.commitConversation(root.id, { ...state, outcomes: [...state.outcomes, outcome] });
+        projectConversationEvents(project.store, project.store.getRun(root.id));
+        project.manager.reconcileWorkerWaits();
+        return outcome;
+    }
+    async waitRequests(caller, value) {
+        const request = requestWaitRequestSchema.parse(value);
+        for (const id of request.requestIds)
+            this.ownRequest(caller, id);
+        const project = this.context(caller);
+        const wait = project.manager.registerRequestWait(caller.runId, request);
+        return { wait, instruction: `Wait ${wait.id} registered until ${wait.deadline}. End your turn now to release capacity. Cezar resumes you when ${wait.mode === 'all' ? 'every selected request settles' : 'a selected request settles'} or at the deadline. Messages also wake you and keep this wait open; end your turn to keep waiting. Your other waits stay open beside it.` };
+    }
+    /** `cez message wait --peer` (hearsay-tools/cezarion#1995): the manager checks each peer through
+     *  the relationship resolver, so a worker or a non-peer is `denied_scope`. */
+    async waitPeers(caller, value) {
+        const request = peerWaitRequestSchema.parse(value);
+        const project = this.context(caller);
+        const wait = project.manager.registerPeerWait(caller.runId, request, 'cez-message-wait');
+        return { wait: peerWaitView(wait), instruction: `Wait ${wait.id} registered until ${wait.deadline}. End your turn now to release capacity. Cezar resumes you when a selected task messages you or settles, or at the deadline. Human and worker messages also wake you and keep this wait open; end your turn to keep waiting. Your other waits stay open beside it.` };
+    }
+    async spawn(caller, value) {
+        const request = workerSpawnRequestSchema.parse(value);
+        const initial = this.context(caller);
+        return this.serialized(`parent:${initial.id}:${caller.runId}`, async () => {
+            const project = this.context(caller);
+            const parent = project.store.getRun(caller.runId);
+            authorizeSpawnReplay(caller, parent, project.id);
+            if (parent?.delegation?.role !== 'root')
+                throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+            if (project.store.containsSessionSecret(JSON.stringify(request)))
+                throw new DelegationPolicyError('invalid_input', 'Credentials cannot be included in delegated input');
+            const requestHash = spawnRequestHash(request);
+            const replayed = replayedSpawn(project, parent, request.requestId, requestHash);
+            if (replayed)
+                return replayed;
+            authorizeSpawn(caller, parent, project.id, id => project.store.getRun(id));
+            const catalog = await resolveSpawnWorkflow(project, request);
+            const resolvedSteps = await resolveSpawnSteps(project.manager, parent.id, request, catalog, (step, settings) => this.validateModels(request, [{ step, settings }]));
+            // Run-level fields hold the first agent step (cockpit columns, pre-#452 evidence readers);
+            // the per-step list is what each launch binds.
+            const first = resolvedSteps[0];
+            const settings = first.settings;
+            const identity = acceptedWorkerIdentitySchema.parse({ kind: 'accepted', ...stepIdentityFields(first),
+                steps: resolvedSteps.map(entry => ({ stepId: entry.step.id, ...stepIdentityFields(entry) })) });
+            const baselineSha = await resolveWorkerBaseline(project.root, settings.cwd, request.baseline);
+            const workspace = await planOwnedWorkspace(project.root, randomUUID(), baselineSha);
+            const prepared = request.context === undefined ? undefined : await prepareWorkerContext({
+                repoRoot: project.root, dataDir: projectPaths(project.root).write, parentId: parent.id, workspace,
+                parentCwd: settings.cwd, context: request.context, containsSecret: text => project.store.containsSessionSecret(text),
+            });
+            return acceptSpawnedWorker({
+                project, parent, request, catalog, resolvedSteps, settings, identity, workspace, baselineSha, requestHash, prepared,
+                current: () => this.context(caller), caller,
+            });
+        });
+    }
+    async list(caller, query = {}) {
+        const project = this.context(caller);
+        const parent = project.store.getRun(caller.runId);
+        authorizeWorkerList(caller, parent, project.id);
+        if (parent?.delegation?.role !== 'root')
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        const workers = [];
+        const offset = Number(query.offset ?? 0);
+        const end = Math.min(offset + 32, parent.delegation.receipts.length);
+        for (const receipt of parent.delegation.receipts.slice(offset, end)) {
+            const worker = project.store.getRun(receipt.workerId);
+            // Deleted histories have no resources to supervise. Never expose an unrelated receipt target.
+            if (worker?.delegation?.role !== 'worker' || worker.delegation.parentRunId !== parent.id ||
+                worker.delegation.workspace.ownerRunId !== worker.id)
+                continue;
+            const inspection = await this.inspect(caller, { workerId: worker.id });
+            workers.push({ workerId: inspection.workerId, parentRunId: inspection.parentRunId,
+                status: inspection.status, workspace: inspection.workspace,
+                ...(inspection.destroy ? { destroy: inspection.destroy } : {}), revision: workerRevision(worker),
+                settled: inspection.outcome !== undefined && project.store.readWorkerExecution(worker.id)?.phase === 'complete',
+                destroyed: worker.delegation.destroy?.phase === 'complete' });
+        }
+        return { workers, ...(end < parent.delegation.receipts.length ? { nextOffset: end } : {}) };
+    }
+    async inspect(caller, params) {
+        const { project, worker, parent } = this.target(caller, params, 'inspect');
+        if (worker.delegation?.role !== 'worker')
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        project.manager.settleOrphanedWorkerExecution(worker.id); // #469: an orphan that died after recovery settles
+        const outcome = workerOutcome(worker, new Date().toISOString());
+        const wait = this.inspectedWait(parent, worker.id);
+        const completion = parent.delegation?.role === 'root' ? completionWaitEntry(parent.waits, worker.id) : undefined;
+        const completionWait = completion ? workerCompletionWaitProjection(completion, parent) : undefined;
+        return { workerId: worker.id, parentRunId: parent.id, status: worker.status, workspace: worker.delegation.workspace,
+            ...(worker.runner === undefined ? {} : { backend: worker.runner }), ...(worker.model === undefined ? {} : { model: worker.model }),
+            ...(worker.delegation.context === undefined ? {} : { inputs: worker.delegation.context.inputs }),
+            ...(worker.currentStepId === undefined ? {} : { currentStepId: worker.currentStepId }),
+            ...(wait ? { wait } : {}), ...(completionWait ? { completionWait } : {}), ...(worker.delegation.destroy ? { destroy: workerDestroyView(worker) } : {}), ...(outcome ? { outcome } : {}) };
+    }
+    /** The wait an inspection shows: the newest open or owed list wait naming the worker, in the
+     *  legacy `WorkerWait` shape (hearsay-tools/cezarion#1235). Cezar's completion wait carries no
+     *  deadline, which that shape requires, so inspection shows it as `completionWait`
+     *  (hearsay-tools/cezarion#1301). */
+    inspectedWait(parent, workerId) {
+        if (parent.delegation?.role !== 'root')
+            return undefined;
+        const entry = (parent.waits ?? []).filter((wait) => wait.kind === 'worker' && WAIT_KINDS.worker.hasDeadline(wait) && !!wait.workerIds?.includes(workerId)).at(-1);
+        return entry ? workerWaitEntryToLegacy(entry) : undefined;
+    }
+    async collect(caller, params) {
+        const project = this.context(caller);
+        const { workerId } = workerParamsSchema.parse(params);
+        const parent = project.store.getRun(caller.runId);
+        const worker = project.store.getRun(workerId);
+        if (!worker) {
+            const retained = project.store.readDeletedWorkerResult(caller.runId, workerId);
+            authorizeRetainedResult(caller, parent, project.id, workerId, retained);
+            const evidence = await revalidateRetainedWorkerResult(project.root, retained, project.store.sourceDataDir(caller.runId));
+            authorizeRetainedResult(caller, project.store.getRun(caller.runId), project.id, workerId, project.store.readDeletedWorkerResult(caller.runId, workerId));
+            return project.store.commitWorkerResult(caller.runId, evidence, project.store.readWorkerResultDiff(caller.runId, workerId));
+        }
+        authorizeWorker(caller, worker, 'inspect', parent, project.id);
+        project.manager.settleOrphanedWorkerExecution(workerId); // #469: before `settled` is computed
+        if (parent?.delegation?.role === 'root' && parent.delegation.receipts.some(receipt => receipt.workerId === workerId && receipt.deletion?.phase === 'pending')) {
+            const retained = project.store.readWorkerResult(parent.id, workerId);
+            if (!retained || !project.store.canDeleteRun(workerId))
+                throw new DelegationPolicyError('incompatible_state', 'Worker history deletion evidence is unavailable');
+            const evidence = await revalidateRetainedWorkerResult(project.root, retained, project.store.sourceDataDir(parent.id));
+            if (!project.store.canDeleteRun(workerId))
+                throw new DelegationPolicyError('incompatible_state', 'Worker history changed during collection');
+            return project.store.commitWorkerResult(parent.id, evidence, project.store.readWorkerResultDiff(parent.id, workerId));
+        }
+        // Store records preserve object references. Copy before yielding to Continue or cleanup.
+        const snapshot = structuredClone(worker);
+        const evidence = await collectWorkerEvidence(project.root, project.store, snapshot);
+        const current = this.target(caller, params, 'inspect');
+        if (current.project !== project || workerRevision(current.worker) !== workerRevision(snapshot) ||
+            current.worker.status !== snapshot.status || JSON.stringify(current.worker.delegation) !== JSON.stringify(snapshot.delegation)) {
+            throw new DelegationPolicyError('incompatible_state', 'Worker changed during collection; collect the current execution again');
+        }
+        return project.store.commitWorkerResult(parent.id, evidence.result, evidence.diffSnapshot);
+    }
+    async steer(caller, params, value) {
+        const request = workerSteerRequestSchema.parse(value);
+        const { project, worker, parent } = this.target(caller, params, 'steer');
+        if (project.store.containsSessionSecret(request.text))
+            throw new DelegationPolicyError('invalid_input', 'Credentials cannot be included in delegated input');
+        const state = project.manager.steerWorker(worker.id, { id: randomUUID(), source: 'agent', parentRunId: parent.id, text: request.text, createdAt: new Date().toISOString() });
+        return { workerId: worker.id, state };
+    }
+    async stop(caller, params) {
+        const { project, worker } = this.target(caller, params, 'stop');
+        return project.manager.requestWorkerStop(worker.id);
+    }
+    async diff(caller, params) {
+        const { project, worker } = this.target(caller, params, 'diff');
+        return readOwnedDiff(project.root, worker);
+    }
+    async wait(caller, value) {
+        const request = workerWaitRequestSchema.parse(value);
+        for (const workerId of request.workerIds)
+            this.target(caller, { workerId }, 'wait');
+        const project = this.context(caller);
+        const wait = project.manager.registerWorkerWait(caller.runId, request);
+        return { wait, instruction: `Wait ${wait.id} registered until ${wait.deadline}. End your turn now to release capacity. Cezar resumes you when ${wait.mode === 'all' ? 'all selected workers settle' : 'a selected worker settles'} or at the deadline. Messages also wake you and keep this wait open; end your turn to keep waiting. Your other waits stay open beside it.` };
+    }
+    async cancelWait(caller, value) {
+        const { waitId } = workerCancelWaitRequestSchema.parse(value);
+        const project = this.context(caller);
+        const sender = project.store.getRun(caller.runId);
+        if (sender?.delegation?.role === 'worker') {
+            this.conversationPair(caller, sender.delegation.parentRunId);
+            // hearsay-tools/cezarion#1235: a worker's request wait is a list entry, open or settled.
+            const wait = [...sender.waits ?? [], ...sender.lastWaits ?? []].find(entry => entry.id === waitId && entry.kind === 'worker');
+            if (wait?.kind !== 'worker' || !wait.requestIds?.length)
+                throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+            for (const requestId of wait.requestIds)
+                this.ownRequest(caller, requestId);
+        }
+        else {
+            authorizeCancelWait(caller, sender, project.id);
+            // A peer wait is cancelled through the list too (hearsay-tools/cezarion#1995).
+            if ([...sender?.waits ?? [], ...sender?.lastWaits ?? []].some(entry => entry.id === waitId && entry.kind === 'peer')) {
+                return { wait: peerWaitView(project.manager.cancelPeerWait(caller.runId, waitId)) };
+            }
+        }
+        return { wait: project.manager.cancelWorkerWait(caller.runId, waitId) };
+    }
+    async destroy(caller, params) {
+        const { project, worker } = this.target(caller, params, 'destroy');
+        return this.cleanups.get(project.id).request(worker.id, () => this.target(caller, params, 'destroy').worker);
+    }
+    /** Existing human HTTP authority, bound to its resolved project; never mint a pretend agent caller. */
+    async destroyForHuman(projectId, workerId) {
+        const project = this.projects.get(projectId);
+        if (!project)
+            throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+        const check = () => {
+            const worker = project.store.getRun(workerId);
+            if (this.projects.get(projectId) !== project || worker?.delegation?.role !== 'worker' || worker.delegation.workspace.ownerRunId !== workerId)
+                throw new DelegationPolicyError('denied_scope', 'Worker scope denied');
+            return worker;
+        };
+        check();
+        return this.cleanups.get(project.id).request(workerId, check);
+    }
+}
+//# sourceMappingURL=service.js.map