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

package/lib/integrations/memory/provider.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+/**
+ * Нейтральный договор внешней памяти (Hindsight и подобные). Harness не
+ * зависит от SDK, MCP или сетевого клиента: реальный адаптер реализует эти
+ * два метода у себя и подключается явно, через opt-in entrypoint
+ * `devcontour-harness/integrations/memory`. Ядро и `./contracts` этот модуль
+ * не импортируют.
+ */
+/** Запрос recall: identity банка/проекта, текст и пределы, которые провайдер обязан соблюдать. */
+export interface MemoryQuery {
+    bank: string;
+    project: string;
+    text: string;
+    maxItems: number;
+    maxBytes: number;
+    maxCostUnits?: number;
+}
+/**
+ * Ответ recall — фактические байты тела ответа провайдера (`body`, JSON по
+ * `memoryRecallBodySchema`). Байты закрепляются как есть: digest считается
+ * от них, а не от пересобранного объекта.
+ */
+export interface MemoryRecallResponse {
+    body: string;
+}
+export declare const memoryItemSchema: z.ZodObject<{
+    id: z.ZodString;
+    text: z.ZodString;
+    score: z.ZodOptional<z.ZodNumber>;
+    mandatory: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type MemoryItem = z.infer<typeof memoryItemSchema>;
+export declare const memoryRecallBodySchema: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        score: z.ZodOptional<z.ZodNumber>;
+        mandatory: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    costUnits: z.ZodOptional<z.ZodNumber>;
+    providerVersion: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type MemoryRecallBody = z.infer<typeof memoryRecallBodySchema>;
+/** Провайдер recall. Ошибка или ответ вне схемы — недоступность, а не пустой успех. */
+export interface MemoryRecallProvider {
+    readonly id: string;
+    recall(query: MemoryQuery, signal: AbortSignal): Promise<MemoryRecallResponse>;
+}
+/**
+ * Документ подтверждённого итога для retain. `documentId` — стабильная
+ * identity одного результата (upsert документа); `operationId` — identity
+ * одной операции доставки (идемпотентность асинхронного retain). Это разные
+ * гарантии: upsert не предотвращает повторную асинхронную обработку.
+ */
+export interface MemoryDocument {
+    bank: string;
+    project: string;
+    documentId: string;
+    operationId: string;
+    content: string;
+    metadata: Record<string, string>;
+}
+export declare const memoryRetainAckSchema: z.ZodObject<{
+    status: z.ZodEnum<{
+        accepted: "accepted";
+        stored: "stored";
+    }>;
+    receipt: z.ZodOptional<z.ZodString>;
+    costUnits: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+export type MemoryRetainAck = z.infer<typeof memoryRetainAckSchema>;
+/** Провайдер retain. Исключение — сбой доставки памяти; harness записывает его отдельно. */
+export interface MemoryRetainProvider {
+    readonly id: string;
+    retain(document: MemoryDocument, signal: AbortSignal): Promise<MemoryRetainAck>;
+}
+export type MemoryProvider = MemoryRecallProvider & MemoryRetainProvider;
+/** ID провайдера входит в ID источника и получателя — та же форма, что у остальных ID. */
+export declare const providerIdSchema: z.ZodString;

package/lib/integrations/memory/provider.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { idSchema } from "../../contracts/index.js";
+export const memoryItemSchema = z.strictObject({
+    id: z.string().min(1).max(200),
+    text: z.string().max(1_000_000),
+    score: z.number().optional(),
+    /** Элемент, который нельзя отбросить по пределу: его обрезка — отказ, а не пометка. */
+    mandatory: z.boolean().optional(),
+});
+export const memoryRecallBodySchema = z.strictObject({
+    items: z.array(memoryItemSchema).max(10_000),
+    /** Стоимость recall в единицах провайдера; учитывается отдельно от coding runtime. */
+    costUnits: z.number().nonnegative().optional(),
+    providerVersion: z.string().min(1).max(100).optional(),
+});
+export const memoryRetainAckSchema = z.strictObject({
+    status: z.enum(['stored', 'accepted']),
+    receipt: z.string().min(1).max(500).optional(),
+    costUnits: z.number().nonnegative().optional(),
+});
+/** ID провайдера входит в ID источника и получателя — та же форма, что у остальных ID. */
+export const providerIdSchema = idSchema;

package/lib/integrations/memory/sink.d.ts

@@ -0,0 +1,56 @@
+import { type DeliveryOutcome, type ResultSink, type RunResult } from '../../contracts/index.ts';
+import { type MemoryDocument, type MemoryRetainProvider } from './provider.ts';
+export interface MemoryResultSinkOptions {
+    /** ID получателя; по умолчанию `memory-<provider.id>` — отдельный от Git и Relay ключ доставки. */
+    id?: string;
+    bank: string;
+    project: string;
+    timeoutMs?: number;
+}
+/** Учёт записи во внешнюю память — отдельно от usage coding runtime. */
+export interface MemoryRetainUsage {
+    retainCalls: number;
+    costUnits: number;
+}
+/**
+ * Детерминированный UUID (форма версии 5, вариант RFC 4122) из hex-digest:
+ * `operation_id` Hindsight — UUID, а повтор обязан дать тот же.
+ */
+export declare function uuidOf(digest: string): string;
+/**
+ * Стабильная identity документа результата: провайдер, bank, project,
+ * поручение, попытка и digest самого результата. Повтор доставки того же
+ * результата даёт тот же `documentId` (upsert), другой результат — другой.
+ */
+export declare const memoryDocumentId: (providerId: string, bank: string, project: string, result: RunResult) => string;
+/**
+ * Текст подтверждённого итога: только то, что записал controller (исход,
+ * SHA, gates и их итоги, находки ревью). Пересказ writer сюда не входит.
+ */
+export declare function memoryContent(result: RunResult): string;
+/**
+ * Получатель подтверждённого итога во внешней памяти. Это обычный
+ * `ResultSink`: harness ведёт его доставку отдельной записью по своему
+ * ключу (`<sink>:<work>:<run>`), так что сбой памяти не трогает принятый
+ * Git-результат и receipt других получателей, а повтор
+ * (`Harness.deliver(work, sink)`) отправляет только память — с тем же
+ * `documentId` и `operationId`, без нового writer.
+ *
+ * Сохраняются только принятые результаты; остальные исходы доставляются
+ * явной отметкой «пропущено» без обращения к провайдеру.
+ */
+export declare class MemoryResultSink implements ResultSink {
+    readonly provider: MemoryRetainProvider;
+    readonly options: MemoryResultSinkOptions;
+    readonly id: string;
+    readonly usage: MemoryRetainUsage;
+    constructor(provider: MemoryRetainProvider, options: MemoryResultSinkOptions);
+    documentId(result: RunResult): string;
+    /** Документ доставки: `operationId` стабилен для ключа доставки и документа. */
+    document(key: string, result: RunResult): MemoryDocument;
+    deliver({ key, result }: {
+        key: string;
+        result: RunResult;
+    }): Promise<DeliveryOutcome>;
+}
+export declare const memoryResultSink: (provider: MemoryRetainProvider, options: MemoryResultSinkOptions) => MemoryResultSink;

package/lib/integrations/memory/sink.js

@@ -0,0 +1,116 @@
+import { HarnessError, digestOf, } from "../../contracts/index.js";
+import { memoryRetainAckSchema, providerIdSchema, } from "./provider.js";
+/**
+ * Детерминированный UUID (форма версии 5, вариант RFC 4122) из hex-digest:
+ * `operation_id` Hindsight — UUID, а повтор обязан дать тот же.
+ */
+export function uuidOf(digest) {
+    const h = digest.slice(0, 32).split('');
+    h[12] = '5';
+    h[16] = ((parseInt(h[16], 16) & 0x3) | 0x8).toString(16);
+    const s = h.join('');
+    return `${s.slice(0, 8)}-${s.slice(8, 12)}-${s.slice(12, 16)}-${s.slice(16, 20)}-${s.slice(20, 32)}`;
+}
+/**
+ * Стабильная identity документа результата: провайдер, bank, project,
+ * поручение, попытка и digest самого результата. Повтор доставки того же
+ * результата даёт тот же `documentId` (upsert), другой результат — другой.
+ */
+export const memoryDocumentId = (providerId, bank, project, result) => 'dch-' +
+    digestOf({
+        provider: providerId,
+        bank,
+        project,
+        work: result.workOrderId,
+        run: result.runId,
+        result: digestOf(result),
+    });
+/**
+ * Текст подтверждённого итога: только то, что записал controller (исход,
+ * SHA, gates и их итоги, находки ревью). Пересказ writer сюда не входит.
+ */
+export function memoryContent(result) {
+    return [
+        `Harness result for work order ${result.workOrderId} (run ${result.runId}): ${result.outcome}.`,
+        `Source: ${result.source.connector} ${result.source.ref} @ ${result.source.revision}.`,
+        result.outcome === 'accepted'
+            ? `Accepted commit: ${result.shas.result} (base ${result.shas.base}).`
+            : `Stop reason: ${result.stopReason.code}: ${result.stopReason.message}`,
+        'Controller evidence: ' +
+            JSON.stringify(result.evidence.map((e) => ({ gate: e.gate, phase: e.phase, passed: e.passed }))),
+        ...(result.findings.length
+            ? ['Review findings: ' + JSON.stringify(result.findings.map((f) => f.message))]
+            : []),
+    ].join('\n');
+}
+/**
+ * Получатель подтверждённого итога во внешней памяти. Это обычный
+ * `ResultSink`: harness ведёт его доставку отдельной записью по своему
+ * ключу (`<sink>:<work>:<run>`), так что сбой памяти не трогает принятый
+ * Git-результат и receipt других получателей, а повтор
+ * (`Harness.deliver(work, sink)`) отправляет только память — с тем же
+ * `documentId` и `operationId`, без нового writer.
+ *
+ * Сохраняются только принятые результаты; остальные исходы доставляются
+ * явной отметкой «пропущено» без обращения к провайдеру.
+ */
+export class MemoryResultSink {
+    provider;
+    options;
+    id;
+    usage = { retainCalls: 0, costUnits: 0 };
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+        providerIdSchema.parse(provider.id);
+        this.id = providerIdSchema.parse(options.id ?? 'memory-' + provider.id);
+    }
+    documentId(result) {
+        return memoryDocumentId(this.provider.id, this.options.bank, this.options.project, result);
+    }
+    /** Документ доставки: `operationId` стабилен для ключа доставки и документа. */
+    document(key, result) {
+        const documentId = this.documentId(result);
+        return {
+            bank: this.options.bank,
+            project: this.options.project,
+            documentId,
+            operationId: uuidOf(digestOf({ key, documentId })),
+            content: memoryContent(result),
+            metadata: {
+                workOrderId: result.workOrderId,
+                runId: result.runId,
+                outcome: result.outcome,
+                sourceConnector: result.source.connector,
+                sourceRef: result.source.ref,
+                sourceRevision: result.source.revision,
+                ...(result.outcome === 'accepted' ? { resultSha: result.shas.result } : {}),
+            },
+        };
+    }
+    async deliver({ key, result }) {
+        if (result.outcome !== 'accepted')
+            return {
+                status: 'delivered',
+                receipt: `skipped: memory retains only accepted results (outcome ${result.outcome})`,
+            };
+        const document = this.document(key, result);
+        this.usage.retainCalls++;
+        const ack = memoryRetainAckSchema.safeParse(await this.provider.retain(document, AbortSignal.timeout(this.options.timeoutMs ?? 30_000)));
+        if (!ack.success)
+            throw new HarnessError('DELIVERY_FAILED', 'Ответ retain вне схемы: ' + ack.error.issues[0]?.message);
+        this.usage.costUnits += ack.data.costUnits ?? 0;
+        return {
+            status: 'delivered',
+            receipt: [
+                `memory:${this.provider.id}`,
+                `bank=${document.bank}`,
+                `document=${document.documentId}`,
+                `operation=${document.operationId}`,
+                `status=${ack.data.status}`,
+                ...(ack.data.receipt ? [`receipt=${ack.data.receipt}`] : []),
+            ].join(' '),
+        };
+    }
+}
+export const memoryResultSink = (provider, options) => new MemoryResultSink(provider, options);

package/lib/integrations/memory/testing.d.ts

@@ -0,0 +1,44 @@
+import type { MemoryDocument, MemoryItem, MemoryProvider, MemoryQuery, MemoryRetainAck } from './provider.ts';
+/**
+ * FIXTURE ONLY. Детерминированный провайдер памяти для тестов: ответы по
+ * сценарию, счётчики обращений, смена ответа, недоступность и отказ retain
+ * до или после записи. Ни сети, ни ключей, ни SDK.
+ */
+export declare class FakeMemoryProvider implements MemoryProvider {
+    readonly id: string;
+    readonly extra: {
+        costUnits?: number;
+        providerVersion?: string;
+    };
+    readonly calls: {
+        recall: number;
+        retain: number;
+    };
+    readonly queries: MemoryQuery[];
+    /** Документы по `documentId` — upsert, как у памяти с document identity. */
+    readonly documents: Map<string, MemoryDocument>;
+    /** Каждая принятая операция retain по порядку (`operationId`). */
+    readonly operations: string[];
+    /** Каждый вызов retain: какой документ и операция пришли (включая неудачные). */
+    readonly log: {
+        documentId: string;
+        operationId: string;
+    }[];
+    private body;
+    private down;
+    private retainFailures;
+    constructor(id: string, items: MemoryItem[], extra?: {
+        costUnits?: number;
+        providerVersion?: string;
+    });
+    /** Новый ответ recall (например, после согласования). */
+    respond(items: MemoryItem[]): void;
+    unavailable(reason?: string): void;
+    available(): void;
+    /** Следующие вызовы retain падают: до записи или после неё (неизвестный исход). */
+    failRetain(...modes: ('before-store' | 'after-store')[]): void;
+    recall(query: MemoryQuery): Promise<{
+        body: string;
+    }>;
+    retain(document: MemoryDocument): Promise<MemoryRetainAck>;
+}

package/lib/integrations/memory/testing.js

@@ -0,0 +1,61 @@
+/**
+ * FIXTURE ONLY. Детерминированный провайдер памяти для тестов: ответы по
+ * сценарию, счётчики обращений, смена ответа, недоступность и отказ retain
+ * до или после записи. Ни сети, ни ключей, ни SDK.
+ */
+export class FakeMemoryProvider {
+    id;
+    extra;
+    calls = { recall: 0, retain: 0 };
+    queries = [];
+    /** Документы по `documentId` — upsert, как у памяти с document identity. */
+    documents = new Map();
+    /** Каждая принятая операция retain по порядку (`operationId`). */
+    operations = [];
+    /** Каждый вызов retain: какой документ и операция пришли (включая неудачные). */
+    log = [];
+    body;
+    down;
+    retainFailures = [];
+    constructor(id, items, extra = {}) {
+        this.id = id;
+        this.extra = extra;
+        this.body = { items, ...extra };
+    }
+    /** Новый ответ recall (например, после согласования). */
+    respond(items) {
+        this.body = { ...this.body, items };
+    }
+    unavailable(reason = 'connection refused') {
+        this.down = reason;
+    }
+    available() {
+        this.down = undefined;
+    }
+    /** Следующие вызовы retain падают: до записи или после неё (неизвестный исход). */
+    failRetain(...modes) {
+        this.retainFailures.push(...modes);
+    }
+    recall(query) {
+        this.calls.recall++;
+        this.queries.push(query);
+        if (this.down)
+            return Promise.reject(new Error(this.down));
+        return Promise.resolve({ body: JSON.stringify(this.body) });
+    }
+    retain(document) {
+        this.calls.retain++;
+        this.log.push({ documentId: document.documentId, operationId: document.operationId });
+        if (this.down)
+            return Promise.reject(new Error(this.down));
+        const failure = this.retainFailures.shift();
+        if (failure === 'before-store')
+            return Promise.reject(new Error('retain failed before store'));
+        this.documents.set(document.documentId, structuredClone(document));
+        if (!this.operations.includes(document.operationId))
+            this.operations.push(document.operationId);
+        if (failure === 'after-store')
+            return Promise.reject(new Error('retain response lost after store'));
+        return Promise.resolve({ status: 'stored', receipt: document.documentId });
+    }
+}

package/lib/integrations/relay-v1/index.d.ts

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { type CheckpointInput, type CheckpointRecord, type CommentRecord, type HistoryMutation, type RelayTransport, type SessionRecord, type TaskColumn, type TaskRead, type TransportErrorKind, type TransportIdentity } from '../connector/transport.ts';
+export declare const RELAY_V1_PROVIDER: "relay-v1-http";
+/** Capability истории работы; без неё методы истории не вызывают routes. */
+export declare const WORK_HISTORY_CAPABILITY = "relay-work-history-v1";
+export declare const relayV1SettingsSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    projectId: z.ZodString;
+    actor: z.ZodString;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxResponseBytes: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type RelayV1Settings = z.input<typeof relayV1SettingsSchema>;
+type Settings = z.output<typeof relayV1SettingsSchema>;
+export interface RelayV1Options {
+    /** Подмена `fetch` (тесты); по умолчанию глобальный `fetch` Node. */
+    fetch?: typeof fetch;
+    /** Генератор requestId; по умолчанию `dc-<uuid>`. Не идемпотентность. */
+    requestId?: () => string;
+    /** Сколько раз перезапускать постраничное чтение при смене версии списка. */
+    maxPageRestarts?: number;
+    /** Сколько раз повторять полное чтение задачи при несогласованных токенах. */
+    maxReadRetries?: number;
+    /** Роль автора комментариев. */
+    actorRole?: 'operator' | 'orchestrator' | 'worker';
+}
+export declare function classifyCode(code: string, status: number, mutation: boolean): TransportErrorKind;
+export declare class RelayV1Transport implements RelayTransport {
+    readonly provider: "relay-v1-http";
+    readonly settings: Readonly<Settings>;
+    private readonly base;
+    private readonly fetchImpl;
+    private readonly nextRequestId;
+    private readonly maxPageRestarts;
+    private readonly maxReadRetries;
+    private readonly actorRole;
+    private capabilities;
+    constructor(settings: Settings, options?: RelayV1Options);
+    private fail;
+    private url;
+    /** Один HTTP-вызов без повторов: envelope, классификация, схема данных. */
+    private call;
+    private transportFailure;
+    private readLimited;
+    /** Полное постраничное чтение offset/limit/version; частичный список не возвращается. */
+    private pages;
+    private pagesOnce;
+    private enc;
+    identity(signal?: AbortSignal): Promise<TransportIdentity>;
+    /** Capability истории (кэш на транспорт); без неё route не вызывается. */
+    private requireHistory;
+    private summary;
+    private readTaskOnce;
+    /** Токен текущей редакции без полного чтения тел: ревизии и версии списков. */
+    private probe;
+    readTask(ref: string, signal?: AbortSignal): Promise<TaskRead>;
+    listComments(ref: string, signal?: AbortSignal): Promise<CommentRecord[]>;
+    addComment(ref: string, input: {
+        title: string;
+        body: string;
+    }, signal?: AbortSignal): Promise<{
+        commentId: string;
+    }>;
+    setCriterion(ref: string, input: {
+        criterionId: string;
+        completed: boolean;
+        ifRevision: number;
+    }, signal?: AbortSignal): Promise<{
+        revision: number;
+    }>;
+    move(ref: string, input: {
+        column: TaskColumn;
+        ifRevision: number;
+    }, signal?: AbortSignal): Promise<{
+        revision: number;
+    }>;
+    private session;
+    private checkpointRecord;
+    private historyPost;
+    startSession(input: {
+        title: string;
+        description: string;
+        client: string;
+        sourceSessionId?: string;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    getSession(ref: string, signal?: AbortSignal): Promise<SessionRecord>;
+    findSessions(marker: string, signal?: AbortSignal): Promise<SessionRecord[]>;
+    checkpoints(sessionRef: string, signal?: AbortSignal): Promise<CheckpointRecord[]>;
+    private checkpointBody;
+    openIntent(sessionRef: string, input: CheckpointInput & {
+        runId: string;
+        ifRevision: number;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    checkpoint(intentRef: string, kind: 'progress' | 'result' | 'cancel', input: CheckpointInput & {
+        runId: string;
+        ifRevision: number;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    fork(intentRef: string, input: {
+        runId: string;
+        ifRevision: number;
+        title: string;
+        description: string;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    attach(sessionRef: string, input: {
+        ifRevision: number;
+        client: string;
+        sourceSessionId?: string;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    takeover(sessionRef: string, input: {
+        ifRevision: number;
+        reason: string;
+        client: string;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+    finishSession(sessionRef: string, outcome: 'complete' | 'cancel', input: {
+        runId?: string;
+        ifRevision: number;
+        result: string;
+    }, signal?: AbortSignal): Promise<HistoryMutation>;
+}
+/** Создаёт транспорт Relay v1 по проверенным настройкам; неверные — `INVALID_INPUT`. */
+export declare function createTransport(settings: unknown, options?: RelayV1Options): RelayV1Transport;
+export {};