@sema-agent/client-core 0.108.0 → 0.109.0

package/dist/localEngineStep.d.ts

@@ -0,0 +1,286 @@
+import { type EngineIdentityView } from './engineIdentity.js';
+import type { LocalEngineRef, LocalEngineVerdict } from './localEngineJudge.js';
+import { type LocalEngineOccupancy } from './localEngineOccupancy.js';
+import { type EngineSwapCard, type EngineSwapCardTarget, type LocalEngineSwapCause } from './localEngineSwapCard.js';
+import { type StopLadderState } from './localEngineStopLadder.js';
+import type { RequestLane } from './request/taskRequest.js';
+import type { LocalEngineBudgets } from './localEngineSpawn.js';
+export interface LocalEnginePolicy {
+    readonly lane: Exclude<RequestLane, 'utility'>;
+    readonly credentialAuto: boolean;
+    readonly budgets: LocalEngineBudgets;
+}
+export interface LocalEngineStepOccupancy extends LocalEngineOccupancy {
+    readonly bgIds: readonly string[] | null;
+}
+export type LocalEngineTarget = EngineSwapCardTarget;
+export type LocalEngineStateDownReason = 'lock-unavailable' | 'spawn-failed' | 'spawn-refused' | 'stop-failed' | 'crash-loop' | 'high-water-unreadable';
+export interface LocalEngineCauseEntry {
+    readonly cause: LocalEngineSwapCause;
+    readonly fingerprint: string;
+}
+export interface LocalEngineAutoTry {
+    readonly cause: LocalEngineSwapCause;
+    readonly target: EngineIdentityView;
+}
+export interface LocalEngineCtx {
+    readonly causes: readonly LocalEngineCauseEntry[];
+    readonly autoTried: readonly LocalEngineAutoTry[];
+    readonly opSeq: number;
+    readonly lockRetry: 0 | 1;
+    readonly attached: {
+        readonly instance: EngineIdentityView;
+        readonly at: number;
+    } | null;
+    readonly demand: boolean;
+    readonly deaths: readonly number[];
+    readonly cooldown: number;
+}
+export interface LocalEngineCardHold {
+    readonly cause: LocalEngineSwapCause;
+    readonly target: LocalEngineTarget;
+    readonly running?: string;
+    readonly own?: string;
+    readonly occupancy: LocalEngineStepOccupancy | null;
+}
+export type LocalEngineLockIntent = {
+    readonly kind: 'spawn';
+} | {
+    readonly kind: 'stop';
+    readonly mode: 'idle' | 'forced';
+    readonly serving: boolean;
+};
+export type LocalEnginePlan = {
+    readonly kind: 'spawn';
+} | {
+    readonly kind: 'stop';
+    readonly target: LocalEngineTarget;
+    readonly mode: 'idle' | 'forced';
+};
+export type LocalEngineRelation = 'attach' | 'version-unknown' | 'ahead';
+export type LocalEngineState = {
+    readonly kind: 'unbound';
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'attached';
+    readonly engine: LocalEngineRef;
+    readonly relation: LocalEngineRelation;
+    readonly since: number;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'pending';
+    readonly target: LocalEngineTarget | null;
+    readonly serving: boolean;
+    readonly relation?: LocalEngineRelation;
+    readonly card: 'shown' | 'hidden';
+    readonly hold?: LocalEngineCardHold;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'draining-wait';
+    readonly engine: LocalEngineRef;
+    readonly deadlineAt: number;
+    readonly overdue: boolean;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'unanswered';
+    readonly pid: number;
+    readonly startedAt?: number;
+    readonly reason: 'no-answer' | 'unverifiable';
+    readonly since: number;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'down';
+    readonly reason: LocalEngineStateDownReason;
+    readonly since: number;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'locking';
+    readonly intent: LocalEngineLockIntent;
+    readonly held: boolean;
+    readonly entry: LocalEngineTarget | null;
+    readonly op: number;
+    readonly since: number;
+    readonly plan: LocalEnginePlan | null;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'stopping';
+    readonly target: LocalEngineTarget;
+    readonly mode: 'idle' | 'forced';
+    readonly ladder: StopLadderState;
+    readonly op: number;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'spawning';
+    readonly forced: boolean;
+    readonly deferred: readonly LocalEngineCauseEntry[];
+    readonly op: number;
+    readonly since: number;
+    readonly ctx: LocalEngineCtx;
+} | {
+    readonly kind: 'behind';
+    readonly running: string;
+    readonly own: string;
+    readonly source: 'running' | 'high-water';
+};
+export type LocalEngineEvent = {
+    readonly kind: 'observed';
+    readonly verdict: LocalEngineVerdict;
+    readonly occupancy?: LocalEngineStepOccupancy;
+    readonly demand: boolean;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'relooked';
+    readonly verdict: LocalEngineVerdict;
+    readonly occupancy?: LocalEngineStepOccupancy;
+    readonly nowMs: number;
+    readonly op: number;
+} | {
+    readonly kind: 'lock';
+    readonly held: boolean;
+    readonly op: number;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'lock-lost';
+    readonly op: number;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'prepared';
+    readonly ok: boolean;
+    readonly reason?: string;
+    readonly occupancy?: LocalEngineStepOccupancy;
+    readonly nowMs: number;
+    readonly op: number;
+} | {
+    readonly kind: 'tick';
+    readonly nowMs: number;
+    readonly alive?: 'alive' | 'gone' | 'unknown';
+    readonly health?: object | null;
+    readonly occupancy?: LocalEngineStepOccupancy;
+} | {
+    readonly kind: 'cause';
+    readonly cause: LocalEngineSwapCause;
+    readonly fingerprint: string;
+    readonly occupancy?: LocalEngineStepOccupancy;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'cause-resolved';
+    readonly cause: LocalEngineSwapCause;
+    readonly fingerprint: string;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'answer';
+    readonly choice: 'force' | 'wait';
+    readonly fingerprint: string;
+    readonly occupancy?: LocalEngineStepOccupancy;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'spawned';
+    readonly verdict: LocalEngineVerdict;
+    readonly op: number;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'spawn-failed';
+    readonly reason?: string;
+    readonly op: number;
+    readonly nowMs: number;
+} | {
+    readonly kind: 'gone';
+    readonly instance: EngineIdentityView;
+    readonly clean: boolean | 'unknown';
+    readonly nowMs: number;
+};
+export declare const LOCAL_ENGINE_FAIL_CODES: readonly ["local_engine.behind", "local_engine.legacy_below_floor", "local_engine.unresponsive", "local_engine.swap_pending", "local_engine.drain_overdue", "local_engine.unanswered_unverifiable", "local_engine.lock_unavailable", "local_engine.spawn_failed", "local_engine.spawn_refused", "local_engine.stop_failed", "local_engine.crash_loop", "local_engine.high_water_unreadable", "local_engine.principal_unknown"];
+export type LocalEngineFailCode = (typeof LOCAL_ENGINE_FAIL_CODES)[number];
+export type LocalEngineNotice = {
+    readonly key: 'versionUnknown';
+} | {
+    readonly key: 'highWaterUnreadable';
+} | {
+    readonly key: 'crashLoop';
+    readonly retryInMs: number | null;
+} | {
+    readonly key: 'crashLoopRetry';
+} | {
+    readonly key: 'drainOverdue';
+} | {
+    readonly key: 'engineExited';
+    readonly counted: boolean;
+    readonly crashLoopNext: boolean;
+} | {
+    readonly key: 'cannotVerifyEngine';
+} | {
+    readonly key: 'lockUnavailable';
+} | {
+    readonly key: 'prepareFailed';
+    readonly reason: string;
+} | {
+    readonly key: 'stopFailed';
+} | {
+    readonly key: 'spawnFailed';
+    readonly timeout: boolean;
+} | {
+    readonly key: 'lockLost';
+} | {
+    readonly key: 'forcedLine';
+};
+export type LocalEngineEffect = {
+    readonly kind: 'attach';
+    readonly engine: LocalEngineRef;
+} | {
+    readonly kind: 'submits';
+    readonly open: boolean;
+    readonly sentence?: 'legacyBelowFloor' | 'behind';
+} | {
+    readonly kind: 'card';
+    readonly show: EngineSwapCard | null;
+} | {
+    readonly kind: 'banner';
+    readonly key: 'pending' | null;
+} | {
+    readonly kind: 'acquire-lock';
+    readonly op: number;
+} | {
+    readonly kind: 'cancel-lock';
+    readonly op: number;
+} | {
+    readonly kind: 'release-lock';
+    readonly op: number;
+} | {
+    readonly kind: 'reread';
+} | {
+    readonly kind: 'prepare';
+    readonly plan: LocalEnginePlan;
+    readonly op: number;
+} | {
+    readonly kind: 'signal';
+    readonly pid: number;
+    readonly startedAt?: number;
+    readonly sig: 'term' | 'kill';
+} | {
+    readonly kind: 'spawn';
+    readonly op: number;
+} | {
+    readonly kind: 'abandon-spawn';
+    readonly op: number;
+} | {
+    readonly kind: 'hand-off';
+} | {
+    readonly kind: 'prompt-upgrade';
+    readonly running: string;
+    readonly own: string;
+    readonly source: 'running' | 'high-water';
+} | {
+    readonly kind: 'fail';
+    readonly code: LocalEngineFailCode;
+} | {
+    readonly kind: 'notice';
+    readonly notice: LocalEngineNotice;
+};
+export interface LocalEngineStepResult {
+    readonly state: LocalEngineState;
+    readonly effects: readonly LocalEngineEffect[];
+}
+export declare const LOCAL_ENGINE_INITIAL_STATE: LocalEngineState;
+export declare function localEngineCurrentCard(s: LocalEngineState): EngineSwapCard | undefined;
+export declare function localEngineStep(state: LocalEngineState, event: LocalEngineEvent, policy: LocalEnginePolicy): LocalEngineStepResult;
+export declare function engineSwapAnswerOutcomeOf(before: LocalEngineState, event: LocalEngineEvent, policy: LocalEnginePolicy): 'started' | 'stale-card' | 'nothing-pending';