@hivemagnus/ardent-studio 0.0.0-stage → 0.1.0

package/dist/conductor/conductor.js

@@ -0,0 +1,939 @@
+// The conductor: one worker inside ArdentStudio that starts agent turns through Magnus, follows
+// them, relays live reply text, writes the final messages and enforces team rules on what
+// agents request. It never runs model work, and everything it records comes from a person's
+// request or a real Ardent record. See docs/CONDUCTOR.md.
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+import { isAvailable } from '../agents/directory.js';
+import { ARDENT_STUDIO_CAPABILITY, MagnusError, parseAgentRef } from '../clients/magnus.js';
+import { ServiceTokenError } from '../clients/service-token.js';
+import { hivememProjectId } from '../db/repos/projects.js';
+import { sessionKey } from '../db/repos/sessions.js';
+import { TERMINAL_TASK_STATES } from '../db/repos/tasks.js';
+import { deriveActivity, excerpt } from './activity.js';
+import { ARDENT_FINISHED, TaskFollower } from './follower.js';
+import { buildMission, composeTurn, HANDOFF_EDGES } from './prompting.js';
+export class ConductorError extends Error {
+    status;
+    code;
+    name = 'ConductorError';
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+const ROOM_HISTORY = 50;
+const ATTACHMENT_TEXT_LIMIT = 256 * 1024;
+const TEXT_MIME = /^(text\/|application\/json$|image\/svg\+xml$)/;
+const FINISHED = [...TERMINAL_TASK_STATES, 'input_required'];
+const handoffSchema = z.object({ to_role: z.string(), objective: z.string(), deliverables: z.array(z.string()).optional(), note: z.string().optional() });
+const askSchema = z.object({ question: z.string(), options: z.array(z.string()).optional() });
+const proposalSchema = z.object({ title: z.string(), statement: z.string(), rationale: z.string().optional() });
+const stateSchema = z.object({ to: z.string() });
+const toolSchema = z.object({ name: z.string() });
+const teamResultSchema = z.object({ outcome: z.string(), summary: z.string(), artifacts: z.array(z.object({ name: z.string(), sha256: z.string() }).loose()).optional() }).loose();
+/** A stable UUID for a Studio task, so a retried submission is the same Ardent task. */
+export function ardentIdempotencyKey(taskId) {
+    const hex = createHash('sha256').update(`ardentstudio:${taskId}`).digest('hex');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-${((parseInt(hex[16], 16) & 0x3) | 0x8).toString(16)}${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
+}
+function transient(error) {
+    if (error instanceof ServiceTokenError)
+        return true;
+    if (error instanceof MagnusError)
+        return error.status >= 500 || error.status === 429 || error.status === 408;
+    return !(error instanceof z.ZodError);
+}
+function errorText(error) {
+    return error instanceof Error ? error.message.slice(0, 300) : 'unknown error';
+}
+const versionAtLeast = (version, minimum) => {
+    const match = version ? /^(\d+)\.(\d+)\.(\d+)/.exec(version) : null;
+    if (!match)
+        return false;
+    const parts = [Number(match[1]), Number(match[2]), Number(match[3])];
+    for (let index = 0; index < 3; index++)
+        if (parts[index] !== minimum[index])
+            return parts[index] > minimum[index];
+    return true;
+};
+export class Conductor {
+    options;
+    followers = new Map();
+    submitting = new Set();
+    retryAt = new Map();
+    capabilities = new Map();
+    /** Last presence probe per agent. Absent until probed. */
+    presence = new Map();
+    /** Re-derive an agent's activity when its Delivering window ends, per project and binding. */
+    deliveringTimers = new Map();
+    hooks = [];
+    contextProviders = [];
+    modes = new Map();
+    pumping;
+    pumpAgain = false;
+    retryTimer;
+    presenceTimer;
+    stopped = false;
+    store;
+    magnus;
+    constructor(options) {
+        this.options = options;
+        this.store = options.store;
+        this.magnus = options.magnus;
+    }
+    /** Register a journal hook (for example the artifact importer). */
+    onJournalEvent(hook) {
+        this.hooks.push(hook);
+    }
+    /** Register extra turn context (for example the review comments of a revision task). */
+    addContextProvider(provider) {
+        this.contextProviders.push(provider);
+    }
+    /** Handle tasks of this mode with the handler instead of the room (for example team proposals). */
+    registerMode(mode, handler) {
+        this.modes.set(mode, handler);
+    }
+    /** Resume following every accepted task from its stored cursor, finish discussions a restart interrupted, and start dispatching. */
+    start() {
+        this.stopped = false;
+        for (const task of this.store.tasks.following())
+            this.follow(task);
+        for (const conversation of this.runningDiscussions())
+            this.advanceDiscussion(conversation.id);
+        this.kick();
+        void this.probe();
+        this.presenceTimer = setInterval(() => { void this.probe(); }, this.options.presenceMs ?? 30_000);
+        this.presenceTimer.unref();
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.presenceTimer)
+            clearInterval(this.presenceTimer);
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        for (const timer of this.deliveringTimers.values())
+            clearTimeout(timer);
+        this.deliveringTimers.clear();
+        await Promise.all([...this.followers.values()].map(follower => follower.stop()));
+        this.followers.clear();
+        await this.pumping;
+    }
+    /** Tasks the conductor currently follows (for tests and diagnostics). */
+    followerOf(taskId) {
+        return this.followers.get(taskId);
+    }
+    // ── Dispatch ──
+    /** Submit every task that is ready. Safe to call often: runs are serialized. */
+    kick() {
+        if (this.stopped)
+            return;
+        if (this.pumping) {
+            this.pumpAgain = true;
+            return;
+        }
+        this.pumping = this.pump().finally(() => {
+            this.pumping = undefined;
+            if (this.pumpAgain) {
+                this.pumpAgain = false;
+                this.kick();
+            }
+        });
+    }
+    /** Resolves when no dispatch run is in progress. */
+    async settled() {
+        while (this.pumping)
+            await this.pumping;
+    }
+    async pump() {
+        const now = Date.now();
+        const ready = [];
+        for (const task of this.store.tasks.unsubmitted()) {
+            if (this.submitting.has(task.id) || (this.retryAt.get(task.id) ?? 0) > now)
+                continue;
+            const project = this.store.projects.get(task.project_id);
+            if (!project || project.status !== 'active')
+                continue;
+            const conversation = task.conversation_id ? this.store.room.conversation(task.conversation_id) : undefined;
+            if (conversation?.stopped_at) {
+                this.cancelLocally(task, 'The conversation was stopped before this turn started.');
+                continue;
+            }
+            const ahead = this.store.tasks.groupBefore(task).filter(item => !FINISHED.includes(item.state));
+            if (ahead.length) {
+                this.refreshActivity(task.project_id, task.binding_id);
+                continue;
+            }
+            ready.push(task);
+        }
+        await Promise.all(ready.map(task => this.submit(task)));
+    }
+    resolve(task) {
+        const project = this.store.projects.get(task.project_id);
+        if (!project)
+            return 'The project no longer exists.';
+        const revision = task.assignment_revision ? this.store.team.revision(project.id, task.assignment_revision) : this.store.team.current(project.id);
+        if (!revision)
+            return 'The project has no published team.';
+        const role = revision.body.roles.find(item => item.key === task.role_key);
+        if (!role)
+            return `Team r${revision.revision} has no role "${task.role_key ?? ''}".`;
+        if (!role.agent_ref)
+            return `${role.name} has no bound agent in team r${revision.revision}.`;
+        const bindingId = role.binding_id ?? this.store.team.ensureBinding(role.agent_ref).id;
+        return { project, revision, role, agentRef: role.agent_ref, bindingId };
+    }
+    /**
+     * Studio level and whether the agent runs an Ardent with missions, both from the node's one
+     * installation record (every profile on a node runs its one Ardent package). Cached briefly.
+     * A failed or stale agent list never decides this, so a mission is not silently sent as a
+     * plain task without its tools.
+     */
+    async capability(agentRef) {
+        const { nodeId } = parseAgentRef(agentRef);
+        let cached = this.capabilities.get(nodeId);
+        if (!cached || Date.now() - cached.at >= (this.options.capabilityCacheMs ?? 60_000)) {
+            const installation = await this.magnus.getInstallation(nodeId);
+            cached = { level: installation.capabilities?.studio ?? 0, version: installation.version, at: Date.now() };
+            this.capabilities.set(nodeId, cached);
+        }
+        const { level, version } = cached;
+        return { level, missions: level >= ARDENT_STUDIO_CAPABILITY.missions && versionAtLeast(version, [2, 2, 0]) };
+    }
+    /** A room turn: the role's agent under the task's team revision, with an Ardent session when the node supports one. */
+    async planTurn(task) {
+        const resolved = this.resolve(task);
+        if (typeof resolved === 'string')
+            return resolved;
+        const { project, revision, role, agentRef } = resolved;
+        const { level, missions } = await this.capability(agentRef);
+        const conversationId = task.conversation_id ?? this.ensureTeamConversation(project.id, 'conductor').id;
+        const context = missions ? 'mission' : 'direct';
+        let session = level >= ARDENT_STUDIO_CAPABILITY.bridge ? this.store.sessions.get(conversationId, role.key, agentRef, context) : undefined;
+        if (level >= ARDENT_STUDIO_CAPABILITY.bridge && !session) {
+            const key = sessionKey(project.id, conversationId, role.key);
+            const opened = await this.magnus.openSession(agentRef, missions ? { key, context } : { key });
+            session = this.store.sessions.save({ conversationId, roleKey: role.key, agentRef, context, projectId: project.id, sessionKey: key, sessionId: opened.id });
+        }
+        const turn = this.compose(task, resolved, conversationId, session?.last_seen_seq ?? 0, !session || session.turns === 0);
+        return {
+            agentRef, dispatch: missions ? 'mission' : 'turn', session, seenSeq: turn.seenSeq,
+            objective: turn.composed.objective, contextItems: turn.composed.contextItems, prompt: turn.composed.prompt,
+            mission: missions ? buildMission({ task, project, team: revision.body, role, hivememProjectId: hivememProjectId(project.id), now: new Date() }) : undefined,
+            labels: { 'studio.project': project.id, 'studio.task': task.id, 'studio.conversation': conversationId, 'studio.role': role.key },
+        };
+    }
+    /** A handled mode: one request without a session, composed by its handler. */
+    async planHandled(task, handler) {
+        const project = this.store.projects.get(task.project_id);
+        if (!project)
+            return 'The project no longer exists.';
+        const chosen = handler.agent(task);
+        if ('error' in chosen)
+            return chosen.error;
+        const { missions } = await this.capability(chosen.agentRef);
+        const dispatch = missions ? 'mission' : 'turn';
+        const request = handler.compose(task, { project, dispatch, now: new Date() });
+        return {
+            agentRef: chosen.agentRef, dispatch, session: undefined, seenSeq: 0, objective: request.objective, contextItems: request.contextItems,
+            prompt: request.prompt, mission: missions ? request.mission : undefined,
+            labels: { 'studio.project': project.id, 'studio.task': task.id, 'studio.mode': task.mode },
+        };
+    }
+    async submit(task) {
+        this.submitting.add(task.id);
+        try {
+            const handler = this.modes.get(task.mode);
+            const plan = handler ? await this.planHandled(task, handler) : await this.planTurn(task);
+            if (typeof plan === 'string') {
+                this.failTask(task, plan);
+                return;
+            }
+            const { agentRef, dispatch, session, mission } = plan;
+            let admission;
+            if (mission) {
+                admission = await this.magnus.submitMission(agentRef, {
+                    ...(session ? { session_id: session.session_id } : {}), objective: plan.objective, mission,
+                    ...(plan.contextItems.length ? { context_items: plan.contextItems } : {}),
+                    labels: plan.labels,
+                    idempotency_key: task.id,
+                });
+            }
+            else {
+                admission = await this.magnus.submitTask(agentRef, { prompt: plan.prompt, idempotency_key: ardentIdempotencyKey(task.id), ...(session ? { session_id: session.session_id } : {}) });
+            }
+            this.retryAt.delete(task.id);
+            let accepted;
+            this.store.tx(() => {
+                const current = this.store.tasks.get(task.id);
+                accepted = this.store.tasks.attachArdent(task.id, { agentRef, taskId: admission.task_id, sessionId: session?.session_id ?? null, dispatch, ...(mission ? { mission } : {}) });
+                if (current.state === 'queued' && admission.state === 'running')
+                    accepted = this.store.tasks.setState(task.id, 'running');
+                if (session)
+                    this.store.sessions.recordTurn(session, plan.seenSeq);
+                this.store.emit(task.project_id, 'task.updated', this.taskEvent(accepted));
+                this.refreshActivity(task.project_id, accepted.binding_id);
+            });
+            // A pause or cancel asked for while the submission was in flight applies now.
+            if (accepted.state === 'paused')
+                void this.magnus.pauseTask(agentRef, admission.task_id).catch(error => this.options.logger.warn('Pause after admission failed', { task_id: task.id, error: errorText(error) }));
+            if (accepted.state === 'cancelled') {
+                void this.magnus.cancelTask(agentRef, admission.task_id).catch(error => this.options.logger.warn('Cancel after admission failed', { task_id: task.id, error: errorText(error) }));
+                return;
+            }
+            this.follow(accepted);
+        }
+        catch (error) {
+            if (transient(error)) {
+                const attempts = this.store.tasks.countAttempt(task.id);
+                if (attempts < (this.options.maxSubmitAttempts ?? 5)) {
+                    const wait = (this.options.submitRetryMs ?? 1_000) * 2 ** (attempts - 1);
+                    this.retryAt.set(task.id, Date.now() + wait);
+                    this.scheduleRetry(wait);
+                    this.options.logger.warn('Task submission failed; retrying', { task_id: task.id, attempts, error: errorText(error) });
+                    return;
+                }
+            }
+            this.failTask(task, `Magnus could not start the turn: ${errorText(error)}`);
+        }
+        finally {
+            this.submitting.delete(task.id);
+        }
+    }
+    scheduleRetry(ms) {
+        if (this.stopped)
+            return;
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        this.retryTimer = setTimeout(() => { this.retryTimer = undefined; this.kick(); }, ms + 5);
+        this.retryTimer.unref();
+    }
+    compose(task, context, conversationId, lastSeen, firstTurn) {
+        const { project, revision, role, bindingId } = context;
+        const conversation = this.store.room.conversation(conversationId);
+        const trigger = task.trigger_message_id ? this.store.room.message(task.trigger_message_id) : undefined;
+        const roleNames = new Map(revision.body.roles.map(item => [item.key, item.name]));
+        const names = {
+            role: (key) => roleNames.get(key) ?? key,
+            author: (message) => message.author.kind === 'user' ? message.author.user_id
+                : message.author.kind === 'agent' ? (message.author.role_key ? roleNames.get(message.author.role_key) ?? message.author.role_key : 'Agent') : 'Studio',
+        };
+        const own = (message) => message.author.kind === 'agent' && message.author.binding_id === bindingId;
+        let unseen = [];
+        let discussion;
+        if (conversation.kind === 'discussion' && conversation.discussion) {
+            const transcript = this.store.room.recentMessages(conversation.id, ROOM_HISTORY);
+            discussion = { ...conversation.discussion, summary: task.source.summary === true, transcript };
+        }
+        else {
+            unseen = this.store.room.messages(conversationId, lastSeen, 500).filter(message => message.id !== trigger?.id && !own(message)).slice(-ROOM_HISTORY);
+        }
+        const attachments = (trigger?.attachments ?? []).flatMap(id => {
+            const file = this.store.files.get(id);
+            return file ? [this.attachmentText(file)] : [];
+        });
+        const extra = this.contextProviders.flatMap(provider => provider(task));
+        const composed = composeTurn({ project, team: revision.body, role, task, firstTurn, unseen, trigger, names, attachments, discussion, extra });
+        const seen = [...unseen, ...(trigger ? [trigger] : []), ...(discussion?.transcript ?? [])].reduce((max, message) => Math.max(max, message.seq), lastSeen);
+        return { composed, seenSeq: seen };
+    }
+    /** Text attachments are read synchronously only when small; others are named, not inlined. */
+    attachmentText(file) {
+        if (!TEXT_MIME.test(file.mime) || file.size > ATTACHMENT_TEXT_LIMIT)
+            return { name: file.name, mime: file.mime, text: null };
+        try {
+            const text = this.options.blobs.readTextSync(file.sha256);
+            return { name: file.name, mime: file.mime, text };
+        }
+        catch {
+            return { name: file.name, mime: file.mime, text: null };
+        }
+    }
+    /** A task that could not start: record why, in the task and in the room. */
+    failTask(task, reason) {
+        this.retryAt.delete(task.id);
+        this.store.tx(() => {
+            const current = this.store.tasks.get(task.id);
+            if (!current || FINISHED.includes(current.state))
+                return;
+            const failed = this.store.tasks.setState(task.id, 'failed', { error: reason, ardent_state: null });
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(failed));
+            const handler = this.modes.get(task.mode);
+            const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+            if (handler)
+                handler.finished(failed, { state: 'failed', reply: null, error: reason });
+            else if (conversationId)
+                this.systemMessage(conversationId, `${this.roleName(task)}: ${task.title}. ${reason}`, { task_id: task.id }, task.trigger_message_id);
+            this.refreshActivity(task.project_id, task.binding_id);
+        });
+        this.afterFinish(task);
+    }
+    cancelLocally(task, reason) {
+        this.store.tx(() => {
+            const current = this.store.tasks.get(task.id);
+            if (!current || FINISHED.includes(current.state))
+                return;
+            const cancelled = this.store.tasks.setState(task.id, 'cancelled', { error: null, ardent_state: null, note: reason });
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(cancelled));
+            this.modes.get(task.mode)?.finished(cancelled, { state: 'cancelled', reply: null, error: reason });
+            this.refreshActivity(task.project_id, task.binding_id);
+        });
+        this.afterFinish(task);
+    }
+    // ── Following ──
+    follow(task) {
+        if (this.stopped || this.followers.has(task.id) || !task.ardent.agent_ref || !task.ardent.task_id)
+            return;
+        const ref = task.ardent.agent_ref;
+        const follower = new TaskFollower(this.magnus, ref, task.ardent.task_id, {
+            cursor: () => this.store.tasks.get(task.id)?.ardent.event_cursor ?? 0,
+            text: (step, text, mode) => this.relay(task.id, step, text, mode),
+            event: event => this.journal(task.id, event),
+            done: record => this.finish(task.id, record),
+        }, this.options.logger, this.options.follower);
+        this.followers.set(task.id, follower);
+        void follower.start().finally(() => { if (this.followers.get(task.id) === follower)
+            this.followers.delete(task.id); });
+    }
+    /** Live reply text: create the streaming message on the first visible text, then relay it. */
+    relay(taskId, step, text, mode) {
+        const task = this.store.tasks.get(taskId);
+        // Handled modes do not speak in the room; their reply is read when the task finishes.
+        if (!task?.ardent.task_id || FINISHED.includes(task.state) || this.modes.has(task.mode))
+            return;
+        let message = this.store.room.messageForArdentTask(task.ardent.task_id);
+        if (!message) {
+            if (!text)
+                return;
+            const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+            if (!conversationId)
+                return;
+            message = this.store.tx(() => {
+                const created = this.store.room.addMessage({ conversationId, author: this.agentAuthor(task), kind: task.source.summary === true ? 'summary' : 'reply',
+                    bodyMd: '', replyTo: task.trigger_message_id, links: { task_id: task.id }, ardent: { task_id: task.ardent.task_id, session_id: task.ardent.session_id }, state: 'streaming' });
+                this.store.emit(task.project_id, 'message.created', this.messageEvent(created));
+                return created;
+            });
+        }
+        if (message.state !== 'streaming')
+            return;
+        if (mode === 'replace')
+            this.options.live.replace(task.project_id, message.id, step, text);
+        else
+            this.options.live.append(task.project_id, message.id, step, text);
+    }
+    /** Handle one journal event and advance the cursor in the same transaction. True when it ends the turn. */
+    async journal(taskId, event) {
+        const task = this.store.tasks.get(taskId);
+        if (!task || event.sequence <= task.ardent.event_cursor)
+            return false;
+        let ended = false;
+        let dispatch = false;
+        this.store.tx(() => {
+            switch (event.kind) {
+                case 'state': {
+                    const to = stateSchema.safeParse(event.detail).data?.to;
+                    if (to === 'running' && (task.state === 'queued')) {
+                        this.store.emit(task.project_id, 'task.updated', this.taskEvent(this.store.tasks.setState(task.id, 'running')));
+                    }
+                    if (to === 'input_required')
+                        ended = true;
+                    break;
+                }
+                case 'model_started':
+                    if (!FINISHED.includes(task.state))
+                        this.store.tasks.noteProgress(task.id, { model_started: true });
+                    break;
+                case 'tool_attempt': {
+                    const tool = toolSchema.safeParse(event.detail).data?.name;
+                    if (tool && !FINISHED.includes(task.state))
+                        this.store.tasks.noteProgress(task.id, { model_started: true, tool });
+                    break;
+                }
+                case 'team_handoff':
+                    dispatch = this.handoff(task, event);
+                    break;
+                case 'team_ask_user':
+                    this.clarification(task, event);
+                    break;
+                case 'team_propose_decision':
+                    this.proposal(task, event);
+                    break;
+                case 'pause_requested':
+                    if (!FINISHED.includes(task.state))
+                        this.store.emit(task.project_id, 'task.updated', this.taskEvent(this.store.tasks.setState(task.id, 'pausing')));
+                    break;
+                case 'paused':
+                    if (!FINISHED.includes(task.state))
+                        this.store.emit(task.project_id, 'task.updated', this.taskEvent(this.store.tasks.setState(task.id, 'paused')));
+                    break;
+                case 'resumed':
+                    if (!FINISHED.includes(task.state))
+                        this.store.emit(task.project_id, 'task.updated', this.taskEvent(this.store.tasks.setState(task.id, 'running')));
+                    break;
+                default: break;
+            }
+            for (const hook of this.hooks)
+                hook(task, event);
+            this.store.tasks.advanceCursor(task.id, event.sequence);
+            this.refreshActivity(task.project_id, task.binding_id);
+        });
+        if (dispatch)
+            this.kick();
+        if (ended && task.ardent.agent_ref && task.ardent.task_id) {
+            const record = await this.magnus.task(task.ardent.agent_ref, task.ardent.task_id).catch(() => undefined);
+            if (record && ARDENT_FINISHED.includes(record.state)) {
+                await this.finish(task.id, record);
+                return true;
+            }
+        }
+        return false;
+    }
+    /** An agent asked for a hand-off. Studio starts it only along a delegates_to or hands_off_to edge of the task's team revision. */
+    handoff(task, event) {
+        const request = handoffSchema.safeParse(event.detail);
+        const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+        if (!request.success || !conversationId)
+            return false;
+        const revision = task.assignment_revision ? this.store.team.revision(task.project_id, task.assignment_revision) : this.store.team.current(task.project_id);
+        const from = this.roleName(task);
+        const asked = request.data.to_role.trim();
+        const target = revision?.body.roles.find(role => role.key === asked || role.name.toLowerCase() === asked.toLowerCase());
+        const refuse = (why) => {
+            this.systemMessage(conversationId, `${from} asked to hand work to ${target?.name ?? JSON.stringify(asked)} (${excerpt(request.data.objective, 120)}). ${why}`, { task_id: task.id, handoff: { from_role: task.role_key, to_role: target?.key ?? asked, objective: request.data.objective, allowed: false } }, task.trigger_message_id);
+            return false;
+        };
+        if (!revision)
+            return refuse('The project has no published team, so Studio did not start it.');
+        if (!target)
+            return refuse(`Team r${revision.revision} has no such role, so Studio did not start it.`);
+        const edge = revision.body.relationships.find(item => item.from === task.role_key && item.to === target.key && HANDOFF_EDGES.includes(item.type));
+        if (!edge) {
+            return refuse(`Team r${revision.revision} has no delegates_to or hands_off_to relationship from ${from} to ${target.name}, so Studio did not start it. `
+                + 'A person can assign the work from the Tasks drawer or change the team.');
+        }
+        if (!target.agent_ref)
+            return refuse(`${target.name} has no bound agent in team r${revision.revision}, so Studio did not start it.`);
+        const instructions = [request.data.objective, request.data.deliverables?.length ? `Deliverables: ${request.data.deliverables.join('; ')}` : '',
+            request.data.note ? `Note from ${from}: ${request.data.note}` : ''].filter(Boolean).join('\n\n');
+        const created = this.store.tasks.create({
+            projectId: task.project_id, title: excerpt(request.data.objective, 200), mode: 'assignment', roleKey: target.key,
+            bindingId: target.binding_id ?? this.store.team.ensureBinding(target.agent_ref).id, assignmentRevision: revision.revision,
+            source: { handoff_from: task.role_key, from_task: task.id, ardent_event_seq: event.sequence, relationship: edge.type },
+            createdBy: 'conductor', conversationId, instructionsMd: instructions,
+        });
+        this.store.emit(task.project_id, 'task.created', this.taskEvent(created));
+        const message = this.store.room.addMessage({ conversationId, author: this.agentAuthor(task), kind: 'handoff', addressees: [target.key],
+            bodyMd: `Handed off to ${target.name}: ${request.data.objective}`, replyTo: task.trigger_message_id,
+            links: { task_id: task.id, handoff: { from_role: task.role_key, to_role: target.key, task_id: created.id, relationship: edge.type, allowed: true } }, state: 'complete' });
+        this.store.emit(task.project_id, 'message.created', this.messageEvent(message));
+        this.refreshActivity(task.project_id, created.binding_id);
+        return true;
+    }
+    clarification(task, event) {
+        const asked = askSchema.safeParse(event.detail);
+        const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+        if (!asked.success || !conversationId)
+            return;
+        const message = this.store.room.addMessage({ conversationId, author: this.agentAuthor(task), kind: 'clarification', bodyMd: asked.data.question,
+            replyTo: task.trigger_message_id, links: { task_id: task.id, question: asked.data.question, options: asked.data.options ?? [], answer_message_id: null }, state: 'complete' });
+        this.store.emit(task.project_id, 'message.created', this.messageEvent(message));
+        const outcome = (task.outcome && typeof task.outcome === 'object' ? task.outcome : {});
+        this.store.tasks.setState(task.id, task.state, { ...outcome, clarification_message_id: message.id });
+    }
+    proposal(task, event) {
+        const proposal = proposalSchema.safeParse(event.detail);
+        const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+        if (!proposal.success || !conversationId)
+            return;
+        // Pinning stays with a person: this is only a proposal card.
+        const message = this.store.room.addMessage({ conversationId, author: this.agentAuthor(task), kind: 'decision_proposal', bodyMd: proposal.data.statement,
+            replyTo: task.trigger_message_id, links: { task_id: task.id, proposal: { title: proposal.data.title, statement: proposal.data.statement, rationale: proposal.data.rationale ?? '' }, decision_id: null },
+            state: 'complete' });
+        this.store.emit(task.project_id, 'message.created', this.messageEvent(message));
+    }
+    /** The task finished in Ardent: write the final message and the task state. Idempotent on the Ardent task id. */
+    async finish(taskId, record) {
+        const task = this.store.tasks.get(taskId);
+        if (!task || !task.ardent.task_id || FINISHED.includes(task.state))
+            return;
+        // The stream may end before every journal event was sent: read the rest first.
+        if (task.ardent.agent_ref) {
+            const rest = await this.magnus.taskEvents(task.ardent.agent_ref, task.ardent.task_id, task.ardent.event_cursor).catch(() => []);
+            for (const event of rest)
+                await this.journal(taskId, event);
+        }
+        this.complete(taskId, record);
+    }
+    /** Exposed for routes that receive a final task record directly (cancel). */
+    complete(taskId, record) {
+        const task = this.store.tasks.get(taskId);
+        if (!task || !task.ardent.task_id || FINISHED.includes(task.state))
+            return;
+        const result = typeof record.result === 'string' ? record.result : null;
+        let teamResult;
+        if (task.dispatch === 'mission' && result) {
+            try {
+                teamResult = teamResultSchema.safeParse(JSON.parse(result)).data;
+            }
+            catch {
+                teamResult = undefined;
+            }
+        }
+        const outcome = (task.outcome && typeof task.outcome === 'object' ? task.outcome : {});
+        const asked = typeof outcome.clarification_message_id === 'string' || teamResult?.outcome === 'input_required';
+        const ardentState = record.state;
+        const state = ardentState === 'missing' ? 'unknown'
+            : (ardentState === 'completed' || ardentState === 'partial') ? (asked ? 'input_required' : ardentState)
+                : ['failed', 'cancelled', 'unknown', 'input_required'].find(item => item === ardentState) ?? 'unknown';
+        const answer = (teamResult?.summary ?? result ?? '').trim();
+        // Ardent summarizes a turn that ended with team_ask_user as the question itself, which the
+        // clarification card already shows: posting it again as a reply would repeat the question.
+        const question = typeof outcome.clarification_message_id === 'string' ? this.store.room.message(outcome.clarification_message_id)?.body_md.trim() : undefined;
+        const reply = asked && question !== undefined && answer === question ? '' : answer;
+        const error = typeof record.error === 'string' && record.error ? record.error.slice(0, 2000) : null;
+        const handler = this.modes.get(task.mode);
+        if (handler) {
+            this.completeHandled(task, handler, { ardentState, reply, error, outcome });
+            return;
+        }
+        let finishedMessage;
+        this.store.tx(() => {
+            const current = this.store.tasks.get(taskId);
+            if (FINISHED.includes(current.state))
+                return;
+            const conversationId = task.conversation_id ?? this.store.room.teamConversation(task.project_id)?.id;
+            const existing = this.store.room.messageForArdentTask(task.ardent.task_id);
+            const failed = state === 'failed' || state === 'unknown' || state === 'cancelled';
+            const body = reply || (state === 'cancelled' ? 'The task was cancelled.' : failed ? `The task ${state === 'failed' ? 'failed' : 'ended in an unknown state'}${error ? `: ${error}` : '.'}` : '');
+            if (existing) {
+                if (existing.state === 'streaming') {
+                    finishedMessage = this.store.room.finishMessage(existing.id, { bodyMd: body, state: failed && !reply ? 'failed' : 'complete' });
+                    this.store.emit(task.project_id, 'message.updated', this.messageEvent(finishedMessage));
+                }
+            }
+            else if (conversationId && body) {
+                finishedMessage = this.store.room.addMessage({ conversationId, author: this.agentAuthor(task), kind: task.source.summary === true ? 'summary' : 'reply', bodyMd: body,
+                    replyTo: task.trigger_message_id, links: { task_id: task.id }, ardent: { task_id: task.ardent.task_id, session_id: task.ardent.session_id },
+                    state: failed && !reply ? 'failed' : 'complete' });
+                this.store.emit(task.project_id, 'message.created', this.messageEvent(finishedMessage));
+            }
+            const finished = this.store.tasks.setState(taskId, state, {
+                ...outcome, ardent_state: ardentState, error, reply_message_id: finishedMessage?.id ?? existing?.id ?? null,
+                ...(teamResult ? { team_result: { outcome: teamResult.outcome, artifacts: teamResult.artifacts?.length ?? 0 } } : {}),
+            });
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(finished));
+            this.refreshActivity(task.project_id, task.binding_id);
+        });
+        const live = finishedMessage ?? this.store.room.messageForArdentTask(task.ardent.task_id);
+        if (live)
+            this.options.live.clear(live.id);
+        this.afterFinish(task);
+    }
+    /** A handled mode has no clarifications: Ardent input_required ends it as partial, and the handler reads the reply. */
+    completeHandled(task, handler, input) {
+        const { ardentState } = input;
+        const state = ardentState === 'completed' || ardentState === 'partial' ? ardentState
+            : ardentState === 'input_required' ? 'partial'
+                : ardentState === 'failed' || ardentState === 'cancelled' ? ardentState : 'unknown';
+        this.store.tx(() => {
+            if (FINISHED.includes(this.store.tasks.get(task.id).state))
+                return;
+            const finished = this.store.tasks.setState(task.id, state, { ...input.outcome, ardent_state: ardentState, error: input.error });
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(finished));
+            handler.finished(finished, { state, reply: input.reply || null, error: input.error });
+            this.refreshActivity(task.project_id, task.binding_id);
+        });
+        this.afterFinish(task);
+    }
+    afterFinish(task) {
+        if (task.mode === 'discussion_turn' && task.conversation_id)
+            this.advanceDiscussion(task.conversation_id);
+        this.kick();
+    }
+    // ── Requests from people (routes call these inside or after their transaction) ──
+    /** The project's team conversation, created on first use. Call inside a transaction. */
+    ensureTeamConversation(projectId, createdBy) {
+        const existing = this.store.room.teamConversation(projectId);
+        if (existing)
+            return existing;
+        return this.store.tx(() => {
+            const created = this.store.room.createConversation({ projectId, kind: 'team', title: 'Team room', createdBy });
+            this.store.emit(projectId, 'conversation.created', { conversation: created });
+            return created;
+        });
+    }
+    /**
+     * Queue one turn per addressee in an ordering group, so each addressee sees the replies before
+     * theirs. Call inside the transaction that stored the message.
+     */
+    queueTurns(input) {
+        const groupId = `${input.message.id}:turns`;
+        return input.roles.map((role, position) => {
+            const task = this.store.tasks.create({
+                projectId: input.project.id, title: excerpt(input.message.body_md || 'Reply', 120), mode: input.mode ?? 'turn', roleKey: role.key,
+                bindingId: role.binding_id ?? (role.agent_ref ? this.store.team.ensureBinding(role.agent_ref).id : null), assignmentRevision: input.revision.revision,
+                source: { message_id: input.message.id, ...input.source }, createdBy: input.createdBy, conversationId: input.conversation.id,
+                triggerMessageId: input.message.id, groupId: input.roles.length > 1 ? groupId : null, groupPosition: position,
+            });
+            this.store.emit(input.project.id, 'task.created', this.taskEvent(task));
+            this.refreshActivity(input.project.id, task.binding_id);
+            return task;
+        });
+    }
+    /** Queue one task (an assignment, follow-up or answer). Call inside a transaction. */
+    queueTask(input) {
+        const task = this.store.tasks.create(input);
+        this.store.emit(input.projectId, 'task.created', this.taskEvent(task));
+        this.refreshActivity(input.projectId, task.binding_id);
+        return task;
+    }
+    /** Queue round `round` of a discussion: one turn per participant, in order. Call inside a transaction. */
+    queueDiscussionRound(conversation, revision, round, createdBy) {
+        const discussion = conversation.discussion;
+        return discussion.participants.flatMap((key, position) => {
+            const role = revision.body.roles.find(item => item.key === key);
+            if (!role)
+                return [];
+            return [this.queueTask({ projectId: conversation.project_id, title: `${excerpt(discussion.question, 80)} (round ${round})`, mode: 'discussion_turn',
+                    roleKey: key, bindingId: role.binding_id ?? (role.agent_ref ? this.store.team.ensureBinding(role.agent_ref).id : null), assignmentRevision: revision.revision,
+                    source: { discussion: conversation.id, round }, createdBy, conversationId: conversation.id, groupId: `${conversation.id}:r${round}`, groupPosition: position })];
+        });
+    }
+    /** Move a discussion on once the current round (or its summary) has finished. */
+    advanceDiscussion(conversationId) {
+        const conversation = this.store.room.conversation(conversationId);
+        const discussion = conversation?.discussion;
+        if (!conversation || !discussion || conversation.stopped_at || (discussion.state !== 'running' && discussion.state !== 'summarizing'))
+            return;
+        const group = discussion.state === 'running' ? `${conversation.id}:r${discussion.round}` : `${conversation.id}:summary`;
+        if (this.store.tasks.inGroup(group).some(task => !FINISHED.includes(task.state)))
+            return;
+        const revision = this.store.team.current(conversation.project_id);
+        this.store.tx(() => {
+            let next;
+            if (discussion.state === 'running' && discussion.round < discussion.max_rounds && revision) {
+                next = { ...discussion, round: discussion.round + 1 };
+                const updated = this.store.room.updateDiscussion(conversation.id, next);
+                this.queueDiscussionRound(updated, revision, next.round, 'conductor');
+            }
+            else if (discussion.state === 'running') {
+                const coordinator = revision?.body.roles.find(role => role.coordinator && role.agent_ref);
+                if (coordinator && revision) {
+                    next = { ...discussion, state: 'summarizing' };
+                    this.store.room.updateDiscussion(conversation.id, next);
+                    this.queueTask({ projectId: conversation.project_id, title: `Summary: ${excerpt(discussion.question, 80)}`, mode: 'discussion_turn', roleKey: coordinator.key,
+                        bindingId: coordinator.binding_id ?? this.store.team.ensureBinding(coordinator.agent_ref).id, assignmentRevision: revision.revision,
+                        source: { discussion: conversation.id, summary: true }, createdBy: 'conductor', conversationId: conversation.id, groupId: `${conversation.id}:summary` });
+                }
+                else {
+                    next = { ...discussion, state: 'done' };
+                    this.store.room.updateDiscussion(conversation.id, next);
+                    this.systemMessage(conversation.id, 'The discussion ended without a summary: the team has no bound coordinator.', {});
+                }
+            }
+            else {
+                next = { ...discussion, state: 'done' };
+                this.store.room.updateDiscussion(conversation.id, next);
+            }
+            this.store.emit(conversation.project_id, 'conversation.updated', { conversation: this.store.room.conversation(conversation.id) });
+        });
+        this.kick();
+    }
+    runningDiscussions() {
+        const rows = this.store.db.prepare("SELECT id FROM conversations WHERE kind = 'discussion' AND stopped_at IS NULL").all();
+        return rows.map(row => this.store.room.conversation(row.id)).filter(item => item.discussion?.state === 'running' || item.discussion?.state === 'summarizing');
+    }
+    /** Stop a conversation: unstarted turns are cancelled here, started ones are cancelled through Magnus. */
+    async stopConversation(conversationId) {
+        const tasks = this.store.tasks.inConversation(conversationId).filter(task => !FINISHED.includes(task.state));
+        for (const task of tasks) {
+            if (!task.ardent.task_id)
+                this.cancelLocally(task, 'The conversation was stopped.');
+            else
+                await this.cancel(task).catch(error => this.options.logger.warn('Cancel on stop failed', { task_id: task.id, error: errorText(error) }));
+        }
+    }
+    /** Cancel a task. An unstarted one is cancelled here; a started one through Magnus, and its final record follows. */
+    async cancel(task) {
+        if (FINISHED.includes(task.state))
+            throw new ConductorError('The task has already finished', 409, 'TASK_FINISHED');
+        if (!task.ardent.task_id || !task.ardent.agent_ref) {
+            this.cancelLocally(task, 'Cancelled before it started.');
+            return this.store.tasks.get(task.id);
+        }
+        const record = await this.magnusCall(() => this.magnus.cancelTask(task.ardent.agent_ref, task.ardent.task_id));
+        const parsed = z.object({ id: z.string(), state: z.string(), result: z.string().nullable().optional(), error: z.string().nullable().optional() }).loose().safeParse(record);
+        if (parsed.success && ARDENT_FINISHED.includes(parsed.data.state))
+            await this.finish(task.id, parsed.data);
+        return this.store.tasks.get(task.id);
+    }
+    /** Pause a task at its next step boundary (studio >= 2), or hold an unstarted one. */
+    async pause(task) {
+        if (FINISHED.includes(task.state))
+            throw new ConductorError('The task has already finished', 409, 'TASK_FINISHED');
+        if (task.state === 'paused' || task.state === 'pausing')
+            return task;
+        if (!task.ardent.task_id || !task.ardent.agent_ref) {
+            return this.store.tx(() => {
+                const held = this.store.tasks.setState(task.id, 'paused', { ...(task.outcome ?? {}), held: true });
+                this.store.emit(task.project_id, 'task.updated', this.taskEvent(held));
+                this.refreshActivity(task.project_id, task.binding_id);
+                return held;
+            });
+        }
+        await this.magnusCall(() => this.magnus.pauseTask(task.ardent.agent_ref, task.ardent.task_id));
+        return this.store.tx(() => {
+            const current = this.store.tasks.get(task.id);
+            if (current.state === 'paused' || FINISHED.includes(current.state))
+                return current;
+            const pausing = this.store.tasks.setState(task.id, 'pausing');
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(pausing));
+            this.refreshActivity(task.project_id, task.binding_id);
+            return pausing;
+        });
+    }
+    async resume(task) {
+        if (task.state !== 'paused' && task.state !== 'pausing')
+            throw new ConductorError('The task is not paused', 409, 'TASK_NOT_PAUSED');
+        if (!task.ardent.task_id || !task.ardent.agent_ref) {
+            const queued = this.store.tx(() => {
+                const next = this.store.tasks.setState(task.id, 'queued');
+                this.store.emit(task.project_id, 'task.updated', this.taskEvent(next));
+                this.refreshActivity(task.project_id, task.binding_id);
+                return next;
+            });
+            this.kick();
+            return queued;
+        }
+        const answer = await this.magnusCall(() => this.magnus.resumeTask(task.ardent.agent_ref, task.ardent.task_id));
+        return this.store.tx(() => {
+            const current = this.store.tasks.get(task.id);
+            if (FINISHED.includes(current.state))
+                return current;
+            const next = this.store.tasks.setState(task.id, answer.state === 'queued' ? 'queued' : 'running');
+            this.store.emit(task.project_id, 'task.updated', this.taskEvent(next));
+            this.refreshActivity(task.project_id, task.binding_id);
+            return next;
+        });
+    }
+    async magnusCall(call) {
+        try {
+            return await call();
+        }
+        catch (error) {
+            if (error instanceof MagnusError) {
+                if (error.code === 'AGENT_UPGRADE_REQUIRED')
+                    throw new ConductorError(error.message, 409, 'AGENT_UPGRADE_REQUIRED');
+                if (error.status === 409)
+                    throw new ConductorError(`Ardent refused: ${error.message}`, 409, 'ARDENT_CONFLICT');
+                if (error.status === 404)
+                    throw new ConductorError('Ardent has no record of this task', 404, 'ARDENT_TASK_NOT_FOUND');
+            }
+            throw new ConductorError(`Magnus could not reach the agent: ${errorText(error)}`, 503, 'MAGNUS_UNAVAILABLE');
+        }
+    }
+    // ── Presence and activity ──
+    /** Probe agent status every 30 s. The probe only records reachability; activity is then derived as for any change. */
+    async probe() {
+        if (this.stopped)
+            return;
+        let profiles;
+        try {
+            profiles = await this.options.agents.profiles();
+        }
+        catch {
+            profiles = undefined;
+        }
+        const byRef = new Map((profiles ?? []).map(profile => [`${profile.nodeId}~${profile.id}`, profile]));
+        for (const project of this.store.projects.list({ status: 'active' })) {
+            const revision = this.store.team.current(project.id);
+            if (!revision)
+                continue;
+            this.store.tx(() => {
+                for (const role of revision.body.roles) {
+                    if (!role.agent_ref)
+                        continue;
+                    const profile = byRef.get(role.agent_ref);
+                    this.presence.set(role.agent_ref, !profiles ? 'unreachable' : profile && isAvailable(profile) ? 'available' : 'offline');
+                    this.refreshActivity(project.id, role.binding_id ?? this.store.team.ensureBinding(role.agent_ref).id);
+                }
+            });
+        }
+    }
+    /**
+     * Derive a binding's activity from the last probe and its real records (docs/CONDUCTOR.md#activity),
+     * and announce it when it changed. Call inside a transaction, after the records changed.
+     */
+    refreshActivity(projectId, bindingId) {
+        if (!bindingId)
+            return;
+        const binding = this.store.db.prepare('SELECT agent_ref FROM agent_bindings WHERE id = ?').get(bindingId);
+        if (!binding)
+            return;
+        const tasks = this.store.tasks.list(projectId).filter(task => task.binding_id === bindingId);
+        const now = this.store.clock.now();
+        const deliveringMs = this.options.deliveringMs ?? 20_000;
+        const delivered = this.store.review.latestDeliveredBy(projectId, bindingId);
+        const activity = deriveActivity({
+            probe: this.presence.get(binding.agent_ref),
+            tasks,
+            blockerOf: task => this.store.tasks.groupBefore(task).find(item => !FINISHED.includes(item.state)),
+            handedOff: this.store.tasks.handedOffFrom(projectId, new Set(tasks.map(task => task.id))).filter(task => task.binding_id !== bindingId),
+            message: id => this.store.room.message(id),
+            roleName: task => this.roleName(task),
+            delivered, now, deliveringMs,
+        });
+        this.writeActivity(projectId, bindingId, binding.agent_ref, activity.state, activity.label, activity.source);
+        // Delivering is transient: derive again when its window ends.
+        const remaining = delivered ? Date.parse(delivered.received_at) + deliveringMs - now.getTime() : 0;
+        const key = `${projectId}:${bindingId}`;
+        if (remaining > 0 && !this.deliveringTimers.has(key) && !this.stopped) {
+            const timer = setTimeout(() => {
+                this.deliveringTimers.delete(key);
+                if (!this.stopped)
+                    this.store.tx(() => this.refreshActivity(projectId, bindingId));
+            }, remaining + 5);
+            timer.unref();
+            this.deliveringTimers.set(key, timer);
+        }
+    }
+    writeActivity(projectId, bindingId, agentRef, state, label, source) {
+        const since = this.store.clock.now().toISOString();
+        if (this.store.room.changeActivity({ project_id: projectId, binding_id: bindingId, state, label, source, since })) {
+            this.store.emit(projectId, 'presence.updated', { binding_id: bindingId, agent_ref: agentRef, state, label, source, since });
+        }
+    }
+    // ── Shared record helpers ──
+    agentAuthor(task) {
+        return task.binding_id ? { kind: 'agent', binding_id: task.binding_id, role_key: task.role_key } : { kind: 'system' };
+    }
+    roleName(task) {
+        const revision = task.assignment_revision ? this.store.team.revision(task.project_id, task.assignment_revision) : this.store.team.current(task.project_id);
+        return revision?.body.roles.find(role => role.key === task.role_key)?.name ?? task.role_key ?? 'An agent';
+    }
+    /** A Studio note in the room. Call inside a transaction. */
+    systemMessage(conversationId, text, links, replyTo) {
+        const message = this.store.room.addMessage({ conversationId, author: { kind: 'system' }, kind: 'system', bodyMd: text, replyTo: replyTo ?? null, links, state: 'complete' });
+        this.store.emit(message.project_id, 'message.created', this.messageEvent(message));
+        return message;
+    }
+    messageEvent(message) {
+        return { message };
+    }
+    taskEvent(task) {
+        return { task: publicTask(task) };
+    }
+}
+/** A task as the browser sees it (no mission JSON). */
+export function publicTask(task) {
+    return {
+        id: task.id, project_id: task.project_id, title: task.title, mode: task.mode, role_key: task.role_key, binding_id: task.binding_id,
+        assignment_revision: task.assignment_revision, conversation_id: task.conversation_id, trigger_message_id: task.trigger_message_id,
+        instructions_md: task.instructions_md, source: task.source, state: task.state, dispatch: task.dispatch,
+        ardent: { agent_ref: task.ardent.agent_ref, task_id: task.ardent.task_id, session_id: task.ardent.session_id },
+        outcome: task.outcome ?? null, reassigned_from: task.reassigned_from, group_id: task.group_id, group_position: task.group_position,
+        created_by: task.created_by, created_at: task.created_at, updated_at: task.updated_at, finished_at: task.finished_at,
+    };
+}