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

package/dist/authority/index.d.ts

@@ -0,0 +1,11 @@
+export { createTeamRuntime, pendingStops, confirmStop, closing, stopPlan, type RuntimeOptions, type StopPlan, type StopOutcome } from './runtime.ts';
+export { observe, ObservationDoc, observations, type Observations, type Page, type ObservationPortResolver } from './observation.ts';
+export { TeamDoc, GraphDoc, JournalDoc, OutboxDoc, ReceiptDoc, open, plain, type TeamState, type GraphState, type JournalState, type OutboxState, type Team, type Worker, type ModelRole, type ModelRoleCatalog, type State } from './state.ts';
+export { GraphTaskController } from './graph-control.ts';
+export { projectGraphTaskCards } from './graph-card.ts';
+export { snapshotResult, currentAlerts } from './projection.ts';
+export { abortExpectedRun, type AbortRun, type InterruptOutcome, type InterruptTarget } from './interrupt.ts';
+export { TASK_ID_MAX_LENGTH } from './limits.ts';
+export { deliveryDraft, deliveryInput, SENDER_LIMIT, type DeliveryInput, type TeamNoticeData } from './delivery.ts';
+export { pageDraft } from './notifier.ts';
+export { updates, pageEvents, UPDATE_PAGE_EVENTS, UPDATE_SCAN_ENTRIES } from './sync.ts';

package/dist/authority/index.js

@@ -0,0 +1,11 @@
+export { createTeamRuntime, pendingStops, confirmStop, closing, stopPlan } from "./runtime.js";
+export { observe, ObservationDoc, observations } from "./observation.js";
+export { TeamDoc, GraphDoc, JournalDoc, OutboxDoc, ReceiptDoc, open, plain } from "./state.js";
+export { GraphTaskController } from "./graph-control.js";
+export { projectGraphTaskCards } from "./graph-card.js";
+export { snapshotResult, currentAlerts } from "./projection.js";
+export { abortExpectedRun } from "./interrupt.js";
+export { TASK_ID_MAX_LENGTH } from "./limits.js";
+export { deliveryDraft, deliveryInput, SENDER_LIMIT } from "./delivery.js";
+export { pageDraft } from "./notifier.js";
+export { updates, pageEvents, UPDATE_PAGE_EVENTS, UPDATE_SCAN_ENTRIES } from "./sync.js";

package/dist/authority/interrupt.d.ts

@@ -0,0 +1,11 @@
+import type { Context } from '@earendil-works/chord/context';
+import { type Harness, type TaskId, type ConversationId, type DocumentReader } from '@earendil-works/pi-durable';
+export interface InterruptTarget {
+    key: string;
+    conversationId: ConversationId;
+    expectedRunTaskId?: TaskId;
+}
+export type InterruptOutcome = 'interrupted' | 'ended' | 'failed' | 'retired';
+export type AbortRun = (api: Pick<DocumentReader, 'snapshot'>, target: InterruptTarget, context: Context) => Promise<InterruptOutcome>;
+/** Host primitive: exact native identity, cancellable wait, and no conversation-wide abort. */
+export declare function abortExpectedRun(harness: Harness, target: InterruptTarget, context: Context): Promise<InterruptOutcome>;

package/dist/authority/interrupt.js

@@ -0,0 +1,26 @@
+import { LiveDoc } from '@earendil-works/pi-durable';
+import { open } from "./state.js";
+import { eligible } from "./delivery.js";
+/** Host primitive: exact native identity, cancellable wait, and no conversation-wide abort. */
+export async function abortExpectedRun(harness, target, context) {
+    const check = await harness.commit(async (tx) => {
+        const s = await open(tx), o = s.outbox.obligations[target.key];
+        if (!o || !eligible(s, o) || o.conversationId !== target.conversationId || o.interruptRun !== target.expectedRunTaskId)
+            return 'retired';
+        if (target.expectedRunTaskId === undefined)
+            return 'ended';
+        const task = await tx.task(target.expectedRunTaskId), live = await tx.doc(LiveDoc, target.conversationId);
+        if (!task || task.conversationId !== target.conversationId)
+            return 'failed';
+        if (task.state.status === 'terminal')
+            return task.state.outcome.status === 'aborted' ? 'interrupted' : 'ended';
+        if (live.run?.taskId !== target.expectedRunTaskId)
+            return 'ended';
+        return 'abort';
+    }, context);
+    if (check !== 'abort')
+        return check;
+    await harness.abortTask(target.expectedRunTaskId, context);
+    const task = await harness.waitForTask(target.expectedRunTaskId, context);
+    return task.state.outcome.status === 'aborted' ? 'interrupted' : 'failed';
+}

package/dist/authority/limits.d.ts

@@ -0,0 +1,7 @@
+import { Type } from "typebox";
+/** Static card type defaults. contracts.ts applies the configured runtime goal limit. */
+export declare const TASK_CARD_GOAL_MAX_LENGTH = 1600;
+export declare const TASK_ID_MAX_LENGTH = 128;
+export declare const TASK_CARD_TITLE_MAX_LENGTH = 80;
+export declare const TASK_CARD_CONTEXT_MAX_LENGTH = 2000;
+export declare const TaskVersionRefSchema: Type.TString;

package/dist/authority/limits.js

@@ -0,0 +1,7 @@
+import { Type } from "typebox";
+/** Static card type defaults. contracts.ts applies the configured runtime goal limit. */
+export const TASK_CARD_GOAL_MAX_LENGTH = 1_600;
+export const TASK_ID_MAX_LENGTH = 128;
+export const TASK_CARD_TITLE_MAX_LENGTH = 80;
+export const TASK_CARD_CONTEXT_MAX_LENGTH = 2_000;
+export const TaskVersionRefSchema = Type.String({ pattern: "^v_[0-9a-f]{16}$", minLength: 18, maxLength: 18 });

package/dist/authority/notifier.d.ts

@@ -0,0 +1,32 @@
+import { type ConversationId, type Tx } from '@earendil-works/pi-durable';
+import { type Page } from './observation.ts';
+import { type ModelRoleCatalog } from './state.ts';
+import type { TeamNoticeData } from './delivery.ts';
+export declare const NOTIFY_RECHECK_MS = 1000;
+export declare const NOTIFY_DELAY_MS = 30000;
+/** The input a notifier page submits to the lead: a Team update that durable-team itself writes. */
+export declare function pageDraft(page: Page): {
+    type: "input";
+    content: string;
+    whenBusy: "followUp";
+    requestId: string;
+    entry: {
+        kind: string;
+        data: TeamNoticeData;
+    };
+};
+export declare function createNotifier(rolesOf: (tx: Tx, lead: ConversationId) => Promise<ModelRoleCatalog>): 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/notifier.js

@@ -0,0 +1,83 @@
+import { defineTask, LiveDoc } from '@earendil-works/pi-durable';
+import { observations, reserve } from "./observation.js";
+import { open, plain } from "./state.js";
+import { snapshotResult } from "./projection.js";
+import { pageEvents, updates } from "./sync.js";
+export const NOTIFY_RECHECK_MS = 1000;
+export const NOTIFY_DELAY_MS = 30000;
+/** The input a notifier page submits to the lead: a Team update that durable-team itself writes. */
+export function pageDraft(page) {
+    const data = { source: 'team', pageId: page.id, epoch: page.epoch, delivery: 'update', sender: 'durable-team' };
+    return { type: 'input', content: page.carrier.kind === 'input' ? page.carrier.text : page.body, whenBusy: 'followUp', requestId: page.id, entry: { kind: 'team.notice', data } };
+}
+const draft = pageDraft;
+export function createNotifier(rolesOf) {
+    return defineTask({
+        name: 'ptb.notify', version: 1, initial: () => ({ phase: 'tick', ordinal: 1 }),
+        phases: {
+            tick: async (task, runtime, context) => {
+                await runtime.commit(async (tx) => {
+                    const s = await open(tx), team = s.team.current, o = await observations(tx);
+                    if (!team || team.epoch !== task.input.epoch || team.lifecycle !== 'active' || team.shutdownPending)
+                        return { status: 'terminal', outcome: { status: 'completed', result: null } };
+                    const live = await tx.doc(LiveDoc, team.lead);
+                    const pending = Object.values(o.pages).some(p => p.epoch === team.epoch && ['reserved', 'presented'].includes(p.state));
+                    const checkpoint = task.state.checkpoint, due = checkpoint.due ?? runtime.now() + NOTIFY_DELAY_MS;
+                    if (o.paused || pending || live.run || s.journal.seq <= o.acknowledged || runtime.now() < due)
+                        return { status: 'sleeping', until: runtime.now() + NOTIFY_RECHECK_MS, checkpoint: { ...checkpoint, due } };
+                    const from = o.epoch === team.epoch ? o.acknowledged : 0;
+                    const previous = Object.values(o.pages).filter(p => p.epoch === team.epoch && p.state === 'acknowledged' && p.scanThrough !== undefined).sort((a, b) => Number(b.scanThrough) - Number(a.scanThrough))[0];
+                    const change = from ? await pageEvents(tx, s, from, previous?.scanThrough) : undefined;
+                    const roles = change ? undefined : await rolesOf(tx, team.lead);
+                    const result = change ? updates(s, change.events) : snapshotResult(s, roles.modelRoles, roles.defaultModelRole);
+                    const id = `${team.epoch}:notify:${runtime.taskId}:${checkpoint.ordinal}`;
+                    const text = JSON.stringify({ kind: 'team_update', page_id: id, result });
+                    const scanThrough = change?.scanThrough ?? s.journal.events.at(-1)?.entryId;
+                    reserve(o, { id, epoch: team.epoch, lead: team.lead, run: 0, from, through: change ? change.events.at(-1)?.seq ?? from : s.journal.seq, carrier: { kind: 'input', text }, ...(scanThrough ? { scanThrough } : {}) }, result);
+                    return { status: 'running', checkpoint: { phase: 'submit', pageId: id, ordinal: checkpoint.ordinal } };
+                }, context);
+            },
+            submit: async (task, runtime, context) => {
+                let page;
+                await runtime.commit(async (tx) => {
+                    const s = await open(tx), o = await observations(tx), p = o.pages[task.state.checkpoint.pageId];
+                    if (!p || s.team.current?.epoch !== p.epoch || s.team.current?.shutdownPending || s.team.current?.lifecycle !== 'active')
+                        return { status: 'terminal', outcome: { status: 'completed', result: null } };
+                    page = plain(p);
+                    return undefined;
+                }, context);
+                if (!page)
+                    return;
+                const target = await runtime.conversation(page.lead, context);
+                if (!target)
+                    throw new Error('PTB lead is missing');
+                const submission = await target.submit(draft(page), context);
+                await runtime.commit(async (tx) => { (await observations(tx)).pages[page.id].submissionId = submission.id; return { status: 'running', checkpoint: { ...task.state.checkpoint, phase: 'settle' } }; }, context);
+            },
+            settle: async (task, runtime, context) => {
+                let page;
+                await runtime.commit(async (tx) => { page = plain((await observations(tx)).pages[task.state.checkpoint.pageId]); return undefined; }, context);
+                const target = await runtime.conversation(page.lead, context);
+                if (!target)
+                    throw new Error('PTB lead is missing');
+                const submission = await target.submit(draft(page), context);
+                if (submission.id !== page.submissionId)
+                    throw new Error('PTB notifier admission identity changed');
+                const settled = await submission.wait(context);
+                await runtime.commit(async (tx) => {
+                    const o = await observations(tx), p = o.pages[page.id];
+                    if (p.run === 0)
+                        p.run = submission.id;
+                    if (settled.status !== 'done') {
+                        p.state = 'released';
+                        o.paused = true;
+                    }
+                    return { status: 'sleeping', until: runtime.now() + NOTIFY_RECHECK_MS, checkpoint: { phase: 'tick', ordinal: task.state.checkpoint.ordinal + 1 } };
+                }, context);
+            },
+        },
+        abort: async (task, runtime, context) => runtime.commit(async (tx) => { const o = await observations(tx); for (const p of Object.values(o.pages))
+            if (p.epoch === task.input.epoch && p.carrier.kind === 'input' && ['reserved', 'presented'].includes(p.state))
+                p.state = 'released'; return { status: 'terminal', outcome: { status: 'aborted' } }; }, context),
+    });
+}

package/dist/authority/observation.d.ts

@@ -0,0 +1,55 @@
+import type { Context } from '@earendil-works/chord/context';
+import type { AssistantMessage } from '@earendil-works/pi-ai';
+import { type JsonObject, type ConversationId, type TaskId, type SubmissionId, type EntryId, type Harness, type Tx, type HookApi, type Extension } from '@earendil-works/pi-durable';
+import { type Result } from './state.ts';
+export interface Page {
+    id: string;
+    epoch: string;
+    lead: ConversationId;
+    run: SubmissionId;
+    from: number;
+    through: number;
+    body: string;
+    digest: string;
+    carrier: {
+        kind: 'tool';
+        callId: string;
+    } | {
+        kind: 'input';
+        text: string;
+    };
+    state: 'reserved' | 'presented' | 'released' | 'acknowledged' | 'replaced';
+    scanThrough?: EntryId;
+    submissionId?: SubmissionId;
+}
+interface Proof {
+    generation: TaskId;
+    lead: ConversationId;
+    run: SubmissionId;
+    requestDigest: string;
+    pages: string[];
+    responseDigest?: string;
+}
+export interface Observations {
+    pages: Record<string, Page>;
+    proofs: Record<string, Proof>;
+    acknowledged: number;
+    epoch?: string;
+    paused?: boolean;
+    resumedOwnerRun?: SubmissionId;
+}
+export declare const ObservationDoc: import("@earendil-works/pi-durable").SessionDocToken<JsonObject>;
+export declare const digest: (value: unknown) => string;
+export declare const observations: (tx: Tx) => Promise<Observations>;
+export declare function reservationHead(o: Observations, epoch: string, run: SubmissionId): number;
+export declare function reserve(o: Observations, input: Omit<Page, 'body' | 'digest' | 'state'>, result: Result): Page;
+export interface ObservationPort {
+    commit<T>(fn: (tx: Tx) => Promise<T>, context: Context): Promise<T>;
+}
+/** Install last among message-replacing hooks. No hook advances the acknowledged cursor. */
+export type ObservationPortResolver = (api: HookApi, context: Context) => Promise<ObservationPort>;
+export declare function observationExtension(resolvePort: ObservationPortResolver): Extension;
+export declare function recordResponse(port: ObservationPort, api: Pick<HookApi, 'taskId'>, message: AssistantMessage, context: Context): Promise<void>;
+/** Later observer: native response persistence and run settlement are both required. */
+export declare function observe(harness: Harness, context: Context): Promise<void>;
+export {};

package/dist/authority/observation.js

@@ -0,0 +1,125 @@
+import { createHash } from 'node:crypto';
+import { defineDoc, GenerationTask, hook, LiveDoc } from '@earendil-works/pi-durable';
+import { open, plain } from "./state.js";
+export const ObservationDoc = defineDoc({ kind: 'ptb.observation', version: 1, scope: 'session', initial: () => ({ pages: {}, proofs: {}, acknowledged: 0 }), checkpointWhen: (_v, _o, i) => i.deltasSinceBase >= 31 });
+export const digest = (value) => createHash('sha256').update(typeof value === 'string' ? value : JSON.stringify(value)).digest('hex');
+export const observations = async (tx) => await tx.doc(ObservationDoc);
+export function reservationHead(o, epoch, run) {
+    return Math.max(o.epoch === epoch ? o.acknowledged : 0, ...Object.values(o.pages).filter(p => p.epoch === epoch && p.run === run && (p.state === 'reserved' || p.state === 'presented')).map(p => p.through));
+}
+export function reserve(o, input, result) {
+    if (o.epoch !== input.epoch) {
+        o.epoch = input.epoch;
+        o.acknowledged = 0;
+        o.paused = false;
+    }
+    if (o.pages[input.id])
+        return o.pages[input.id];
+    const body = JSON.stringify(result), page = { ...input, body, digest: digest(body), state: 'reserved' };
+    o.pages[input.id] = page;
+    return page;
+}
+function texts(message) {
+    const content = message.content;
+    return typeof content === 'string' ? [content] : Array.isArray(content) ? content.filter(c => c.type === 'text').map(c => c.text) : [];
+}
+function visible(page, messages) {
+    const carrier = page.carrier;
+    return messages.some(message => carrier.kind === 'tool'
+        ? message.role === 'toolResult' && message.toolCallId === carrier.callId && texts(message).some(text => text === page.body)
+        : message.role === 'user' && texts(message).some(text => text === carrier.text));
+}
+export function observationExtension(resolvePort) {
+    return { name: 'ptb.observation', hooks: [hook(GenerationTask, {
+                beforeRequest: async (request, api, context) => {
+                    const port = await resolvePort(api, context);
+                    const live = await api.snapshot(LiveDoc, api.conversationId, context), run = live?.run?.inputs[0];
+                    if (run === undefined)
+                        return;
+                    await port.commit(async (tx) => {
+                        const o = await observations(tx), ids = [];
+                        for (const p of Object.values(o.pages)) {
+                            if (p.lead !== api.conversationId || (p.run !== run && p.run !== 0) || !['reserved', 'presented'].includes(p.state))
+                                continue;
+                            if (visible(p, request.messages)) {
+                                p.run = run;
+                                ids.push(p.id);
+                                p.state = 'presented';
+                            }
+                            else if (p.state === 'reserved' && p.run === run)
+                                p.state = 'released';
+                        }
+                        // Replace on every attempt. An earlier response cannot attest a later request.
+                        o.proofs[String(api.taskId)] = { generation: api.taskId, lead: api.conversationId, run, requestDigest: digest(request.messages), pages: ids };
+                    }, context);
+                },
+                afterResponse: async (message, api, context) => {
+                    await recordResponse(await resolvePort(api, context), api, message, context);
+                },
+            })] };
+}
+export async function recordResponse(port, api, message, context) {
+    await port.commit(async (tx) => {
+        const o = await observations(tx), proof = o.proofs[String(api.taskId)];
+        if (proof && ['stop', 'length', 'toolUse'].includes(message.stopReason))
+            proof.responseDigest = digest(message);
+    }, context);
+}
+/** Later observer: native response persistence and run settlement are both required. */
+export async function observe(harness, context) {
+    const snapshot = await harness.commit(async (tx) => plain(await observations(tx)), context);
+    const proofs = Object.values(snapshot.proofs);
+    const witnessed = new Set();
+    // Generation checkpoints/results name their persisted assistant entry. No transcript scan.
+    for (const proof of proofs) {
+        if (!proof.responseDigest || !proof.pages.length)
+            continue;
+        const native = await harness.getTask(proof.generation, context), state = native?.state;
+        const entryId = state?.checkpoint?.assistant ?? (state?.outcome?.status === 'completed' ? state.outcome.result?.entryId : undefined);
+        if (entryId === undefined)
+            continue;
+        const entry = await harness.commit(tx => tx.entry(entryId), context);
+        if (entry?.byTaskId === proof.generation && entry.kind === 'pi.assistant' && entry.model?.some(m => digest(m) === proof.responseDigest))
+            for (const id of proof.pages)
+                witnessed.add(id);
+    }
+    const runs = new Map();
+    for (const page of Object.values(snapshot.pages)) {
+        if (!['reserved', 'presented'].includes(page.state) || runs.has(page.run))
+            continue;
+        const submission = await harness.submission(page.run, context), record = await submission?.status(context);
+        runs.set(page.run, record?.status === 'done' ? 'success' : record?.status === 'unanswered' ? 'failure' : 'live');
+    }
+    await harness.commit(async (tx) => {
+        const o = await observations(tx), s = await open(tx);
+        for (const p of Object.values(o.pages)) {
+            if (!['reserved', 'presented'].includes(p.state))
+                continue;
+            // Only unchanged persisted evidence may settle this reservation.
+            if (JSON.stringify(p) !== JSON.stringify(snapshot.pages[p.id]))
+                continue;
+            const outcome = runs.get(p.run);
+            if (outcome === 'live')
+                continue;
+            const stableProof = Object.values(o.proofs).some(proof => proof.pages.includes(p.id) && JSON.stringify(proof) === JSON.stringify(snapshot.proofs[String(proof.generation)]));
+            if (outcome === 'success' && witnessed.has(p.id) && stableProof) {
+                p.state = 'acknowledged';
+            }
+            else if (outcome === 'failure' || outcome === 'success') {
+                p.state = 'released';
+                if (outcome === 'failure')
+                    o.paused = true;
+            }
+        }
+        for (let advanced = true; advanced;) {
+            advanced = false;
+            for (const p of Object.values(o.pages))
+                if (p.epoch === o.epoch && p.state === 'acknowledged' && p.from <= o.acknowledged && p.through > o.acknowledged) {
+                    o.acknowledged = p.through;
+                    advanced = true;
+                }
+        }
+        if (s.team.current?.epoch === o.epoch)
+            s.journal.acknowledged = o.acknowledged;
+    }, context);
+}

package/dist/authority/projection.d.ts

@@ -0,0 +1,4 @@
+import { type State, type Result, type ModelRole } from './state.ts';
+/** Alert IDs carry their Team epoch; consumers do not parse that identity. */
+export declare function currentAlerts(s: State): import("./state.ts").Alert[];
+export declare function snapshotResult(s: State, modelRoles: ModelRole[], defaultModelRole?: string): Result;

package/dist/authority/projection.js

@@ -0,0 +1,15 @@
+import { GraphTaskController } from "./graph-control.js";
+import { projectGraphTaskCards } from "./graph-card.js";
+import { plain } from "./state.js";
+/** Alert IDs carry their Team epoch; consumers do not parse that identity. */
+export function currentAlerts(s) {
+    const epoch = s.team.current?.epoch;
+    return epoch === undefined ? [] : Object.values(s.outbox.alerts).filter(a => a.id.startsWith(`${epoch}:`));
+}
+export function snapshotResult(s, modelRoles, defaultModelRole) {
+    const team = s.team.current, graph = GraphTaskController.recover(plain(s.graph.snapshot));
+    const received = currentAlerts(s).filter(a => a.recipients.some(r => r.name === 'team-lead' && r.conversationId === team.lead)).reverse();
+    return { kind: 'snapshot', team: { name: team.name, purpose: team.purpose, lifecycle: 'active' }, model_roles: modelRoles.map(r => ({ name: r.name, use: r.use })), ...(defaultModelRole ? { default_model_role: defaultModelRole } : {}),
+        workers: Object.values(team.workers).map(w => ({ name: w.name, scope: w.scope, carrier: w.state === 'active' ? 'connected' : 'absent', model_role: w.role.name, nonterminal_task_ids: graph.readTasks().filter(t => t.assignee === w.name && !['goal_achieved', 'goal_failed', 'cancelled'].includes(t.state.kind)).map(t => t.id) })),
+        tasks: projectGraphTaskCards(graph), alerts: received.slice(0, 10).map(a => { const chars = Array.from(a.text); return { alert_id: a.id, from: a.from, kind: a.kind, ...(a.task_id ? { task_id: a.task_id } : {}), ...(a.task_version ? { task_version: a.task_version } : {}), received_at: a.receivedAt, text: chars.slice(0, 2000).join(''), ...(chars.length > 2000 ? { truncated: true, text_length: chars.length } : {}) }; }), alerts_omitted: Math.max(0, received.length - 10) };
+}