@hivemagnus/ardent-studio 0.0.0-stage → 0.1.0

package/dist/conductor/follower.d.ts

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { ardentTaskDoneEventSchema, type ArdentTaskEvent, type MagnusClient } from '../clients/magnus.js';
+import type { Logger } from '../logger.js';
+export type FollowerMagnus = Pick<MagnusClient, 'streamTask' | 'taskEvents' | 'task'>;
+export type DoneRecord = z.infer<typeof ardentTaskDoneEventSchema>;
+/** Ardent states after which a task's turn is over. Ardent keeps `input_required` out of its stream's done set, so it is listed here. */
+export declare const ARDENT_FINISHED: readonly ["completed", "partial", "failed", "cancelled", "unknown", "input_required"];
+export interface FollowerHooks {
+    /** The journal sequence already handled. */
+    cursor(): number;
+    text(step: number, text: string, mode: 'replace' | 'append'): void;
+    /** Handle and persist one journal event. Returns true when the event ends the turn. */
+    event(event: ArdentTaskEvent): Promise<boolean> | boolean;
+    done(record: DoneRecord): Promise<void>;
+}
+export interface FollowerOptions {
+    pollMinMs?: number;
+    pollMaxMs?: number;
+    /** How long to poll before trying the stream again. */
+    pollWindowMs?: number;
+    /** Pause between a clean stream end and the reconnect. */
+    reconnectMs?: number;
+}
+export declare class TaskFollower {
+    private readonly magnus;
+    private readonly agentRef;
+    private readonly ardentTaskId;
+    private readonly hooks;
+    private readonly logger;
+    private readonly abort;
+    private running;
+    private readonly pollMin;
+    private readonly pollMax;
+    private readonly pollWindow;
+    private readonly reconnect;
+    /** How the follower currently reads the task: for tests and diagnostics. */
+    mode: 'stream' | 'poll' | 'done';
+    constructor(magnus: FollowerMagnus, agentRef: string, ardentTaskId: string, hooks: FollowerHooks, logger: Logger, options?: FollowerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private get stopped();
+    private loop;
+    /** One SSE subscription. True when the task finished. */
+    private stream;
+    /** Poll the journal and the task. True when the task finished; false to try the stream again. */
+    private poll;
+    private sleep;
+}

package/dist/conductor/follower.js

@@ -0,0 +1,154 @@
+// Follows one Ardent task through Magnus: one SSE subscription (journal events and live reply
+// text) resumed after the last handled journal sequence. Ardent ends a stream after 60 seconds,
+// so a clean end reconnects. When the stream fails, the follower polls the journal and the task
+// every 1 to 5 seconds, then tries the stream again.
+import { setTimeout as delay } from 'node:timers/promises';
+import { ardentTaskDoneEventSchema, ardentTaskEventSchema, ardentTaskTextEventSchema, MagnusError } from '../clients/magnus.js';
+/** Ardent states after which a task's turn is over. Ardent keeps `input_required` out of its stream's done set, so it is listed here. */
+export const ARDENT_FINISHED = ['completed', 'partial', 'failed', 'cancelled', 'unknown', 'input_required'];
+export class TaskFollower {
+    magnus;
+    agentRef;
+    ardentTaskId;
+    hooks;
+    logger;
+    abort = new AbortController();
+    running;
+    pollMin;
+    pollMax;
+    pollWindow;
+    reconnect;
+    /** How the follower currently reads the task: for tests and diagnostics. */
+    mode = 'stream';
+    constructor(magnus, agentRef, ardentTaskId, hooks, logger, options = {}) {
+        this.magnus = magnus;
+        this.agentRef = agentRef;
+        this.ardentTaskId = ardentTaskId;
+        this.hooks = hooks;
+        this.logger = logger;
+        this.pollMin = options.pollMinMs ?? 1_000;
+        this.pollMax = options.pollMaxMs ?? 5_000;
+        this.pollWindow = options.pollWindowMs ?? 30_000;
+        this.reconnect = options.reconnectMs ?? 250;
+    }
+    start() {
+        this.running ??= this.loop().catch(error => {
+            this.logger.error('Task follower stopped unexpectedly', { task_id: this.ardentTaskId, error: error instanceof Error ? error.message : 'unknown' });
+        });
+        return this.running;
+    }
+    async stop() {
+        this.abort.abort();
+        await this.running;
+    }
+    get stopped() { return this.abort.signal.aborted; }
+    async loop() {
+        while (!this.stopped) {
+            this.mode = 'stream';
+            let failed = false;
+            try {
+                if (await this.stream()) {
+                    this.mode = 'done';
+                    return;
+                }
+            }
+            catch (error) {
+                if (this.stopped)
+                    return;
+                failed = true;
+                this.logger.warn('Task stream failed; polling', { task_id: this.ardentTaskId, error: error instanceof Error ? error.message.slice(0, 200) : 'unknown' });
+            }
+            if (this.stopped)
+                return;
+            if (failed) {
+                this.mode = 'poll';
+                if (await this.poll()) {
+                    this.mode = 'done';
+                    return;
+                }
+            }
+            else {
+                await this.sleep(this.reconnect);
+            }
+        }
+    }
+    /** One SSE subscription. True when the task finished. */
+    async stream() {
+        for await (const message of this.magnus.streamTask(this.agentRef, this.ardentTaskId, { after: this.hooks.cursor(), signal: this.abort.signal })) {
+            if (this.stopped)
+                return false;
+            if (message.event === 'task.text' || message.event === 'task.delta') {
+                const parsed = ardentTaskTextEventSchema.safeParse(parseJson(message.data));
+                if (parsed.success)
+                    this.hooks.text(parsed.data.step, parsed.data.text, message.event === 'task.text' ? 'replace' : 'append');
+            }
+            else if (message.event === 'task.event') {
+                const parsed = ardentTaskEventSchema.safeParse(parseJson(message.data));
+                if (!parsed.success)
+                    continue;
+                if (await this.hooks.event(parsed.data))
+                    return true;
+            }
+            else if (message.event === 'task.done') {
+                const parsed = ardentTaskDoneEventSchema.safeParse(parseJson(message.data));
+                await this.hooks.done(parsed.success ? parsed.data : { id: this.ardentTaskId, state: 'unknown', error: 'Ardent sent an unreadable final task record' });
+                return true;
+            }
+        }
+        return false;
+    }
+    /** Poll the journal and the task. True when the task finished; false to try the stream again. */
+    async poll() {
+        const until = Date.now() + this.pollWindow;
+        let interval = this.pollMin;
+        while (!this.stopped && Date.now() < until) {
+            try {
+                // A journal page Magnus cannot relay (an error, or a page over its size limit) must not
+                // hide that the task finished: the task record is read either way.
+                let events = [];
+                let unreadable;
+                try {
+                    events = await this.magnus.taskEvents(this.agentRef, this.ardentTaskId, this.hooks.cursor(), { signal: this.abort.signal });
+                }
+                catch (error) {
+                    if (error instanceof MagnusError && error.status === 404)
+                        throw error;
+                    unreadable = error;
+                }
+                for (const event of events)
+                    if (await this.hooks.event(event))
+                        return true;
+                const task = await this.magnus.task(this.agentRef, this.ardentTaskId, { signal: this.abort.signal });
+                if (ARDENT_FINISHED.includes(task.state)) {
+                    await this.hooks.done(task);
+                    return true;
+                }
+                if (unreadable !== undefined)
+                    throw unreadable;
+                interval = events.length ? this.pollMin : Math.min(this.pollMax, interval * 2);
+            }
+            catch (error) {
+                if (this.stopped)
+                    return false;
+                if (error instanceof MagnusError && error.status === 404) {
+                    await this.hooks.done({ id: this.ardentTaskId, state: 'unknown', error: 'Ardent has no record of this task' });
+                    return true;
+                }
+                interval = this.pollMax;
+            }
+            await this.sleep(interval);
+        }
+        return false;
+    }
+    async sleep(ms) {
+        await delay(ms, undefined, { signal: this.abort.signal }).catch(() => undefined);
+    }
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/conductor/live.d.ts

@@ -0,0 +1,23 @@
+import type { EventBus } from '../events/bus.js';
+export interface LiveEntry {
+    projectId: string;
+    step: number;
+    text: string;
+}
+export declare class LiveText {
+    private readonly bus;
+    private readonly entries;
+    constructor(bus: EventBus);
+    /** A step started or a stream (re)connected: the text is the whole current step. */
+    replace(projectId: string, messageId: string, step: number, text: string): void;
+    /** More text for the current step. A delta for another step starts that step. */
+    append(projectId: string, messageId: string, step: number, text: string): void;
+    get(messageId: string): LiveEntry | undefined;
+    clear(messageId: string): void;
+    /** Current text of every streaming message in a project. */
+    snapshot(projectId: string): Array<{
+        message_id: string;
+        step: number;
+        text: string;
+    }>;
+}

package/dist/conductor/live.js

@@ -0,0 +1,32 @@
+export class LiveText {
+    bus;
+    entries = new Map();
+    constructor(bus) {
+        this.bus = bus;
+    }
+    /** A step started or a stream (re)connected: the text is the whole current step. */
+    replace(projectId, messageId, step, text) {
+        this.entries.set(messageId, { projectId, step, text });
+        this.bus.publishEphemeral(projectId, 'message.delta', { message_id: messageId, text, mode: 'replace', step });
+    }
+    /** More text for the current step. A delta for another step starts that step. */
+    append(projectId, messageId, step, text) {
+        const current = this.entries.get(messageId);
+        if (current && current.step !== step) {
+            this.replace(projectId, messageId, step, text);
+            return;
+        }
+        this.entries.set(messageId, { projectId, step, text: (current?.text ?? '') + text });
+        this.bus.publishEphemeral(projectId, 'message.delta', { message_id: messageId, text, mode: 'append', step });
+    }
+    get(messageId) {
+        return this.entries.get(messageId);
+    }
+    clear(messageId) {
+        this.entries.delete(messageId);
+    }
+    /** Current text of every streaming message in a project. */
+    snapshot(projectId) {
+        return [...this.entries].filter(([, entry]) => entry.projectId === projectId).map(([id, entry]) => ({ message_id: id, step: entry.step, text: entry.text }));
+    }
+}

package/dist/conductor/prompting.d.ts

@@ -0,0 +1,74 @@
+import type { ArdentContextItem, ArdentTeamMission } from '../clients/magnus.js';
+import type { Project } from '../db/repos/projects.js';
+import type { Message } from '../db/repos/room.js';
+import type { StudioTask } from '../db/repos/tasks.js';
+import type { TeamBody } from '../db/repos/team.js';
+export type TeamRole = TeamBody['roles'][number];
+/** Ardent's limits: a mission objective and a task prompt are at most 16000 characters. */
+export declare const PROMPT_LIMIT = 16000;
+export interface AttachmentText {
+    name: string;
+    mime: string;
+    text: string | null;
+}
+export interface TurnInput {
+    project: Pick<Project, 'id' | 'name' | 'brief_md' | 'audience' | 'constraints' | 'deliverables'>;
+    team: Pick<TeamBody, 'roles' | 'relationships'>;
+    role: TeamRole;
+    task: Pick<StudioTask, 'id' | 'mode' | 'title' | 'instructions_md' | 'source'>;
+    /** No earlier turn in this Ardent session (or no session at all): include the brief and roster. */
+    firstTurn: boolean;
+    /** Room messages the agent has not been shown, oldest first, without the trigger. */
+    unseen: readonly Message[];
+    /** The message this turn answers, when there is one. */
+    trigger: Message | undefined;
+    /** Readable names for message authors and addressees. */
+    names: {
+        author: (message: Message) => string;
+        role: (key: string) => string;
+    };
+    attachments: readonly AttachmentText[];
+    discussion?: {
+        question: string;
+        desired_output: string;
+        round: number;
+        max_rounds: number;
+        summary: boolean;
+        transcript: readonly Message[];
+    } | undefined;
+    /** Further material for this turn, such as the review comments of a revision request. */
+    extra?: ReadonlyArray<{
+        title: string;
+        text: string;
+        mime?: string;
+    }> | undefined;
+}
+export interface ComposedTurn {
+    /** Mission objective (missions) — at most PROMPT_LIMIT characters. */
+    objective: string;
+    /** Large material for a mission, within Ardent's 64 KiB. */
+    contextItems: ArdentContextItem[];
+    /** The same turn as one prompt for task-submit, with large material shortened to fit. */
+    prompt: string;
+}
+/** Compose one turn. Large material becomes context items for a mission and is shortened for a plain prompt. */
+export declare function composeTurn(input: TurnInput): ComposedTurn;
+/** Mission tools a role may use. A hand-off tool only when the team gives the role someone to hand to. */
+export declare function missionResources(input: {
+    team: Pick<TeamBody, 'relationships'>;
+    role: TeamRole;
+    hivememProjectId: string;
+}): string[];
+/** Relationship types along which Studio starts a requested hand-off. */
+export declare const HANDOFF_EDGES: readonly string[];
+/** The TeamMission for a Studio task: constraints from the project, criteria from the request. */
+export declare function buildMission(input: {
+    task: Pick<StudioTask, 'id' | 'mode' | 'title' | 'assignment_revision'> & {
+        source?: Record<string, unknown>;
+    };
+    project: Pick<Project, 'name' | 'constraints' | 'deliverables'>;
+    team: Pick<TeamBody, 'relationships'>;
+    role: TeamRole;
+    hivememProjectId: string;
+    now: Date;
+}): ArdentTeamMission;

package/dist/conductor/prompting.js

@@ -0,0 +1,177 @@
+import { ARDENT_CONTEXT_ITEMS_MAX_BYTES } from '../clients/magnus.js';
+/** Ardent's limits: a mission objective and a task prompt are at most 16000 characters. */
+export const PROMPT_LIMIT = 16_000;
+/** Inline sizes before material moves into context items. */
+const INLINE_BRIEF = 3_000;
+const INLINE_ROOM = 6_000;
+const ITEM_TEXT_LIMIT = 24_000;
+const clip = (text, max) => text.length <= max ? text : `${text.slice(0, Math.max(0, max - 15)).trimEnd()}\n[…shortened]`;
+const bytes = (text) => Buffer.byteLength(text, 'utf8');
+function renderMessage(message, names) {
+    const to = message.addressees.length ? ` → ${message.addressees.map(names.role).join(', ')}` : '';
+    return `[${names.author(message)}${to}] ${message.body_md.trim() || '(no text)'}`;
+}
+function roleSection(role) {
+    const lines = [`You are ${role.name} (role key "${role.key}")${role.coordinator ? ', the team coordinator' : ''}.`];
+    if (role.responsibilities_md.trim())
+        lines.push(`Responsibilities:\n${role.responsibilities_md.trim()}`);
+    if (role.instructions_md.trim())
+        lines.push(`Instructions for this project:\n${role.instructions_md.trim()}`);
+    if (role.contributions.length)
+        lines.push(`You contribute: ${role.contributions.join('; ')}.`);
+    if (role.deliverables.length)
+        lines.push(`You deliver: ${role.deliverables.join('; ')}.`);
+    return lines.join('\n');
+}
+function rosterSection(input) {
+    const lines = input.team.roles.map(role => `- ${role.name} ("${role.key}")${role.coordinator ? ', coordinator' : ''}${role.agent_ref ? '' : ' (no agent bound)'}`);
+    const edges = input.team.relationships.filter(edge => edge.from === input.role.key || edge.to === input.role.key)
+        .map(edge => `- ${input.names.role(edge.from)} ${edge.type.replace(/_/g, ' ')} ${input.names.role(edge.to)}`);
+    return [`Team:\n${lines.join('\n')}`, edges.length ? `Your working relationships:\n${edges.join('\n')}` : ''].filter(Boolean).join('\n');
+}
+function projectSection(input, brief) {
+    const project = input.project;
+    const lines = [`Project: ${project.name}`];
+    if (project.audience)
+        lines.push(`Audience: ${project.audience}`);
+    if (project.constraints.length)
+        lines.push(`Constraints:\n${project.constraints.map(item => `- ${item}`).join('\n')}`);
+    if (project.deliverables.length) {
+        lines.push(`Requested deliverables:\n${project.deliverables.map(item => `- ${item.name} (${item.formats.join(', ')})${item.producer_role_key ? ` by ${input.names.role(item.producer_role_key)}` : ''}`).join('\n')}`);
+    }
+    if (brief)
+        lines.push(`Brief:\n${brief}`);
+    return lines.join('\n');
+}
+function requestSection(input) {
+    const { task, trigger, names, discussion } = input;
+    if (discussion) {
+        const head = `Discussion question: ${discussion.question}\nDesired output: ${discussion.desired_output.replace(/_/g, ' ')}.`;
+        return discussion.summary
+            ? `${head}\nThe discussion has ended. As coordinator, summarize it as the desired output. Name open disagreements; do not add positions nobody took.`
+            : `${head}\nRound ${discussion.round} of ${discussion.max_rounds}. Give your contribution from your role in a few short paragraphs, responding to what others said.`;
+    }
+    if (typeof task.source.answer_to === 'string' && trigger) {
+        const question = typeof task.source.question === 'string' ? task.source.question : 'your question';
+        return `${names.author(trigger)} answered ${JSON.stringify(question)}:\n${trigger.body_md.trim()}`;
+    }
+    if (task.mode === 'turn' && trigger)
+        return `Message for you from ${names.author(trigger)}:\n${trigger.body_md.trim()}`;
+    const lines = [`${task.mode === 'revision' ? 'Revision request' : task.mode === 'review' ? 'Review request' : 'Assignment'}: ${task.title}`];
+    if (task.instructions_md.trim())
+        lines.push(task.instructions_md.trim());
+    if (typeof task.source.handoff_from === 'string')
+        lines.push(`Handed off by ${names.role(task.source.handoff_from)}.`);
+    if (trigger)
+        lines.push(`From the message by ${names.author(trigger)}:\n${trigger.body_md.trim()}`);
+    return lines.join('\n');
+}
+/** Compose one turn. Large material becomes context items for a mission and is shortened for a plain prompt. */
+export function composeTurn(input) {
+    const items = [];
+    let itemBytes = 0;
+    const addItem = (title, text, mime = 'text/markdown') => {
+        const body = clip(text, ITEM_TEXT_LIMIT);
+        const size = bytes(title + body);
+        if (!body.trim() || itemBytes + size > ARDENT_CONTEXT_ITEMS_MAX_BYTES || items.length >= 64)
+            return false;
+        items.push({ title, mime, text: body });
+        itemBytes += size;
+        return true;
+    };
+    const brief = input.firstTurn ? input.project.brief_md.trim() : '';
+    const briefInline = brief.length <= INLINE_BRIEF ? brief : '';
+    const briefItem = brief && !briefInline ? addItem('Project brief', brief) : false;
+    const transcript = input.discussion && !input.discussion.summary ? [] : input.unseen;
+    const room = transcript.map(message => renderMessage(message, input.names)).join('\n');
+    const roomInline = room.length <= INLINE_ROOM ? room : '';
+    const roomItem = room && !roomInline ? addItem('Room messages since your last turn', room) : false;
+    const discussionRoom = input.discussion ? input.discussion.transcript.map(message => renderMessage(message, input.names)).join('\n') : '';
+    const discussionInline = discussionRoom.length <= INLINE_ROOM ? discussionRoom : '';
+    const discussionItem = discussionRoom && !discussionInline ? addItem('Discussion so far', discussionRoom) : false;
+    const attachmentNotes = [];
+    for (const attachment of input.attachments) {
+        if (attachment.text !== null && addItem(`Attachment: ${attachment.name}`, attachment.text, attachment.mime.startsWith('text/') ? attachment.mime : 'text/plain')) {
+            attachmentNotes.push(`- ${attachment.name} (in context items)`);
+        }
+        else {
+            attachmentNotes.push(`- ${attachment.name} (${attachment.mime}; not included as text)`);
+        }
+    }
+    const extraNotes = [];
+    const extraInline = [];
+    for (const item of input.extra ?? []) {
+        if (addItem(item.title, item.text, item.mime))
+            extraNotes.push(`- ${item.title}`);
+        extraInline.push(`${item.title}:\n${clip(item.text, 3_000)}`);
+    }
+    const sections = (mode, budget) => [
+        roleSection(input.role),
+        input.firstTurn ? projectSection(input, budget.brief) : `Project: ${input.project.name}`,
+        input.firstTurn ? rosterSection(input) : '',
+        budget.room ? `Room messages since your last turn:\n${budget.room}` : '',
+        budget.discussion ? `Discussion so far:\n${budget.discussion}` : '',
+        attachmentNotes.length ? `Attachments:\n${attachmentNotes.join('\n')}` : '',
+        mode === 'mission' && extraNotes.length ? `In context items:\n${extraNotes.join('\n')}` : '',
+        mode === 'prompt' && extraInline.length ? extraInline.join('\n\n') : '',
+        requestSection(input),
+        mode === 'mission'
+            ? 'Reply to the team in plain prose; your reply is posted in the room as your message.'
+            : 'Reply to the team in plain prose; your reply is posted in the room as your message. You cannot hand work to other roles or save files in this turn; say what you need instead.',
+    ].filter(Boolean).join('\n\n');
+    const objective = clip(sections('mission', {
+        brief: briefInline || (briefItem ? '(in the context item "Project brief")' : clip(brief, INLINE_BRIEF)),
+        room: roomInline || (roomItem ? '(in the context item "Room messages since your last turn")' : clip(room.slice(-INLINE_ROOM), INLINE_ROOM)),
+        discussion: discussionInline || (discussionItem ? '(in the context item "Discussion so far")' : clip(discussionRoom.slice(-INLINE_ROOM), INLINE_ROOM)),
+    }), PROMPT_LIMIT);
+    // A plain prompt has no context items: keep the newest room text and the start of the brief.
+    const fixed = sections('prompt', { brief: '', room: '', discussion: '' }).length;
+    const spare = Math.max(0, PROMPT_LIMIT - fixed - 200);
+    const roomShare = Math.floor(spare * (brief ? 0.5 : 1));
+    const tail = (text, max) => text.length <= max ? text : `[…earlier messages left out]\n${text.slice(text.length - max + 32)}`;
+    const prompt = clip(sections('prompt', {
+        brief: brief ? clip(brief, Math.max(200, spare - Math.min(roomShare, room.length + discussionRoom.length))) : '',
+        room: room ? tail(room, Math.max(200, Math.floor(roomShare / (discussionRoom ? 2 : 1)))) : '',
+        discussion: discussionRoom ? tail(discussionRoom, Math.max(200, Math.floor(roomShare / 2))) : '',
+    }), PROMPT_LIMIT);
+    return { objective, contextItems: items, prompt };
+}
+/** Mission tools a role may use. A hand-off tool only when the team gives the role someone to hand to. */
+export function missionResources(input) {
+    const resources = ['tool:team_ask_user', 'tool:team_propose_decision', 'tool:artifact_write', 'tool:document_render', 'tool:development_note'];
+    if (input.team.relationships.some(edge => edge.from === input.role.key && HANDOFF_EDGES.includes(edge.type)))
+        resources.unshift('tool:team_handoff');
+    resources.push(`project:${input.hivememProjectId}`);
+    return resources;
+}
+/** Relationship types along which Studio starts a requested hand-off. */
+export const HANDOFF_EDGES = ['delegates_to', 'hands_off_to'];
+const MISSION_HOURS = 6;
+const missionLine = (text) => {
+    let line = text.replace(/\s+/g, ' ').trim();
+    while (bytes(line) > 1000)
+        line = line.slice(0, -16);
+    return line;
+};
+/** The TeamMission for a Studio task: constraints from the project, criteria from the request. */
+export function buildMission(input) {
+    const { task, role, project } = input;
+    const unique = (values) => [...new Set(values.map(missionLine).filter(Boolean))].slice(0, 32);
+    const criteria = task.mode === 'turn' ? ['Reply to the latest message addressed to you, in your role']
+        : task.mode === 'discussion_turn' ? ['Contribute your view to the discussion round, in your role']
+            : [`Complete: ${task.title}`];
+    const expected = task.mode === 'revision' && typeof task.source?.deliverable_name === 'string' ? [task.source.deliverable_name]
+        : task.mode === 'assignment' ? project.deliverables.filter(item => item.producer_role_key === role.key).map(item => item.name)
+            : [];
+    return {
+        id: task.id,
+        revision: Math.max(1, task.assignment_revision ?? 1),
+        parent_task: null,
+        constraints: unique([`Project: ${project.name}`, `Role: ${role.name}`, ...project.constraints]),
+        allowed_actions: ['observe', 'analyze', 'create_artifact', 'create_draft'],
+        resources: missionResources(input),
+        deadline: Math.floor(input.now.getTime() / 1000) + MISSION_HOURS * 3600,
+        acceptance_criteria: unique(criteria),
+        expected_artifacts: unique(expected),
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,52 @@
+import { type IdentityLink } from './auth/links.js';
+export declare const DEFAULT_PORT = 8097;
+export declare const DEFAULT_MAX_BLOB_BYTES: number;
+export declare const DEFAULT_EVENT_RETENTION_DAYS = 30;
+export interface ServiceClientConfig {
+    url: string;
+    clientId: string;
+    clientSecret: string;
+    /** OAuth scope for the client_credentials request. Oathweave grants nothing without one. */
+    scope: string;
+}
+export interface Config {
+    host: string;
+    port: number;
+    dataDir: string;
+    maxBlobBytes: number;
+    eventRetentionDays: number;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+    oathweave: {
+        issuer: string;
+        jwksUrl: string;
+        userinfoUrl: string;
+        tokenUrl: string;
+        identities: IdentityLink[];
+    };
+    magnus: ServiceClientConfig;
+    hivemem: ServiceClientConfig;
+    chattermost: {
+        webhookUrl: string;
+    } | undefined;
+}
+export declare class ConfigError extends Error {
+    readonly issues: ReadonlyArray<{
+        name: string;
+        message: string;
+    }>;
+    constructor(issues: ReadonlyArray<{
+        name: string;
+        message: string;
+    }>);
+}
+/** Every variable the service reads. Secrets are marked so tooling never prints their values. */
+export declare const ENV_CATALOG: ReadonlyArray<{
+    name: string;
+    required: boolean;
+    secret: boolean;
+    description: string;
+}>;
+type Env = Record<string, string | undefined>;
+/** Read and validate the environment. Throws ConfigError naming every problem; values are never echoed. */
+export declare function loadConfig(env?: Env): Config;
+export {};