@axiom-lattice/gateway 4.6.1 → 4.7.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as http from 'http';
-import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
-import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent } from '@axiom-lattice/core';
+import { ProjectRoomMessage, ProjectBotMembership, ProjectMembership, TaskItem, ChannelAdapter, InboundMessage, Binding, BindingRegistry, ChannelInstallationStore, DispatchResult, ProjectRoomEventScope, ProjectRoomBusinessEventDraft, ProjectRoomScopedBusinessEvent, ProjectRoomBusinessEvent, ProjectRoomEventSubscription, TaskStore, ProjectRoomStore, ProjectBotMembershipStore, ThreadStore, ProjectRoom, Thread, ProjectStore, TaskWorkItemStore, TenantStore, LoggerType, PinoFileOptions } from '@axiom-lattice/protocols';
+import { TrustedAgentMessageDispatcher, TrustedMessageOptions, TaskLifecycleListener, TaskLifecycleService, IMessageQueueStore, Agent, TaskRunRegistry } from '@axiom-lattice/core';
 import * as fastify from 'fastify';
 
 /** Public publisher surface for committed Project Room business facts. */
@@ -764,6 +764,229 @@ declare class AgentTaskConsumer {
     trigger_agent_task(taskRequest: AgentTaskRequest): void;
 }
 
+/** Minimal caller-graph client surface used by recovery. */
+interface RecoveryCallerClient {
+    getState(config: unknown): Promise<unknown>;
+    updateState(config: unknown, values: unknown, asNode?: string): Promise<unknown>;
+    invoke(input: unknown, config: unknown): Promise<unknown>;
+}
+interface TopCallerRecoveryDeps {
+    /**
+     * Resolve a caller's agent client + config from the resolved top caller.
+     *
+     * @param top The resolved top-level caller thread + assistant.
+     * @param tenantId The orphan task's tenant, used to scope the caller client.
+     */
+    callerFor(top: {
+        threadId: string;
+        assistantId?: string;
+    }, tenantId: string): Promise<{
+        client: RecoveryCallerClient;
+        config: unknown;
+        agent?: unknown;
+    } | undefined>;
+    /** Live-run registry (defaults to the shared Core singleton). */
+    registry?: {
+        isLive(taskId: string): boolean;
+    };
+    /** Resume the continuation (tests can call client.invoke(null, config)). */
+    resume(client: RecoveryCallerClient, config: unknown, agent?: unknown): Promise<void>;
+}
+/** Dependencies for an on-demand single-task recovery ({@link recoverTask}). */
+interface RecoverTaskDeps {
+    /** Lifecycle used to converge the orphan to `failed(no_executor)`. */
+    lifecycle: Pick<TaskLifecycleService, "failTask">;
+    /** Live-run registry (defaults to the shared Core singleton). */
+    registry?: TaskRunRegistry;
+    /**
+     * The tenant's other orphan candidates (normally every `in_progress` task),
+     * used to walk the caller chain up to the true top-level caller.
+     *
+     * @remarks
+     * Without this set {@link resolveTopCaller} can only see the target itself,
+     * so a nested middle run would be mistaken for a direct child of its
+     * immediate (frozen) caller. Defaults to `[converged]` when omitted.
+     */
+    orphans?: TaskItem[];
+    /** Resolve a caller's agent client + config from the resolved top caller. */
+    callerFor: TopCallerRecoveryDeps["callerFor"];
+    /** Resume the continuation (tests can call client.invoke(null, config)). */
+    resume: TopCallerRecoveryDeps["resume"];
+}
+/**
+ * Outcome of an on-demand single-task recovery attempt.
+ *
+ * @remarks
+ * - `recovered`: the task was converged and its top-level caller was resumed.
+ * - `skipped`: nothing was changed; `reason` names the guard (for example
+ *   `not_in_progress`, `live`, `middle`, `project_task`, `no_top_caller`,
+ *   `not_found`).
+ * - `converged_no_call`: the task was converged to `failed`, but the caller had
+ *   no pending `task` call left to resolve, so no continuation was resumed.
+ */
+type RecoverTaskResult = {
+    kind: "recovered";
+} | {
+    kind: "skipped";
+    reason: string;
+} | {
+    kind: "converged_no_call";
+};
+/**
+ * Backfills one converged direct-child task's top-level caller.
+ *
+ * @param task The converged orphan task (must carry `context.caller_thread_id`).
+ * @param top The resolved top-level caller.
+ * @param deps Caller resolver, live-run registry, and resume hook.
+ * @returns `"recovered"` or a `"skipped:<reason>"` string.
+ */
+declare function recoverTopCaller(task: TaskItem, top: {
+    threadId: string;
+    assistantId?: string;
+}, deps: TopCallerRecoveryDeps): Promise<string>;
+/**
+ * Recovers a single orphan task on demand, reusing the collapse logic.
+ *
+ * @param task The candidate task (any status).
+ * @param deps Lifecycle, live-run registry, orphan candidate set (for the
+ *   caller-chain walk), caller resolver, and resume hook.
+ * @returns A discriminated outcome: `recovered`, `skipped:<reason>`, or
+ *   `converged_no_call` when the task was converged but the caller had no
+ *   pending `task` call to resolve.
+ * @remarks
+ * Mirrors {@link runOrphanRecovery} for exactly one task: anything not
+ * `in_progress`, or still held by a live run, is skipped; the rest is converged
+ * to `failed` (`no_executor`, ADR-143) and its **top-level** caller is
+ * backfilled. `deps.orphans` must carry the tenant's other `in_progress`
+ * candidates so a nested middle run is correctly skipped (`middle`) instead of
+ * being mistaken for a direct child of its frozen immediate caller.
+ *
+ * This is an **offline/maintenance** entry point (the `task:recover` CLI): run
+ * it when the Gateway is stopped, or from within the Gateway process. The
+ * `live` guard reads the process-local {@link taskRunRegistry}, so it is
+ * meaningful only in-process and cannot detect a run held by another process.
+ *
+ * The convergence actor is `system:on-demand-recovery` (distinct from the
+ * startup sweep's `system:orphan-recovery`), so on-demand convergences are
+ * auditable in the task work-item trail. No HTTP route is added and recovery
+ * semantics are unchanged.
+ */
+declare function recoverTask(task: TaskItem, deps: RecoverTaskDeps): Promise<RecoverTaskResult>;
+/** Walks caller links up to the thread that is not any orphan's run thread. */
+declare function resolveTopCaller(task: TaskItem, orphans: TaskItem[]): {
+    threadId: string;
+    assistantId?: string;
+} | undefined;
+/**
+ * Runs the whole collapse recovery once: reconcile orphan tasks, then backfill
+ * the top-level caller of every direct-child orphan, grouped per top caller.
+ * Best-effort; a failing group is contained and never aborts the others.
+ *
+ * @param deps Reconcile source, caller resolution, resume, and logger.
+ * @returns The recovered and skipped `taskId:reason` entries.
+ */
+declare function runOrphanRecovery(deps: {
+    reconcile: () => Promise<{
+        convergedTasks: TaskItem[];
+    }>;
+    callerFor: TopCallerRecoveryDeps["callerFor"];
+    resume: TopCallerRecoveryDeps["resume"];
+    log: {
+        info(msg: string, ctx: Record<string, unknown>): void;
+        warn(msg: string, ctx: Record<string, unknown>): void;
+    };
+}): Promise<{
+    recovered: string[];
+    skipped: string[];
+}>;
+
+/**
+ * Shared orphan-recovery runtime: the startup sweep and the on-demand
+ * single-task entry point share one dependency shape and one lifecycle.
+ *
+ * @remarks
+ * `recoverAll()` is the behavior-preserving move of the gateway startup block
+ * (reconcile every tenant's orphaned ordinary tasks, then backfill the
+ * top-level caller). `recoverTask()` is the A-lite on-demand entry: no HTTP
+ * route, just a programmatic call used by the `task:recover` CLI/script.
+ */
+
+/** Dependencies shared by the startup sweep and the single-task entry. */
+interface OrphanRecoveryRuntimeDeps {
+    /** Task store used to enumerate tenants' orphans and read one task by id. */
+    taskStore: TaskStore;
+    /** Work-item store used to build the lifecycle when `lifecycle` is omitted. */
+    workItemStore: TaskWorkItemStore;
+    /** Tenant store supplying `getAllTenants()` for the startup sweep. */
+    tenantStore: Pick<TenantStore, "getAllTenants">;
+    /** Lifecycle used to converge orphans (built from the stores when omitted). */
+    lifecycle?: Pick<TaskLifecycleService, "failTask">;
+    /** Resolve a caller's agent client + config from the resolved top caller. */
+    callerFor: TopCallerRecoveryDeps["callerFor"];
+    /** Resume the continuation (tests can call client.invoke(null, config)). */
+    resume: TopCallerRecoveryDeps["resume"];
+    /** Structured logger. */
+    log: {
+        info(msg: string, ctx: Record<string, unknown>): void;
+        warn(msg: string, ctx: Record<string, unknown>): void;
+    };
+}
+/** Entry points returned by {@link createOrphanRecoveryRuntime}. */
+interface OrphanRecoveryRuntime {
+    /** Startup/interval sweep over every tenant's orphaned ordinary tasks. */
+    recoverAll(): Promise<{
+        recovered: string[];
+        skipped: string[];
+    }>;
+    /**
+     * On-demand recovery of exactly one task within one tenant.
+     *
+     * @remarks Offline/maintenance: run when the Gateway is stopped, or from the
+     * Gateway process. The `live` guard reads the process-local task registry and
+     * cannot see a run held by another process. Governed Project tasks are refused
+     * (`skipped:project_task`) so this never bypasses their managed runtime.
+     */
+    recoverTask(input: {
+        tenantId: string;
+        taskId: string;
+    }): Promise<RecoverTaskResult>;
+}
+/**
+ * Builds the shared orphan-recovery runtime.
+ *
+ * @param deps Task/work-item/tenant stores, optional lifecycle, caller
+ *   resolver, resume hook, and logger.
+ * @returns `recoverAll()` (startup sweep) and `recoverTask()` (on-demand).
+ * @remarks
+ * Governed Project tasks are excluded from `recoverAll()` (they have their own
+ * observer-based reconciliation) and from `recoverTask()`
+ * (`skipped:project_task`), so the on-demand entry can never bypass the managed
+ * Project runtime. `recoverTask()` delegates to {@link recoverSingleTask} with
+ * the shared lifecycle and the process-local live-run registry, so it never
+ * converges a task a live run still holds — in-process only.
+ *
+ * @example
+ * ```ts
+ * const runtime = createOrphanRecoveryRuntime({ taskStore, workItemStore, tenantStore, callerFor, resume, log });
+ * await runtime.recoverAll();
+ * const outcome = await runtime.recoverTask({ tenantId, taskId });
+ * ```
+ */
+declare function createOrphanRecoveryRuntime(deps: OrphanRecoveryRuntimeDeps): OrphanRecoveryRuntime;
+
+/**
+ * Builds the caller-resolution and resume hooks used by orphan recovery.
+ *
+ * @returns `callerFor` (resolves a top caller's agent client + config, omitting
+ *   the in-memory `agent` when it is absent) and `resume` (prefers
+ *   `agent.resumeTask()`, otherwise a raw checkpoint continuation via
+ *   `client.invoke(null, config)`).
+ * @remarks
+ * `callerFor` uses `getAgentClientAsync` (falls back to `getAgentClient`) so a
+ * DB-backed assistant that is not resident in memory can still be loaded.
+ */
+declare function createRecoveryCallerDeps(): Pick<TopCallerRecoveryDeps, "callerFor" | "resume">;
+
 /**
  * Logger configuration for gateway
  */
@@ -794,4 +1017,4 @@ declare const LatticeGateway: {
     AgentTaskConsumer: typeof AgentTaskConsumer;
 };
 
-export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig };
+export { type GatewayLoggerConfig, LatticeGateway, type LatticeGatewayConfig, type OrphanRecoveryRuntime, type OrphanRecoveryRuntimeDeps, type RecoverTaskDeps, type RecoverTaskResult, createOrphanRecoveryRuntime, createRecoveryCallerDeps, recoverTask, recoverTopCaller, resolveTopCaller, runOrphanRecovery };