@adhdev/mesh-shared 1.0.60-rc.9 → 1.0.60

package/dist/turn-ipc-mission.d.ts

@@ -0,0 +1,250 @@
+/**
+ * turn-ipc — mission, note, tool-call and ledger commands: mission_upsert,
+ * mission_query, mission_list_query, note_upsert, note_forget, tool_call_record,
+ * ledger_query. Part of the turn-ipc wire contract (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+export declare const MESH_MISSION_STATUSES: readonly ["active", "paused", "completed", "abandoned"];
+export type MeshMissionStatusValue = typeof MESH_MISSION_STATUSES[number];
+export declare const isMeshMissionStatusValue: (value: unknown) => value is "active" | "completed" | "paused" | "abandoned";
+export interface MissionBriefWire {
+    goal: string;
+    constraints?: readonly string[];
+    doneCriteria?: readonly string[];
+    handoffNotes?: readonly string[];
+    ownedPaths?: readonly string[];
+}
+export interface MissionUpsertRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Omitted = create a new mission; present = update (must resolve to an existing mission — see mesh-missions.ts MISSION-UPSERT-SILENT-CREATE). */
+    id?: string;
+    title: string;
+    /** Free text — see file-header note on why this is fine over local IPC. */
+    goal?: string;
+    status?: MeshMissionStatusValue;
+    /**
+     * H2: `undefined` = do not touch the stored brief. `null` = explicitly clear it.
+     * A present object with no usable `goal` is treated by the daemon's own
+     * `normalizeMissionBrief` as "no brief" (see mesh-missions.ts upsertMeshMission) —
+     * this wire guard only checks SHAPE, not that decision.
+     */
+    brief?: MissionBriefWire | null;
+}
+export interface MeshMissionRecordWire {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatusValue;
+    /** H2: absent = no brief attached to this mission. */
+    brief?: MissionBriefWire;
+}
+export interface MissionUpsertResponse {
+    mission: MeshMissionRecordWire;
+}
+export declare function decodeMissionUpsertRequest(value: unknown): MissionUpsertRequest | null;
+export declare function isMissionUpsertResponse(value: unknown): value is MissionUpsertResponse;
+export declare function decodeMissionUpsertResponse(value: unknown): MissionUpsertResponse | null;
+export interface MissionQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Omitted = every status. */
+    statuses?: readonly MeshMissionStatusValue[];
+    /** Single-mission lookup (mesh-missions.ts `getMeshMission`'s shape) — mutually exclusive with `statuses`. */
+    id?: string;
+}
+export interface MissionQueryResponse {
+    missions: readonly MeshMissionRecordWire[];
+}
+export declare function decodeMissionQueryRequest(value: unknown): MissionQueryRequest | null;
+export declare function decodeMissionQueryResponse(value: unknown): MissionQueryResponse | null;
+export interface MissionListQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    statuses?: readonly MeshMissionStatusValue[];
+    verbose?: boolean;
+    withStats?: boolean;
+    limit?: number;
+    historyIdLimit?: number;
+    /**
+     * The mesh_status mission projection, computed in the daemon (the MCP no longer
+     * opens the daemon's store for it): 'compact' = `getMeshStatusMissionsCompact`
+     * (live missions goal-elided + folded history), 'verbose' =
+     * `getMeshStatusMissionSummaries({verbose: true})` (live + capped history, full
+     * goal, no stats — stats ride one batched `task_stats_query`). Rows then also
+     * carry `createdAt`/`updatedAt`/`closeCandidateEmittedAt`. When set, every other
+     * option except `historyIdLimit` is ignored. An older daemon rejects the key.
+     */
+    meshStatusView?: 'compact' | 'verbose';
+}
+export interface MeshMissionTaskAggregateWire {
+    total: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    blocked: number;
+    lastActivityAt: string | null;
+}
+export interface MeshMissionStatsWire {
+    missionId: string;
+    taskCount: number;
+    completed: number;
+    failed: number;
+    totalDurationMs: number;
+    wallClockMs: number | null;
+    retries: number;
+    incompleteTaskIds: readonly string[];
+}
+/** Verbose (full-goal) mission row. `goal` present, `goalPreview`/`goalTruncated` absent. */
+export interface MissionListSummaryVerboseWire {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatusValue;
+    tasks: MeshMissionTaskAggregateWire;
+    stats?: MeshMissionStatsWire;
+    /** H2: absent = no brief attached. */
+    brief?: MissionBriefWire;
+    /** `meshStatusView` rows only. */
+    createdAt?: string;
+    updatedAt?: string;
+    closeCandidateEmittedAt?: string | null;
+}
+/** Compact (default) mission row. `goalPreview`/`goalTruncated` present, `goal` absent. */
+export interface MissionListSummarySlimWire {
+    id: string;
+    meshId: string;
+    title: string;
+    goalPreview: string;
+    goalTruncated: boolean;
+    status: MeshMissionStatusValue;
+    tasks: MeshMissionTaskAggregateWire;
+    stats?: MeshMissionStatsWire;
+    /** H2: absent = no brief attached. */
+    brief?: MissionBriefWire;
+    /** `meshStatusView` rows only. */
+    createdAt?: string;
+    updatedAt?: string;
+    closeCandidateEmittedAt?: string | null;
+}
+export type MissionListSummaryWire = MissionListSummaryVerboseWire | MissionListSummarySlimWire;
+export interface MeshMissionHistoryFoldWire {
+    count: number;
+    byStatus: Record<string, number>;
+    missionIds: readonly string[];
+    note: string;
+}
+export interface MissionListQueryResponse {
+    missions: readonly MissionListSummaryWire[];
+    historyFold: MeshMissionHistoryFoldWire | null;
+    truncated: boolean;
+    matched: number;
+    overflowIds?: readonly string[];
+}
+export declare function decodeMissionListQueryRequest(value: unknown): MissionListQueryRequest | null;
+export declare function decodeMissionListQueryResponse(value: unknown): MissionListQueryResponse | null;
+export declare const OPERATING_NOTE_CATEGORIES: readonly ["provider_quirk", "pattern_to_avoid", "recovery_lesson"];
+export type OperatingNoteCategory = typeof OPERATING_NOTE_CATEGORIES[number];
+export interface NoteUpsertRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Free text (local IPC — see the section note). */
+    text: string;
+    category?: OperatingNoteCategory;
+    pinned?: boolean;
+    /** Explicit expiry, ISO-8601. */
+    expiresAt?: string;
+    /** Note id (or subject key) this note supersedes. */
+    supersedes?: string;
+    subjectKey?: string;
+    /** Best-effort identity of the recording coordinator (session id / daemon id / host). */
+    sourceCoordinator?: string;
+}
+export interface NoteUpsertResponse {
+    noteId: string;
+    /** True when the same text was already among the recent live notes (no new note). */
+    deduped: boolean;
+    createdAt: string;
+}
+export declare function decodeNoteUpsertRequest(value: unknown): NoteUpsertRequest | null;
+export declare function decodeNoteUpsertResponse(value: unknown): NoteUpsertResponse | null;
+export interface NoteForgetRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** At least one of `noteId` / `text` (a text forget retracts every note with that exact text, and any recorded later). */
+    noteId?: string;
+    text?: string;
+    reason?: string;
+}
+export interface NoteForgetResponse {
+    /** Live notes this forget hid. */
+    matched: number;
+    tombstoneId: string;
+}
+export declare function decodeNoteForgetRequest(value: unknown): NoteForgetRequest | null;
+export declare function decodeNoteForgetResponse(value: unknown): NoteForgetResponse | null;
+export declare const TOOL_CALLER_ROLES: readonly ["coordinator", "unknown"];
+export type ToolCallerRole = typeof TOOL_CALLER_ROLES[number];
+export interface ToolCallRecordRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** The mesh tool name, e.g. `mesh_status` (identifier, not free text — always a fixed tool-name string). */
+    tool: string;
+    sessionId?: string;
+    callerRole: ToolCallerRole;
+}
+export interface ToolCallRecordResponse {
+    rateLimitExceeded: boolean;
+    callsInWindow: number;
+    /** Short machine-oriented advisory string, or null. Never free text describing content. */
+    advisory: string | null;
+}
+export declare function decodeToolCallRecordRequest(value: unknown): ToolCallRecordRequest | null;
+export declare function decodeToolCallRecordResponse(value: unknown): ToolCallRecordResponse | null;
+export interface LedgerQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** One or more ledger `kind` strings (daemon-core `MeshLedgerKind`; mesh-shared cannot import that union, so these are identifiers here). Omitted = every kind. */
+    kind?: readonly string[];
+    /** ISO-8601 or epoch-ms-as-string — passed through to `readLedgerEntries`'s `since` (parsed via `new Date()`). */
+    since?: string;
+    /** Filter to entries whose nodeId is equivalent to this daemon id (matched via `daemonIdsEquivalent` daemon-side, not raw `===`). */
+    node?: string;
+    tail?: number;
+    /** Also return `getLedgerSummary(meshId)` alongside the entries — saves a second round trip for callers that want both (the common case: every existing call site fetches both together). */
+    includeSummary?: boolean;
+}
+export interface LedgerQueryEntryWire {
+    id: string;
+    meshId: string;
+    timestamp: string;
+    kind: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    /** Unbounded JSON passthrough — see file section's CONTENT BOUNDARY note. */
+    payload: Record<string, unknown>;
+}
+export interface LedgerQuerySummaryWire {
+    meshId: string;
+    totalEntries: number;
+    taskDispatched: number;
+    taskCompleted: number;
+    taskFailed: number;
+    taskStalled: number;
+    sessionLaunched: number;
+    checkpointCreated: number;
+    lastActivityAt: string | null;
+    recentFailures: number;
+}
+export interface LedgerQueryResponse {
+    entries: readonly LedgerQueryEntryWire[];
+    summary?: LedgerQuerySummaryWire;
+}
+export declare function decodeLedgerQueryRequest(value: unknown): LedgerQueryRequest | null;
+export declare function decodeLedgerQueryResponse(value: unknown): LedgerQueryResponse | null;

package/dist/turn-ipc-queue.d.ts

@@ -0,0 +1,196 @@
+/**
+ * turn-ipc — local records, queue composites and active work (C-W9a):
+ * record_local, queue_query, queue_enqueue, queue_enqueue_batch, queue_cancel,
+ * queue_requeue, direct_dispatch_record, active_work_query,
+ * recovery_context_query. Part of the turn-ipc wire contract (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+/** A queue row as the daemon's `getQueue` returns it — a JSON passthrough (see the section note). */
+export type QueueEntryWire = Record<string, unknown> & {
+    id: string;
+    status: string;
+};
+export interface RecordLocalRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** A `MeshLedgerKind` (daemon-core); an identifier here (mesh-shared cannot import that union). */
+    kind: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    payload: Record<string, unknown>;
+}
+export interface RecordLocalResponse {
+    eventId: string;
+    timestamp: string;
+    storedLocally: boolean;
+    published: boolean;
+}
+export declare function decodeRecordLocalRequest(value: unknown): RecordLocalRequest | null;
+export declare function decodeRecordLocalResponse(value: unknown): RecordLocalResponse | null;
+export interface QueueQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Status filter (queue statuses); omitted = every row. */
+    statuses?: readonly string[];
+    /** One row by id (returns 0 or 1 entries). */
+    taskId?: string;
+    /** Project for a VIEW surface: the persisted input envelope → `inputSummary` (summarizeQueueEntryInputForView). */
+    view?: boolean;
+    /**
+     * Also return the per-status row counts of the WHOLE mesh queue (columns only,
+     * no payload parse) — lets a view read only the rows it shows yet report
+     * mesh-wide counts. An older daemon rejects the key.
+     */
+    withCounts?: boolean;
+    /** With `withCounts`: also count terminal rows whose `updated_at` is older than this age. */
+    historicalOlderThanMs?: number;
+    /**
+     * Also return `dependencyHeads`: id/status/cancelReason of every
+     * row the returned entries list in `dependsOn` that is not itself returned —
+     * enough to annotate dependency state without reading the whole queue.
+     */
+    withDependencyHeads?: boolean;
+}
+/** A dependency row reduced to the fields dependency-state annotation reads. */
+export interface QueueDependencyHeadWire {
+    id: string;
+    status: string;
+    cancelReason?: string;
+}
+export interface QueueQueryResponse {
+    entries: readonly QueueEntryWire[];
+    /** `withCounts`: row count per status over the whole mesh queue. */
+    counts?: Record<string, number>;
+    /** `withCounts` + `historicalOlderThanMs`: terminal rows older than that age. */
+    oldHistoricalCount?: number;
+    /** `withDependencyHeads`. */
+    dependencyHeads?: readonly QueueDependencyHeadWire[];
+}
+export declare function decodeQueueQueryRequest(value: unknown): QueueQueryRequest | null;
+export declare function decodeQueueQueryResponse(value: unknown): QueueQueryResponse | null;
+export interface QueueEnqueueRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Free text (the task message — see the section note). */
+    message: string;
+    options?: Record<string, unknown>;
+}
+export interface QueueEnqueueResponse {
+    entry: QueueEntryWire;
+}
+export declare function decodeQueueEnqueueRequest(value: unknown): QueueEnqueueRequest | null;
+export declare function decodeQueueEnqueueResponse(value: unknown): QueueEnqueueResponse | null;
+export interface QueueEnqueueBatchRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** `MeshTaskBatchEntrySpec[]` (daemon-core, JSON passthrough). */
+    specs: readonly Record<string, unknown>[];
+}
+export type QueueEnqueueBatchResponse = {
+    ok: true;
+    tasks: readonly QueueEntryWire[];
+} | {
+    ok: false;
+    refusalCode?: string;
+    message: string;
+    extra?: Record<string, unknown>;
+};
+export declare function decodeQueueEnqueueBatchRequest(value: unknown): QueueEnqueueBatchRequest | null;
+export declare function decodeQueueEnqueueBatchResponse(value: unknown): QueueEnqueueBatchResponse | null;
+export interface QueueCancelRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** Operator reason (free text, local IPC). */
+    reason?: string;
+}
+export interface QueueCancelResponse {
+    /** The cancelled row, or null when no such task. */
+    task: QueueEntryWire | null;
+    /** The row as it was BEFORE the cancel (its assignment is what a caller stops). */
+    before: QueueEntryWire | null;
+}
+export declare function decodeQueueCancelRequest(value: unknown): QueueCancelRequest | null;
+export declare function decodeQueueCancelResponse(value: unknown): QueueCancelResponse | null;
+export interface QueueRequeueRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** `requeueTask` options (reason / targetNodeId / targetSessionId / clear* / force / message / maxRetries / notBefore), JSON passthrough. */
+    options?: Record<string, unknown>;
+}
+export interface QueueRequeueResponse {
+    task: QueueEntryWire | null;
+}
+export declare function decodeQueueRequeueRequest(value: unknown): QueueRequeueRequest | null;
+export declare function decodeQueueRequeueResponse(value: unknown): QueueRequeueResponse | null;
+export interface DirectDispatchRecordRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskId: string;
+    /** Free text (the authored task message — the materialised row keeps it). */
+    message: string;
+    /** `recordDirectDispatchTask` options minus `id` (JSON passthrough). */
+    task?: Record<string, unknown>;
+}
+export interface DirectDispatchRecordResponse {
+    taskRecorded: boolean;
+}
+export declare function decodeDirectDispatchRecordRequest(value: unknown): DirectDispatchRecordRequest | null;
+export declare function decodeDirectDispatchRecordResponse(value: unknown): DirectDispatchRecordResponse | null;
+export interface ActiveWorkQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    /** Live node probe results (`buildMeshActiveWork`'s `nodes`), JSON passthrough. */
+    nodes?: readonly Record<string, unknown>[];
+    /** Substitute queue rows (default: the daemon's `getQueue`). */
+    queue?: readonly Record<string, unknown>[];
+    /** Record tail fed to active work (default 200). */
+    recordTail?: number;
+    includeTerminalDirect?: boolean;
+    /** Default true. */
+    compute?: boolean;
+    includeInputs?: boolean;
+    includeSummary?: boolean;
+    includeSchedulingRuntime?: boolean;
+    /**
+     * The caller's mesh snapshot for the scheduling runtime, JSON passthrough.
+     * Optional since the daemon resolves its own mesh record when it is absent;
+     * an older daemon rejects `includeSchedulingRuntime` without it (the caller's
+     * feature-detect signal to resend with the mesh).
+     */
+    mesh?: Record<string, unknown>;
+}
+export interface ActiveWorkQueryResponse {
+    /** `MeshActiveWorkEvidence` (daemon-core), JSON passthrough; absent when `compute: false`. */
+    activeWork?: Record<string, unknown>;
+    records?: readonly Record<string, unknown>[];
+    directDispatches?: readonly Record<string, unknown>[];
+    /** `MeshLedgerSummary`-shaped record summary. */
+    summary?: Record<string, unknown>;
+    schedulingRuntime?: Record<string, unknown>;
+}
+export declare function decodeActiveWorkQueryRequest(value: unknown): ActiveWorkQueryRequest | null;
+export declare function decodeActiveWorkQueryResponse(value: unknown): ActiveWorkQueryResponse | null;
+export interface RecoveryContextQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    maxRetries?: number;
+    /**
+     * Batch: one context per node id, computed over ONE record read (answers
+     * `contexts`). Exclusive with `nodeId`/`sessionId`. An older daemon rejects it.
+     */
+    nodeIds?: readonly string[];
+}
+export interface RecoveryContextQueryResponse {
+    /** Single mode (nodeId/sessionId). */
+    context?: Record<string, unknown>;
+    /** Batch mode (`nodeIds`): context per node id. */
+    contexts?: Record<string, Record<string, unknown>>;
+}
+export declare function decodeRecoveryContextQueryRequest(value: unknown): RecoveryContextQueryRequest | null;
+export declare function decodeRecoveryContextQueryResponse(value: unknown): RecoveryContextQueryResponse | null;

package/dist/turn-ipc-stats.d.ts

@@ -0,0 +1,72 @@
+/**
+ * turn-ipc — task stats and maintenance commands: task_stats_query,
+ * prune_stale_direct, orphaned_pin_notify. Part of the turn-ipc wire contract
+ * (./turn-ipc.ts).
+ */
+import { TURN_IPC_PROTOCOL_VERSION } from './turn-ipc-guards';
+export interface TaskStatsQueryRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    taskIds?: readonly string[];
+    missionId?: string;
+    tail?: number;
+    /** Also compute `computeMeshMissionStats` — requires `missionId`. */
+    rollup?: boolean;
+    /**
+     * Batch rollups: `computeMeshMissionStats` for every id, over ONE queue read and
+     * ONE record read (answers `missions`, `tasks` empty). Exclusive with
+     * `taskIds`/`missionId`. An older daemon rejects the key.
+     */
+    missionIds?: readonly string[];
+}
+export interface TaskStatsQueryResponse {
+    /** `MeshTaskStats[]`, JSON passthrough. */
+    tasks: readonly Record<string, unknown>[];
+    /** `MeshMissionStats`, JSON passthrough; present only when `rollup: true` was requested and satisfiable. */
+    mission?: Record<string, unknown>;
+    /** Batch mode: `MeshMissionStats` per requested mission id, JSON passthrough. */
+    missions?: Record<string, Record<string, unknown>>;
+}
+export declare function decodeTaskStatsQueryRequest(value: unknown): TaskStatsQueryRequest | null;
+export declare function decodeTaskStatsQueryResponse(value: unknown): TaskStatsQueryResponse | null;
+export interface PruneStaleDirectRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    execute?: boolean;
+    includeTerminal?: boolean;
+    source?: string;
+}
+export interface PruneStaleDirectResponse {
+    mode: 'execute' | 'dry_run';
+    includeTerminal: boolean;
+    candidateCount: number;
+    /** `MeshActiveWorkRecord[]`, JSON passthrough. */
+    prunable: readonly Record<string, unknown>[];
+    prunedCount: number;
+    preservedUnacknowledged: readonly Record<string, unknown>[];
+    preservedLedgerOnly: readonly Record<string, unknown>[];
+    preservedNotOrphan: readonly Record<string, unknown>[];
+}
+export declare function decodePruneStaleDirectRequest(value: unknown): PruneStaleDirectRequest | null;
+export declare function decodePruneStaleDirectResponse(value: unknown): PruneStaleDirectResponse | null;
+export interface OrphanedPinNotifyRequest {
+    v: typeof TURN_IPC_PROTOCOL_VERSION;
+    meshId: string;
+    stoppedSessionId: string;
+    excludeTaskId?: string;
+    cause?: string;
+    nodeId?: string;
+    coordinatorSessionId?: string;
+}
+export interface OrphanedPinnedTaskWire {
+    taskId: string;
+    title: string;
+    targetSessionId: string;
+    targetNodeId?: string;
+    missionId?: string;
+}
+export interface OrphanedPinNotifyResponse {
+    orphans: readonly OrphanedPinnedTaskWire[];
+}
+export declare function decodeOrphanedPinNotifyRequest(value: unknown): OrphanedPinNotifyRequest | null;
+export declare function decodeOrphanedPinNotifyResponse(value: unknown): OrphanedPinNotifyResponse | null;