@hypercarrier/pi-team-durable 0.0.0-stage → 0.1.0-rc.1

package/dist/authority/runtime.d.ts

@@ -0,0 +1,70 @@
+import type { Context } from '@earendil-works/chord/context';
+import { type Harness, type Extension } from '@earendil-works/pi-durable';
+import { type CoreApi, type CoreOptions } from './tools.ts';
+import type { AbortRun } from './interrupt.ts';
+import { type ObservationPortResolver } from './observation.ts';
+import { type StopIntent } from './state.ts';
+export interface StopPlan {
+    id: string;
+    conversations?: string[];
+    tasks?: string[];
+}
+export type StopOutcome = {
+    status: 'settled';
+    tasks: Record<string, string>;
+} | {
+    status: 'failed';
+    tasks: Record<string, string>;
+    error: string;
+};
+export declare const stopPlan: (id: string, intent: StopIntent) => StopPlan;
+export declare function pendingStops(harness: Harness, context: Context): Promise<StopPlan[]>;
+export declare function confirmStop(harness: Harness, id: string, outcome: StopOutcome, context: Context, now?: () => number): Promise<void>;
+/** Called by NodePlugin.closing after its own lead Close intent is stored. */
+export declare function closing(harness: Harness, conversationId: string, context: Context): Promise<StopPlan[]>;
+export interface RuntimeOptions extends Pick<CoreOptions, 'modelRoles' | 'defaultModelRole' | 'catalog' | 'goalMaxLength' | 'resolveModelRole'> {
+    observationPort: ObservationPortResolver;
+    abortRun: AbortRun;
+    stop: (api: CoreApi, plans: StopPlan[], context: Context) => Promise<StopOutcome[]>;
+}
+export declare function createTeamRuntime(options: RuntimeOptions): {
+    core: {
+        lead: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
+        worker: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
+        execute: (name: import("./contracts.ts").ToolName, role: import("./contracts.ts").Role, input: unknown, api: CoreApi, context: Context) => Promise<import("./state.ts").Result>;
+        contract: import("./contracts.ts").Contract;
+    };
+    lead: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>>;
+    worker: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>>;
+    mechanics: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>>;
+    observation: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>>;
+    extensions: Extension<import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>>[];
+    tasks: {
+        WorkerAnchor: import("@earendil-works/pi-durable").Task<null, {
+            phase: "hold";
+        }, null, object>;
+        Deliver: import("@earendil-works/pi-durable").Task<import("./delivery.ts").DeliveryInput, {
+            phase: "interrupt";
+        } | {
+            phase: "submit";
+        } | {
+            phase: "settle";
+            submissionId: import("@earendil-works/pi-durable").SubmissionId;
+        }, null, object>;
+        Notify: import("@earendil-works/pi-durable").Task<{
+            epoch: string;
+        }, {
+            phase: "tick";
+            ordinal: number;
+            due?: number;
+        } | {
+            phase: "submit";
+            pageId: string;
+            ordinal: number;
+        } | {
+            phase: "settle";
+            pageId: string;
+            ordinal: number;
+        }, null, object>;
+    };
+};

package/dist/authority/runtime.js

@@ -0,0 +1,116 @@
+import { configure } from '@earendil-works/pi-durable';
+import { catalogOf, createAuthorityTools } from "./tools.js";
+import { createAnchoredConversation, WorkerAnchor } from "./anchor.js";
+import { createDeliver, scheduleDeliveries } from "./delivery.js";
+import { createNotifier } from "./notifier.js";
+import { observations, observationExtension } from "./observation.js";
+import { sync } from "./sync.js";
+import { open, event } from "./state.js";
+export const stopPlan = (id, intent) => ({ id, conversations: intent.conversations.map(String), tasks: intent.tasks.map(String) });
+export async function pendingStops(harness, context) {
+    return harness.commit(async (tx) => Object.entries((await open(tx)).team.stops).filter(([, i]) => !i.confirmed).map(([id, i]) => stopPlan(id, i)), context);
+}
+export async function confirmStop(harness, id, outcome, context, now = Date.now) {
+    await harness.commit(async (tx) => {
+        const s = await open(tx), intent = s.team.stops[id];
+        if (!intent || intent.confirmed)
+            return;
+        if (outcome.status !== 'settled') {
+            intent.error = outcome.error;
+            return;
+        }
+        // Confirm the exact persisted targets, including tasks already terminal before mark.
+        for (const target of intent.tasks) {
+            const task = await tx.task(target);
+            if (!task || task.state.status !== 'terminal')
+                throw new Error('PTB stop target is not terminal');
+        }
+        if (s.team.current?.epoch !== intent.epoch)
+            throw new Error('PTB stop epoch changed');
+        const worker = intent.worker ? s.team.current.workers[intent.worker] : undefined;
+        if (intent.binding && (!worker || worker.generation !== intent.generation || worker.anchorId !== intent.binding.anchorId || worker.conversationId !== intent.binding.conversationId))
+            throw new Error('PTB stop binding changed');
+        intent.confirmed = true;
+        delete intent.error;
+        if (worker) {
+            worker.state = 'stopped';
+            await event(tx, s, 'team-lead', 'worker_stopped', { worker: worker.name, at: new Date(now()).toISOString() });
+        }
+        if (s.team.current.shutdownPending && Object.values(s.team.stops).filter(i => i.epoch === intent.epoch).every(i => i.confirmed)) {
+            s.team.current.lifecycle = 'stopped';
+            await event(tx, s, 'team-lead', 'team_stopped', { at: new Date(now()).toISOString() });
+        }
+    }, context);
+}
+function addMechanicStops(s, shutdown) {
+    const team = s.team.current;
+    for (const intent of Object.values(s.team.stops)) {
+        if (intent.epoch !== team.epoch || intent.confirmed)
+            continue;
+        for (const o of Object.values(s.outbox.obligations))
+            if (o.epoch === team.epoch && o.recipient === intent.worker && o.deliveryTaskId && !intent.tasks.includes(o.deliveryTaskId))
+                intent.tasks.push(o.deliveryTaskId);
+    }
+    if (!shutdown)
+        return;
+    const key = `${team.epoch}:shutdown-mechanics`;
+    const tasks = Object.values(s.outbox.obligations).filter(o => o.epoch === team.epoch && o.deliveryTaskId).map(o => o.deliveryTaskId);
+    if (team.notifierId)
+        tasks.push(team.notifierId);
+    s.team.stops[key] ??= { epoch: team.epoch, tasks, conversations: [], confirmed: false };
+    return key;
+}
+/** Called by NodePlugin.closing after its own lead Close intent is stored. */
+export async function closing(harness, conversationId, context) {
+    return harness.commit(async (tx) => {
+        const s = await open(tx), team = s.team.current;
+        if (!team || String(team.lead) !== conversationId || team.lifecycle !== 'active')
+            return [];
+        team.shutdownPending = true;
+        for (const w of Object.values(team.workers))
+            if (w.state !== 'stopped') {
+                const key = `${team.epoch}:stop:${w.name}:g${w.generation}`;
+                w.state = 'stopping';
+                s.team.stops[key] ??= { epoch: team.epoch, worker: w.name, generation: w.generation, binding: { conversationId: w.conversationId, anchorId: w.anchorId }, tasks: [w.anchorId], conversations: [w.conversationId], confirmed: false };
+            }
+        for (const o of Object.values(s.outbox.obligations))
+            if (o.epoch === team.epoch)
+                o.state = 'retired';
+        addMechanicStops(s, true);
+        return Object.entries(s.team.stops).filter(([, i]) => i.epoch === team.epoch && !i.confirmed).map(([id, i]) => stopPlan(id, i));
+    }, context);
+}
+export function createTeamRuntime(options) {
+    const Notify = createNotifier(catalogOf(options));
+    const Deliver = createDeliver(options.abortRun);
+    let lead, worker;
+    const core = createAuthorityTools({ ...options, sync,
+        createWorker: async (tx, role) => {
+            const s = await open(tx), binding = await createAnchoredConversation(tx, s.team.current.lead);
+            await configure(tx, binding.conversationId, { model: role.model, ...(role.thinking ? { thinkingLevel: role.thinking } : {}), extensions: { remove: [lead], add: [worker] } });
+            return binding;
+        },
+        settleStops: async (stops, context, api) => stops.length ? (await options.stop(api, stops.map(s => stopPlan(s.key, s.intent)), context)).map(o => o.status === 'settled') : [],
+        afterCommand: async (tx, s, name, result) => {
+            const team = s.team.current;
+            if (!team || team.lifecycle !== 'active')
+                return;
+            if (name === 'team_create') {
+                const o = await observations(tx);
+                o.epoch = team.epoch;
+                o.acknowledged = 0;
+                o.paused = false;
+            }
+            if (!team.notifierId && !team.shutdownPending)
+                team.notifierId = await tx.createTask(Notify, { epoch: team.epoch }, { conversationId: team.lead, ownership: { kind: 'conversation' }, background: true, abandonOnRestart: false });
+            await scheduleDeliveries(tx, s, Deliver);
+            const extra = addMechanicStops(s, name === 'team_shutdown');
+            if (extra && Array.isArray(result.stops) && !result.stops.includes(extra))
+                result.stops.push(extra);
+        }, });
+    lead = { name: 'ptb.lead', tools: core.lead };
+    worker = { name: 'ptb.worker', tools: core.worker };
+    const mechanics = { name: 'ptb.mechanics', tasks: [WorkerAnchor, Deliver, Notify] };
+    const observation = observationExtension(options.observationPort);
+    return { core, lead, worker, mechanics, observation, extensions: [mechanics, lead, worker, observation], tasks: { WorkerAnchor, Deliver, Notify } };
+}

package/dist/authority/state.d.ts

@@ -0,0 +1,150 @@
+import { type ConversationId, type TaskId, type SubmissionId, type EntryId, type JsonObject, type Tx } from '@earendil-works/pi-durable';
+import type { GraphControlSnapshot } from './graph-control.ts';
+export interface Binding {
+    conversationId: ConversationId;
+    anchorId: TaskId;
+}
+export interface ModelRole {
+    name: string;
+    use: string;
+    model: {
+        provider: string;
+        modelId: string;
+    };
+    thinking?: string;
+}
+/** The roles a lead can select, with the role ensure_worker uses when the call names none. */
+export interface ModelRoleCatalog {
+    modelRoles: ModelRole[];
+    defaultModelRole?: string;
+}
+export interface Worker extends Binding {
+    createdAt?: number;
+    name: string;
+    scope: string;
+    generation: number;
+    state: 'active' | 'stopping' | 'stopped';
+    role: ModelRole;
+}
+export interface Team {
+    createdAt?: number;
+    epoch: string;
+    name: string;
+    purpose: string;
+    lead: ConversationId;
+    lifecycle: 'active' | 'stopped';
+    workers: Record<string, Worker>;
+    shutdownPending?: boolean;
+    notifierId?: TaskId;
+}
+export interface StopIntent {
+    epoch: string;
+    worker?: string;
+    binding?: Binding;
+    generation?: number;
+    tasks: TaskId[];
+    conversations: ConversationId[];
+    confirmed: boolean;
+    error?: string;
+}
+export interface TeamState {
+    current?: Team;
+    history: Team[];
+    stops: Record<string, StopIntent>;
+}
+export interface GraphState {
+    epoch?: string;
+    snapshot?: GraphControlSnapshot;
+    history?: Record<string, GraphControlSnapshot>;
+}
+export interface Alert {
+    interrupt?: true;
+    id: string;
+    from: string;
+    kind: string;
+    text: string;
+    task_id?: string;
+    task_version?: string;
+    receivedAt: string;
+    recipients: {
+        name: string;
+        conversationId: ConversationId;
+        generation: number;
+    }[];
+}
+export interface Obligation {
+    interrupt?: true;
+    interruptRun?: TaskId;
+    interruption?: 'interrupted' | 'ended' | 'failed';
+    acceptedAt?: number;
+    submittedAt?: number;
+    settledAt?: number;
+    key: string;
+    epoch: string;
+    kind: 'task' | 'stop' | 'alert';
+    recipient: string;
+    conversationId: ConversationId;
+    generation: number;
+    taskId?: string;
+    version?: string;
+    alertId?: string;
+    state: 'pending' | 'retired' | 'settled';
+    deliveryTaskId?: TaskId;
+    submissionId?: SubmissionId;
+    outcome?: string;
+}
+export interface OutboxState {
+    alerts: Record<string, Alert>;
+    obligations: Record<string, Obligation>;
+}
+export interface Event {
+    seq: number;
+    epoch: string;
+    actor: string;
+    kind: string;
+    taskId?: string;
+    taskIds?: string[];
+    worker?: string;
+    at?: string;
+    text?: string;
+    entryId?: EntryId;
+}
+export interface JournalState {
+    seq: number;
+    events: Event[];
+    reservation?: {
+        epoch: string;
+        call: string;
+        through: number;
+    };
+    acknowledged: number;
+}
+export type Result = Record<string, unknown> & {
+    kind: string;
+};
+export interface Receipt {
+    fingerprint: string;
+    result?: Result;
+    stops?: string[];
+    epoch?: string;
+}
+export interface ReceiptState {
+    calls: Record<string, Receipt>;
+}
+export declare const TeamDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const GraphDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const JournalDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const OutboxDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const ReceiptDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare function open(tx: Tx): Promise<{
+    team: TeamState;
+    graph: GraphState;
+    journal: JournalState;
+    outbox: OutboxState;
+    receipts: ReceiptState;
+}>;
+export type State = Awaited<ReturnType<typeof open>>;
+export declare const plain: <T>(value: T) => T;
+export declare const JOURNAL_RESIDENT_LIMIT = 100;
+/** History is append-only storage; the document contains a bounded recent projection. */
+export declare function event(tx: Tx, s: State, actor: string, kind: string, extra?: Pick<Event, 'taskId' | 'taskIds' | 'worker' | 'at' | 'text'>): Promise<void>;

package/dist/authority/state.js

@@ -0,0 +1,26 @@
+import { defineDoc } from '@earendil-works/pi-durable';
+const doc = (kind, initial) => defineDoc({ kind, version: 1, scope: 'session', checkpointWhen: () => false, initial });
+export const TeamDoc = doc('ptb.team', () => ({ history: [], stops: {} }));
+export const GraphDoc = doc('ptb.graph', () => ({}));
+export const JournalDoc = defineDoc({ kind: 'ptb.journal', version: 1, scope: 'session', initial: () => ({ seq: 0, events: [], acknowledged: 0 }), checkpointWhen: (_value, _ops, info) => info.deltasSinceBase >= 31 });
+export const OutboxDoc = doc('ptb.outbox', () => ({ alerts: {}, obligations: {} }));
+export const ReceiptDoc = doc('ptb.receipts', () => ({ calls: {} }));
+export async function open(tx) {
+    return {
+        team: await tx.doc(TeamDoc),
+        graph: await tx.doc(GraphDoc),
+        journal: await tx.doc(JournalDoc),
+        outbox: await tx.doc(OutboxDoc),
+        receipts: await tx.doc(ReceiptDoc),
+    };
+}
+export const plain = (value) => JSON.parse(JSON.stringify(value));
+export const JOURNAL_RESIDENT_LIMIT = 100;
+/** History is append-only storage; the document contains a bounded recent projection. */
+export async function event(tx, s, actor, kind, extra = {}) {
+    const value = { seq: ++s.journal.seq, epoch: s.team.current.epoch, actor, kind, ...extra };
+    const entry = await tx.appendEntry(s.team.current.lead, { kind: 'ptb.event', data: value });
+    s.journal.events.push({ ...value, entryId: entry.id });
+    if (s.journal.events.length > JOURNAL_RESIDENT_LIMIT)
+        s.journal.events.splice(0, s.journal.events.length - JOURNAL_RESIDENT_LIMIT);
+}

package/dist/authority/sync.d.ts

@@ -0,0 +1,12 @@
+import { type Tx, type EntryId } from '@earendil-works/pi-durable';
+import type { CoreApi } from './tools.ts';
+import { type State, type Event, type Result } from './state.ts';
+export declare const UPDATE_PAGE_EVENTS = 50;
+export declare const UPDATE_SCAN_ENTRIES = 100;
+export declare function updates(s: State, events: Event[]): Result;
+/** Page native history without making the journal document an unbounded cache. */
+export declare function pageEvents(tx: Tx, s: State, from: number, after?: EntryId): Promise<{
+    events: Event[];
+    scanThrough?: EntryId;
+}>;
+export declare function sync(tx: Tx, s: State, view: 'snapshot' | 'updates' | undefined, api: CoreApi, snapshot: Result): Promise<Result>;

package/dist/authority/sync.js

@@ -0,0 +1,77 @@
+import { LiveDoc } from '@earendil-works/pi-durable';
+import { GraphTaskController } from "./graph-control.js";
+import { projectGraphTaskCards } from "./graph-card.js";
+import { observations, reservationHead, reserve } from "./observation.js";
+import { plain } from "./state.js";
+export const UPDATE_PAGE_EVENTS = 50;
+export const UPDATE_SCAN_ENTRIES = 100;
+export function updates(s, events) {
+    const team = s.team.current, cards = projectGraphTaskCards(GraphTaskController.recover(plain(s.graph.snapshot)));
+    const ids = [...new Set(events.flatMap(e => e.taskIds ?? (e.taskId ? [e.taskId] : [])))];
+    return { kind: 'updates',
+        team_changes: events.filter(e => e.kind === 'team_created' || e.kind === 'team_stopped').map(e => ({ kind: e.kind === 'team_created' ? 'created' : 'lifecycle', text: e.kind === 'team_created' ? team.purpose : 'Team stopped.' })),
+        worker_changes: events.filter(e => e.worker && ['worker_created', 'worker_stopped'].includes(e.kind)).map(e => ({ worker: e.worker, scope: team.workers[e.worker]?.scope ?? 'Historical Worker', kind: e.kind === 'worker_created' ? 'created' : 'stopped', text: e.kind === 'worker_created' ? 'Worker created.' : 'Worker stopped.' })),
+        task_changes: ids.flatMap(id => { const current = cards.find(t => t.id === id); return current ? [{ task_id: id, change_kinds: ['status'], journal_entries: events.filter(e => e.taskId === id && e.at && e.text).map(e => ({ id: `${e.epoch}:${e.seq}`, at: e.at, actor: e.actor, kind: 'note', text: e.text })), current }] : []; }),
+        alerts: [], };
+}
+/** Page native history without making the journal document an unbounded cache. */
+export async function pageEvents(tx, s, from, after) {
+    const recent = s.journal.events.filter(e => e.seq > from);
+    if (recent.length && s.journal.events[0].seq <= from + 1) {
+        const events = recent.slice(0, UPDATE_PAGE_EVENTS);
+        return { events, scanThrough: events.at(-1)?.entryId };
+    }
+    const native = await tx.scanEntries({ conversationId: s.team.current.lead, order: 'ascending', ...(after ? { minEntryId: after } : {}) }, UPDATE_SCAN_ENTRIES);
+    const events = [];
+    let scanThrough = after;
+    for (const entry of native.items) {
+        if (after !== undefined && entry.id <= after)
+            continue;
+        scanThrough = entry.id;
+        if (entry.kind === 'ptb.event') {
+            const event = entry.data;
+            if (event.epoch === s.team.current.epoch && event.seq > from)
+                events.push({ ...event, entryId: entry.id });
+        }
+        if (events.length >= UPDATE_PAGE_EVENTS)
+            break;
+    }
+    return { events, scanThrough };
+}
+export async function sync(tx, s, view, api, snapshot) {
+    const team = s.team.current, live = await tx.doc(LiveDoc, api.conversationId), run = live.run?.inputs[0];
+    if (run === undefined)
+        return { kind: 'unavailable', reason: 'team_state_unavailable', message: 'Observation requires a persisted lead run.' };
+    const o = await observations(tx);
+    o.paused = false;
+    if (Object.values(o.pages).some(p => p.epoch === team.epoch && p.run !== run && ['reserved', 'presented'].includes(p.state)))
+        return { kind: 'refused', reason: 'observation_in_progress', message: 'Another run or automatic delivery owns an unacknowledged page.', state_changed: false, observation_advanced: false };
+    const id = `${team.epoch}:sync:${api.taskId}`, from = reservationHead(o, team.epoch, run);
+    const carrier = { kind: 'tool', callId: api.callId ?? String(api.taskId) };
+    // Failed-run pages reappear once in order; the old replay receipt remains immutable.
+    const released = Object.values(o.pages).find(p => p.epoch === team.epoch && p.state === 'released');
+    if (released) {
+        const result = JSON.parse(released.body);
+        released.state = 'replaced';
+        reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from: released.from, through: released.through, carrier, ...(released.scanThrough ? { scanThrough: released.scanThrough } : {}) }, result);
+        return result;
+    }
+    const outstanding = Object.values(o.pages).filter(p => p.epoch === team.epoch && p.run === run && ['reserved', 'presented'].includes(p.state));
+    if ((view !== 'snapshot' || outstanding.length > 0) && from >= s.journal.seq)
+        return { kind: 'caught_up', head: s.journal.seq, epoch_id: team.epoch };
+    let result, through, scanThrough;
+    if (!outstanding.length && (view === 'snapshot' || from === 0)) {
+        result = snapshot;
+        through = s.journal.seq;
+        scanThrough = s.journal.events.at(-1)?.entryId;
+    }
+    else {
+        const previous = Object.values(o.pages).filter(p => p.epoch === team.epoch && p.scanThrough !== undefined && (p.state === 'acknowledged' || p.run === run && ['reserved', 'presented'].includes(p.state))).sort((a, b) => Number(b.scanThrough) - Number(a.scanThrough))[0];
+        const page = await pageEvents(tx, s, from, previous?.scanThrough);
+        result = updates(s, page.events);
+        through = page.events.at(-1)?.seq ?? from;
+        scanThrough = page.scanThrough;
+    }
+    reserve(o, { id, epoch: team.epoch, lead: team.lead, run, from, through, carrier, ...(scanThrough ? { scanThrough } : {}) }, result);
+    return result;
+}

package/dist/authority/task-version-ref.d.ts

@@ -0,0 +1,3 @@
+export type TaskVersionRef = `v_${string}`;
+/** Stable model-facing version token. */
+export declare function taskVersionRef(sourceRevision: string): TaskVersionRef;

package/dist/authority/task-version-ref.js

@@ -0,0 +1,5 @@
+import { createHash } from "node:crypto";
+/** Stable model-facing version token. */
+export function taskVersionRef(sourceRevision) {
+    return `v_${createHash("sha256").update(sourceRevision).digest("hex").slice(0, 16)}`;
+}

package/dist/authority/tools.d.ts

@@ -0,0 +1,68 @@
+import type { Context } from '@earendil-works/chord/context';
+import { type ToolExecutionApi, type Tx } from '@earendil-works/pi-durable';
+import { type Role, type ToolName } from './contracts.ts';
+import { type GraphTaskTransition, type GraphVersionRef } from './graph-control.ts';
+import type { TaskVersionRef } from './task-version-ref.ts';
+import type { ConversationId } from '@earendil-works/pi-durable';
+import { type Binding, type ModelRole, type ModelRoleCatalog, type Result, type State, type StopIntent } from './state.ts';
+export type CoreApi = Pick<ToolExecutionApi, 'taskId' | 'conversationId' | 'commit' | 'now'> & Partial<Pick<ToolExecutionApi, 'callId'>>;
+export interface CoreOptions {
+    modelRoles: ModelRole[];
+    defaultModelRole?: string;
+    goalMaxLength?: number;
+    createWorker?: (tx: Tx, role: ModelRole) => Promise<Binding>;
+    resolveModelRole?: (tx: Tx, role: ModelRole) => Promise<ModelRole>;
+    catalog?: (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>;
+    stopWorker?: (binding: Binding, context: Context) => Promise<boolean>;
+    settleStops?: (stops: {
+        key: string;
+        intent: StopIntent;
+    }[], context: Context, api: CoreApi) => Promise<boolean[]>;
+    afterCommand?: (tx: Tx, s: State, name: ToolName, result: Result | {
+        stops: string[];
+        epoch: string;
+    }, api: CoreApi) => Promise<void>;
+    sync?: (tx: Tx, s: State, view: Args['view'], api: CoreApi, snapshot: Result) => Promise<Result>;
+}
+interface Args {
+    name?: string;
+    purpose?: string;
+    scope?: string;
+    model_role?: string;
+    worker?: string;
+    view?: 'snapshot' | 'updates';
+    task_id?: string;
+    task_ids?: string[];
+    operation_id?: string;
+    expected_graph_version?: GraphVersionRef;
+    expected_version?: TaskVersionRef;
+    transition?: GraphTaskTransition;
+    current_context?: string;
+    evidence?: string;
+    tasks?: {
+        key: string;
+        title: string;
+        goal: string;
+        assignee: string;
+        needs?: string[];
+        on_goal_failed?: {
+            target: string;
+            max_traversals: number;
+        };
+    }[];
+    to?: string;
+    kind?: string;
+    text?: string;
+    task_version?: string;
+    interrupt?: boolean;
+}
+/** The catalog resolver that options select: the host's per-lead port, else the static list. */
+export declare function catalogOf(options: Pick<CoreOptions, 'modelRoles' | 'defaultModelRole' | 'catalog'>): (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>;
+/** Authority commands commit intent and replay receipts; injected ports own effects. */
+export declare function createAuthorityTools(options: CoreOptions): {
+    lead: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
+    worker: import("@earendil-works/pi-durable").ToolRegistration<import("typebox").TSchema, import("@earendil-works/chord").JsonValue>[];
+    execute: (name: ToolName, role: Role, input: unknown, api: CoreApi, context: Context) => Promise<Result>;
+    contract: import("./contracts.ts").Contract;
+};
+export {};