devcontour-harness 0.0.0-stage → 0.1.0-alpha.6

package/lib/control/workflow.js

@@ -0,0 +1,259 @@
+import { randomUUID } from 'node:crypto';
+import { executionDigest, HarnessError, WORKSPACE_OWNER, digestOf, } from "../contracts/index.js";
+/** Стадии работы над графом: 0 — ревью и согласование плана, 1 — исполнение, 2 — завершено. */
+export const GRAPH_STAGES = 2;
+const iso = (ms) => new Date(ms).toISOString();
+export class WorkflowQueue {
+    store;
+    policy;
+    now;
+    subjects;
+    constructor(store, policy, now = Date.now, subjects) {
+        this.store = store;
+        this.policy = policy;
+        this.now = now;
+        this.subjects = subjects;
+    }
+    /** Вход задания. Без предметов хоста — граф: его digest, политика и режим согласования. */
+    bound(kind, id, view) {
+        if (this.subjects)
+            return this.subjects.input(kind, id, view);
+        if (kind !== 'graph')
+            throw new HarnessError('INVALID_INPUT', 'Неизвестный вид задания: ' + kind);
+        const graph = view.graph(id);
+        if (!graph)
+            return undefined;
+        return {
+            digest: digestOf({
+                kind,
+                id,
+                graph: graph.digest,
+                policy: executionDigest(this.policy),
+                approvalMode: this.policy.approvalMode,
+            }),
+        };
+    }
+    /** Digest входа задания; нет предмета — `undefined`. */
+    input(kind, id, view) {
+        return this.bound(kind, id, view)?.digest;
+    }
+    current(job, view) {
+        try {
+            const bound = this.bound(job.kind, job.id, view);
+            return bound?.digest === job.inputDigest && bound.owner === job.owner;
+        }
+        catch (error) {
+            // Удалённый или ставший недопустимым предмет — устаревшее задание, а не
+            // повод блокировать все следующие.
+            if (error instanceof HarnessError)
+                return false;
+            throw error;
+        }
+    }
+    static owner(owner) {
+        return owner ?? WORKSPACE_OWNER;
+    }
+    /** Задания владельца (по умолчанию — общие). */
+    list(owner) {
+        return this.store.read((v) => v.locals('workflow-jobs', WorkflowQueue.owner(owner)).map((r) => r.value));
+    }
+    get(key, owner) {
+        const job = this.store.read((v) => v.local('workflow-jobs', WorkflowQueue.owner(owner), key));
+        if (!job)
+            throw new HarnessError('NOT_FOUND', 'Задание не найдено: ' + key);
+        return job;
+    }
+    /** Безопасное представление задания: без токена и срока владения. */
+    view(key, owner) {
+        const job = this.get(key, owner);
+        return {
+            key: job.key,
+            kind: job.kind,
+            id: job.id,
+            stage: job.stage,
+            status: job.status,
+            attempts: job.attempts,
+            repairs: job.repairs ?? 0,
+            repairBudget: this.policy.repairBudget,
+            ...(job.error ? { error: job.error } : {}),
+            history: job.history.slice(-20),
+        };
+    }
+    /** Поставить задание; повтор того же входа возвращает прежнее, другой автор — отказ. */
+    start(input) {
+        return this.store.transact('workflow.updated', (tx) => {
+            const bound = this.bound(input.kind, input.id, tx);
+            if (!bound)
+                throw new HarnessError('NOT_FOUND', 'Предмет задания не найден: ' + input.id);
+            const digest = bound.digest;
+            const key = digestOf({ kind: input.kind, id: input.id, input: digest });
+            const old = tx.local('workflow-jobs', WorkflowQueue.owner(bound.owner), key);
+            if (old) {
+                if (old.authorRuntime !== input.authorRuntime)
+                    throw new HarnessError('INVALID_INPUT', 'Runtime автора уже закреплён за этим входом: ' + old.authorRuntime);
+                return old;
+            }
+            const job = {
+                kind: input.kind,
+                id: input.id,
+                authorRuntime: input.authorRuntime,
+                maxAttempts: input.maxAttempts ?? 3,
+                key,
+                ...(bound.owner ? { owner: bound.owner } : {}),
+                inputDigest: digest,
+                stage: 0,
+                attempts: 0,
+                status: 'queued',
+                startedAt: iso(this.now()),
+                history: [],
+            };
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(job.owner), key, job);
+            return job;
+        });
+    }
+    /**
+     * Взять стадию задания. Пока применяется политика, стадии не начинаются:
+     * они читали бы прежний контекст. Изменившийся вход — `stale`; исчерпанные
+     * попытки стадии — `failed`. Чужое действующее владение не перехватывается.
+     */
+    claim(key, owner) {
+        return this.store.transact('workflow.updated', (tx) => {
+            // Пока политика применяется — и до паузы операции, по самому запросу, — стадии не начинаются.
+            const control = tx.control();
+            if (control.pauseReason === 'reconfigure' ||
+                (control.reconfigure && !control.reconfigure.appliedAt))
+                return undefined;
+            const job = tx.local('workflow-jobs', WorkflowQueue.owner(owner), key);
+            if (!job)
+                throw new HarnessError('NOT_FOUND', 'Задание не найдено: ' + key);
+            if (!['queued', 'running'].includes(job.status) ||
+                (job.status === 'running' && job.leaseUntil > this.now()))
+                return undefined;
+            const next = { ...job, history: [...job.history] };
+            if (!this.current(job, tx)) {
+                next.status = 'stale';
+                next.error = 'Вход задания изменился или удалён';
+                delete next.token;
+                delete next.leaseUntil;
+            }
+            else if (job.attempts >= job.maxAttempts) {
+                next.status = 'failed';
+                next.error = 'Исчерпаны попытки стадии';
+                delete next.token;
+                delete next.leaseUntil;
+            }
+            else {
+                next.status = 'running';
+                next.token = randomUUID();
+                next.leaseUntil = this.now() + this.policy.leaseMs;
+                next.attempts = job.attempts + 1;
+            }
+            next.history.push({ at: iso(this.now()), stage: job.stage, event: next.status });
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(owner), key, next);
+            return next.status === 'running' ? next : undefined;
+        });
+    }
+    /** Владение заданием и актуальность входа; иначе — отказ. */
+    guard(job, view) {
+        const check = (v) => {
+            const current = v.local('workflow-jobs', WorkflowQueue.owner(job.owner), job.key);
+            if (current?.status !== 'running' ||
+                current.token !== job.token ||
+                current.leaseUntil <= this.now())
+                throw new HarnessError('LEASE_STALE', 'Владение заданием утрачено');
+            if (!this.current(job, v))
+                throw new HarnessError('APPROVAL_STALE', 'Вход задания изменился');
+            return current;
+        };
+        return view ? check(view) : this.store.read(check);
+    }
+    heartbeat(job) {
+        this.store.transact('workflow.updated', (tx) => {
+            const current = this.guard(job, tx);
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(job.owner), job.key, {
+                ...current,
+                leaseUntil: this.now() + this.policy.leaseMs,
+            });
+        });
+    }
+    /**
+     * Завершить стадию. `wait` — стадия ждёт доменного состояния (повтор,
+     * пауза) и внешнего действия не выполняла: попытка стадии возвращается, а
+     * её запись о захвате снимается. Именно запись о захвате: последним в
+     * истории может стоять решение о восстановлении, и оно должно остаться.
+     */
+    finish(job, wait = false, stages = GRAPH_STAGES) {
+        return this.store.transact('workflow.updated', (tx) => {
+            const current = this.guard(job, tx);
+            const next = { ...current, history: [...current.history] };
+            if (!wait) {
+                next.stage = current.stage + 1;
+                next.attempts = 0;
+            }
+            else {
+                next.attempts = current.attempts - 1;
+                const claimed = next.history.map((h) => h.event).lastIndexOf('running');
+                if (claimed >= 0)
+                    next.history.splice(claimed, 1);
+            }
+            next.status = next.stage >= stages ? 'completed' : 'queued';
+            if (next.status === 'completed')
+                next.finishedAt = iso(this.now());
+            delete next.token;
+            delete next.leaseUntil;
+            delete next.error;
+            if (!wait)
+                next.history.push({ at: iso(this.now()), stage: job.stage, event: 'completed' });
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(job.owner), job.key, next);
+            return next;
+        });
+    }
+    /** Отказ стадии: прерванная — снова в очереди, изменившийся вход — `stale`, иначе `failed`. */
+    fail(job, message, interrupted = false) {
+        this.store.transact('workflow.updated', (tx) => {
+            const current = tx.local('workflow-jobs', WorkflowQueue.owner(job.owner), job.key);
+            if (!current || current.token !== job.token || current.status !== 'running')
+                return;
+            const next = {
+                ...current,
+                status: !this.current(job, tx) ? 'stale' : interrupted ? 'queued' : 'failed',
+                error: message.slice(0, 1000),
+            };
+            delete next.token;
+            delete next.leaseUntil;
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(job.owner), job.key, next);
+        });
+    }
+    /**
+     * Записать восстановление и выполнить его одной транзакцией. Счётчик и само
+     * действие неразделимы: прерывание между ними дало бы либо повтор без учёта
+     * (цикл крутился бы мимо бюджета), либо учёт без повтора.
+     */
+    repair(job, event, apply) {
+        return this.store.transact('task.retry', (tx) => {
+            const current = this.guard(job, tx);
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(job.owner), job.key, {
+                ...current,
+                repairs: (current.repairs ?? 0) + 1,
+                history: [...current.history, { at: iso(this.now()), stage: job.stage, event }],
+            });
+            return apply();
+        });
+    }
+    /** Повтор остановленного задания — решение человека, в пределах попыток стадии. */
+    retry(key, owner) {
+        return this.store.transact('workflow.updated', (tx) => {
+            const job = tx.local('workflow-jobs', WorkflowQueue.owner(owner), key);
+            if (!job)
+                throw new HarnessError('NOT_FOUND', 'Задание не найдено: ' + key);
+            if (job.status !== 'failed' || job.attempts >= job.maxAttempts)
+                throw new HarnessError('NOT_READY', 'Повтор задания недоступен; проверьте статус и попытки');
+            if (!this.current(job, tx))
+                throw new HarnessError('APPROVAL_STALE', 'Вход задания изменился: нужно новое задание');
+            const next = { ...job, status: 'queued' };
+            delete next.error;
+            tx.putLocal('workflow-jobs', WorkflowQueue.owner(owner), key, next);
+            return next;
+        });
+    }
+}

package/lib/engine/budget.d.ts

@@ -0,0 +1,345 @@
+import type { BudgetScopes, CallRecord, ExecutionPolicy, ExecutionView } from '../contracts/index.ts';
+import { usageTotals } from './usage.ts';
+/**
+ * Бюджеты расходов и времени вызовов моделей.
+ *
+ * Расход считается по сохранённым записям вызовов, а не по счётчикам попыток:
+ * `retry --reset`, возврат попытки после отказа окружения, переход этапа
+ * очереди и перезапуск процесса его не уменьшают. Ошибочные, идущие и
+ * прерванные вызовы входят в расход. Неизвестная стоимость делает денежный
+ * бюджет неопределённым; что тогда делать, задаёт `budgets.onUnknown`.
+ *
+ * Учёт локален: записи вызовов не переносятся между клонами, поэтому бюджет
+ * считает вызовы этой установки.
+ */
+export type BudgetScope = {
+    kind: 'work' | 'group' | 'total';
+    id?: string;
+};
+/** Правила и области бюджетов: политика и группы хоста. */
+export interface BudgetContext {
+    policy: ExecutionPolicy;
+    scopes: BudgetScopes;
+}
+/**
+ * Прежняя запись вызова о группе: вида предмета нет, но при вызове закреплена
+ * группа без поручения и без попытки. Вызов о поручении закреплял его
+ * `workId`, поэтому совпадение ID предмета с поручением такую запись не
+ * делает расходом одного поручения — она остаётся расходом группы.
+ */
+export declare function legacyGroupCall(r: {
+    runId?: string;
+    subjectKind?: CallRecord['subjectKind'];
+    groupId?: string;
+    workId?: string;
+}): boolean;
+/**
+ * Записи вызовов области. Поручению принадлежат его попытки, вызовы о нём и
+ * вызовы о его группе целиком (ревью плана): правила долевой атрибуции нет,
+ * и вызов о группе не должен считаться нулевым для поручения. Группе — вызовы,
+ * закреплённые за ней при вызове: перенос поручения в другую группу расход не
+ * переносит.
+ */
+export declare function scopeRecords(c: BudgetContext, view: ExecutionView, records: CallRecord[], scope: BudgetScope): {
+    id: string;
+    stage: string;
+    runtime: string;
+    model: string | null;
+    runtimeVersion: string | null;
+    startedAt: string;
+    outcome: "error" | "active" | "returned" | "abandoned";
+    promptBytes: number;
+    promptDigest: string;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        reportedUsd: number | null;
+        complete: boolean;
+        source: "fixture" | "unavailable" | "codex-turn-events" | "claude-result";
+    };
+    costUsd: number | null;
+    costSource: "unknown" | "provider-reported" | "tariff-estimate";
+    repositoryId?: string | undefined;
+    runId?: string | undefined;
+    subjectId?: string | undefined;
+    subjectKind?: "work" | "group" | "other" | undefined;
+    finishedAt?: string | undefined;
+    process?: {
+        id: string;
+        pid: number;
+        startedAt?: number | undefined;
+    } | undefined;
+    abandonedAt?: string | undefined;
+    durationMs?: number | undefined;
+    elapsedMs?: number | undefined;
+    startedHr?: string | undefined;
+    durationUnknown?: true | undefined;
+    bootId?: string | undefined;
+    workId?: string | undefined;
+    groupId?: string | undefined;
+    workIds?: string[] | undefined;
+    price?: {
+        runtime: "codex" | "claude";
+        model: string;
+        effectiveAt: string;
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    } | undefined;
+    diagnostics?: {
+        startedAt: string;
+        finishedAt: string;
+        lastOutputAt: string | null;
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        aborted: boolean;
+        stdoutTail: string;
+        stderrTail: string;
+        processTree?: {
+            available: boolean;
+            processes: {
+                pid: number;
+                parentPid: number;
+                groupPid: number;
+                name: string;
+            }[];
+            reason?: string | undefined;
+        } | undefined;
+    } | undefined;
+}[];
+export type BudgetStatus = {
+    scope: BudgetScope;
+    limit: {
+        usd?: number;
+        timeMs?: number;
+    };
+    spent: ReturnType<typeof usageTotals> & {
+        uncoveredRuns: number;
+        liveCalls: number;
+    };
+    state: 'within' | 'exceeded' | 'undetermined';
+    reason?: string;
+};
+export declare function budgetStatus(c: BudgetContext, view: ExecutionView, scope: BudgetScope, records?: CallRecord[], at?: number): BudgetStatus | undefined;
+/** Бюджеты, относящиеся к поручению: его собственный, его групп и общий. */
+export declare function workBudgets(c: BudgetContext, view: ExecutionView, workId: string, records?: {
+    id: string;
+    stage: string;
+    runtime: string;
+    model: string | null;
+    runtimeVersion: string | null;
+    startedAt: string;
+    outcome: "error" | "active" | "returned" | "abandoned";
+    promptBytes: number;
+    promptDigest: string;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        reportedUsd: number | null;
+        complete: boolean;
+        source: "fixture" | "unavailable" | "codex-turn-events" | "claude-result";
+    };
+    costUsd: number | null;
+    costSource: "unknown" | "provider-reported" | "tariff-estimate";
+    repositoryId?: string | undefined;
+    runId?: string | undefined;
+    subjectId?: string | undefined;
+    subjectKind?: "work" | "group" | "other" | undefined;
+    finishedAt?: string | undefined;
+    process?: {
+        id: string;
+        pid: number;
+        startedAt?: number | undefined;
+    } | undefined;
+    abandonedAt?: string | undefined;
+    durationMs?: number | undefined;
+    elapsedMs?: number | undefined;
+    startedHr?: string | undefined;
+    durationUnknown?: true | undefined;
+    bootId?: string | undefined;
+    workId?: string | undefined;
+    groupId?: string | undefined;
+    workIds?: string[] | undefined;
+    price?: {
+        runtime: "codex" | "claude";
+        model: string;
+        effectiveAt: string;
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    } | undefined;
+    diagnostics?: {
+        startedAt: string;
+        finishedAt: string;
+        lastOutputAt: string | null;
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        aborted: boolean;
+        stdoutTail: string;
+        stderrTail: string;
+        processTree?: {
+            available: boolean;
+            processes: {
+                pid: number;
+                parentPid: number;
+                groupPid: number;
+                name: string;
+            }[];
+            reason?: string | undefined;
+        } | undefined;
+    } | undefined;
+}[], at?: number): BudgetStatus[];
+/** Сведения о вызове: попытка, предмет (поручение, группа, документ), стадия. */
+export interface CallMeta {
+    repositoryId?: string;
+    runId?: string;
+    subjectId?: string;
+    /** Вид предмета: явный вид важнее совпадения ID с поручением. */
+    subjectKind?: CallRecord['subjectKind'];
+    stage: string;
+    /**
+     * Состав группы из входа вызова (ревью плана до регистрации графа): группа и
+     * её поручения закрепляются за расходом на момент вызова, а не по составу,
+     * который хранилище узнает позже.
+     */
+    group?: {
+        id: string;
+        workIds: string[];
+    };
+}
+/**
+ * Бюджеты вызова модели: по его попытке или поручению — бюджеты поручения; о
+ * группе — бюджеты группы и каждого её открытого поручения, за которыми вызов
+ * будет учтён; о прочем (контракт) — общий.
+ */
+export declare function callBudgets(c: BudgetContext, view: ExecutionView, meta: Pick<CallMeta, 'runId' | 'subjectId' | 'subjectKind' | 'group'>, records?: {
+    id: string;
+    stage: string;
+    runtime: string;
+    model: string | null;
+    runtimeVersion: string | null;
+    startedAt: string;
+    outcome: "error" | "active" | "returned" | "abandoned";
+    promptBytes: number;
+    promptDigest: string;
+    usage: {
+        inputTokens: number | null;
+        outputTokens: number | null;
+        cacheReadTokens: number | null;
+        cacheWriteTokens: number | null;
+        reportedUsd: number | null;
+        complete: boolean;
+        source: "fixture" | "unavailable" | "codex-turn-events" | "claude-result";
+    };
+    costUsd: number | null;
+    costSource: "unknown" | "provider-reported" | "tariff-estimate";
+    repositoryId?: string | undefined;
+    runId?: string | undefined;
+    subjectId?: string | undefined;
+    subjectKind?: "work" | "group" | "other" | undefined;
+    finishedAt?: string | undefined;
+    process?: {
+        id: string;
+        pid: number;
+        startedAt?: number | undefined;
+    } | undefined;
+    abandonedAt?: string | undefined;
+    durationMs?: number | undefined;
+    elapsedMs?: number | undefined;
+    startedHr?: string | undefined;
+    durationUnknown?: true | undefined;
+    bootId?: string | undefined;
+    workId?: string | undefined;
+    groupId?: string | undefined;
+    workIds?: string[] | undefined;
+    price?: {
+        runtime: "codex" | "claude";
+        model: string;
+        effectiveAt: string;
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+    } | undefined;
+    diagnostics?: {
+        startedAt: string;
+        finishedAt: string;
+        lastOutputAt: string | null;
+        exitCode: number | null;
+        signal: string | null;
+        timedOut: boolean;
+        aborted: boolean;
+        stdoutTail: string;
+        stderrTail: string;
+        processTree?: {
+            available: boolean;
+            processes: {
+                pid: number;
+                parentPid: number;
+                groupPid: number;
+                name: string;
+            }[];
+            reason?: string | undefined;
+        } | undefined;
+    } | undefined;
+}[], at?: number): BudgetStatus[];
+/**
+ * Поручение и группа вызова на момент вызова: за ними остаётся его расход.
+ * У вызова о группе — её открытые поручения.
+ */
+export declare function callAttribution(c: BudgetContext, view: ExecutionView, meta: Pick<CallMeta, 'runId' | 'subjectId' | 'subjectKind' | 'group'>, all?: boolean): Pick<CallRecord, 'workId' | 'groupId' | 'workIds'>;
+/** Бюджет, который запрещает тратить: превышен или не определён при `onUnknown: stop`. */
+export declare function blockingBudget(c: BudgetContext, statuses: BudgetStatus[]): BudgetStatus | undefined;
+/** Отказ до траты: превышенный или неопределённый бюджет не даёт начать вызов. */
+export declare function assertBudget(c: BudgetContext, statuses: BudgetStatus[]): void;
+/** Компактный вид бюджета для статуса и потребителей. */
+export declare function budgetView(b: BudgetStatus): {
+    reason?: string | undefined;
+    scope: BudgetScope;
+    state: "exceeded" | "undetermined" | "within";
+    limit: {
+        usd?: number;
+        timeMs?: number;
+    };
+    reportedUsd: number;
+    estimatedUsd: number;
+    unknownCalls: number;
+    unfinishedCalls: number;
+    abandonedCalls: number;
+    errorCalls: number;
+    uncoveredRuns: number;
+    durationMs: number;
+    remainingUsd: number | null;
+    remainingMs: number | null;
+};
+/** Бюджеты установки: общий, группы с незавершённой работой, незавершённые поручения. */
+export declare function budgetOverview(c: BudgetContext, view: ExecutionView, records?: CallRecord[]): {
+    onUnknown: "stop" | "continue";
+    budgets: {
+        reason?: string | undefined;
+        scope: BudgetScope;
+        state: "exceeded" | "undetermined" | "within";
+        limit: {
+            usd?: number;
+            timeMs?: number;
+        };
+        reportedUsd: number;
+        estimatedUsd: number;
+        unknownCalls: number;
+        unfinishedCalls: number;
+        abandonedCalls: number;
+        errorCalls: number;
+        uncoveredRuns: number;
+        durationMs: number;
+        remainingUsd: number | null;
+        remainingMs: number | null;
+    }[];
+} | undefined;