@sema-agent/client-core 0.107.0 → 0.109.0

package/dist/localEngineSeatReading.js

@@ -0,0 +1,294 @@
+import { localEngineCurrentCard } from './localEngineStep.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { displayUntrusted } from './displayUntrusted.js';
+import { ownSnapshotTyped, readOwnDataValue } from './ownKey.js';
+import { engineIdentityVerdict } from './engineIdentity.js';
+function own(v, key) {
+    if (typeof v !== 'object' || v === null)
+        return undefined;
+    try {
+        return readOwnDataValue(v, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+function deepFreeze(v) {
+    if (typeof v === 'object' && v !== null && !Object.isFrozen(v)) {
+        for (const k of Object.keys(v))
+            deepFreeze(v[k]);
+        Object.freeze(v);
+    }
+    return v;
+}
+function say(key, lang, params) {
+    return renderMessage(msg(key, params), lang);
+}
+function principalUnknownLine(lang) {
+    return say('localEngine.principalUnknown', lang, { layer: msg('localEngine.settingsLayer.unspecified') });
+}
+export function localEngineSeatReadingOf(state, host) {
+    try {
+        const snap = ownSnapshotTyped(state);
+        if (snap === undefined)
+            return undefined;
+        const kind = own(snap, 'kind');
+        const ctx = own(snap, 'ctx');
+        let r;
+        switch (kind) {
+            case 'unbound':
+                if (own(ctx, 'demand') === true)
+                    r = { phase: 'waiting', why: 'starting' };
+                else
+                    r = own(own(host, 'principal'), 'kind') === 'unknown' ? { phase: 'down', reason: 'principal-unknown' } : { phase: 'waiting', why: 'dormant' };
+                break;
+            case 'attached':
+                r = { phase: 'attached' };
+                break;
+            case 'pending': {
+                const card = own(snap, 'card') === 'shown' ? localEngineCurrentCard(snap) : undefined;
+                r = { phase: 'pending', serving: own(snap, 'serving') === true, ...(card !== undefined ? { card } : {}) };
+                break;
+            }
+            case 'draining-wait':
+                r = { phase: 'waiting', why: 'draining' };
+                break;
+            case 'unanswered':
+                r = own(snap, 'reason') === 'unverifiable' ? { phase: 'waiting', why: 'unanswered', unverifiable: true } : { phase: 'waiting', why: 'unanswered' };
+                break;
+            case 'down': {
+                const reason = own(snap, 'reason');
+                if (reason === 'lock-unavailable' && own(ctx, 'lockRetry') === 0)
+                    r = { phase: 'waiting', why: 'starting' };
+                else if (typeof reason === 'string' && STATE_DOWN.includes(reason))
+                    r = { phase: 'down', reason: reason };
+                break;
+            }
+            case 'locking': {
+                const intent = own(snap, 'intent');
+                if (own(intent, 'kind') === 'stop')
+                    r = { phase: 'swapping', mode: own(intent, 'mode') === 'forced' ? 'forced' : 'idle' };
+                else
+                    r = own(snap, 'held') === true ? { phase: 'waiting', why: 'starting' } : { phase: 'waiting', why: 'peer' };
+                break;
+            }
+            case 'stopping':
+                r = { phase: 'swapping', mode: own(snap, 'mode') === 'forced' ? 'forced' : 'idle' };
+                break;
+            case 'spawning':
+                r = { phase: 'waiting', why: 'starting' };
+                break;
+            case 'behind': {
+                const running = own(snap, 'running');
+                const mine = own(snap, 'own');
+                if (typeof running === 'string' && running.length > 0 && typeof mine === 'string' && mine.length > 0) {
+                    r = { phase: 'behind', running, own: mine, upgrade: own(host, 'upgrade') === 'available' ? 'available' : 'unavailable' };
+                }
+                break;
+            }
+            default:
+                r = undefined;
+        }
+        return r === undefined ? undefined : deepFreeze(r);
+    }
+    catch {
+        return undefined;
+    }
+}
+const STATE_DOWN = Object.freeze(['lock-unavailable', 'spawn-failed', 'spawn-refused', 'stop-failed', 'crash-loop', 'high-water-unreadable']);
+const DOWN_KEYS = Object.freeze({
+    'lock-unavailable': 'localEngine.down.lockUnavailable',
+    'spawn-failed': 'localEngine.down.spawnFailed',
+    'spawn-refused': 'localEngine.down.spawnRefused',
+    'stop-failed': 'localEngine.down.stopFailed',
+    'crash-loop': 'localEngine.down.crashLoop',
+    'high-water-unreadable': 'localEngine.down.highWaterUnreadable',
+});
+function downSentence(reason, lang) {
+    if (reason === 'principal-unknown')
+        return principalUnknownLine(lang);
+    return typeof reason === 'string' && Object.hasOwn(DOWN_KEYS, reason) ? say(DOWN_KEYS[reason], lang) : undefined;
+}
+export function localEngineSeatSentence(reading, upgrade, lang) {
+    try {
+        const phase = own(reading, 'phase');
+        switch (phase) {
+            case 'waiting': {
+                const why = own(reading, 'why');
+                if (why === 'starting')
+                    return say('localEngine.phase.starting', lang);
+                if (why === 'dormant')
+                    return say('localEngine.phase.dormant', lang);
+                if (why === 'draining')
+                    return say('localEngine.phase.draining', lang);
+                if (why === 'peer')
+                    return say('localEngine.waitingPeer', lang);
+                if (why === 'unanswered')
+                    return say(own(reading, 'unverifiable') === true ? 'localEngine.phase.unverifiable' : 'localEngine.phase.unanswered', lang);
+                return undefined;
+            }
+            case 'pending':
+                return say(own(reading, 'serving') === true ? 'localEngine.banner.pending' : 'localEngine.phase.pendingBlocked', lang);
+            case 'swapping':
+                return say(own(reading, 'mode') === 'forced' ? 'localEngine.phase.swappingForced' : 'localEngine.phase.swappingIdle', lang);
+            case 'down':
+                return downSentence(own(reading, 'reason'), lang);
+            case 'behind': {
+                const running = own(reading, 'running');
+                const mine = own(reading, 'own');
+                if (typeof running !== 'string' || typeof mine !== 'string')
+                    return undefined;
+                const params = { running: displayUntrusted(running, { max: 64 }), own: displayUntrusted(mine, { max: 64 }) };
+                return say(upgrade === 'cli-update' ? 'localEngine.behind.cliUpdate' : 'localEngine.behind.appUpdate', lang, params);
+            }
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+export function localEngineNoticeText(notice, lang) {
+    try {
+        switch (own(notice, 'key')) {
+            case 'versionUnknown':
+                return say('localEngine.versionUnknown', lang);
+            case 'highWaterUnreadable':
+                return say('localEngine.down.highWaterUnreadable', lang);
+            case 'crashLoop': {
+                const ms = own(notice, 'retryInMs');
+                return typeof ms === 'number' && Number.isFinite(ms) && ms >= 0 ? say('localEngine.crashLoop.retry', lang, { seconds: Math.ceil(ms / 1000) }) : say('localEngine.crashLoop.stopped', lang);
+            }
+            case 'crashLoopRetry':
+                return say('localEngine.crashLoop.retrying', lang);
+            case 'drainOverdue':
+                return say('localEngine.drainOverdue', lang);
+            case 'engineExited':
+                if (own(notice, 'crashLoopNext') === true)
+                    return say('localEngine.engineExited.crashLoop', lang);
+                return say(own(notice, 'counted') === true ? 'localEngine.engineExited.unexpected' : 'localEngine.engineExited.quiet', lang);
+            case 'cannotVerifyEngine':
+                return say('localEngine.cannotVerifyEngine', lang);
+            case 'lockUnavailable':
+                return say('localEngine.lockUnavailable', lang);
+            case 'prepareFailed': {
+                const reason = own(notice, 'reason');
+                if (reason === 'timeout')
+                    return say('localEngine.prepareFailed.timeout', lang);
+                return say('localEngine.prepareFailed.reason', lang, { reason: displayUntrusted(typeof reason === 'string' ? reason : '', { max: 200 }) });
+            }
+            case 'stopFailed':
+                return say('localEngine.down.stopFailed', lang);
+            case 'spawnFailed':
+                return say(own(notice, 'timeout') === true ? 'localEngine.spawnFailed.timeout' : 'localEngine.down.spawnFailed', lang);
+            case 'lockLost':
+                return say('localEngine.lockLost', lang);
+            case 'forcedLine':
+                return say('localEngine.forcedLine', lang);
+            default:
+                return undefined;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+const FAIL_KEYS = Object.freeze({
+    'local_engine.behind': 'localEngine.headless.behind',
+    'local_engine.legacy_below_floor': 'localEngine.headless.legacyBelowFloor',
+    'local_engine.unresponsive': 'localEngine.headless.unresponsive',
+    'local_engine.swap_pending': 'localEngine.headless.swapPending',
+    'local_engine.drain_overdue': 'localEngine.headless.drainOverdue',
+    'local_engine.unanswered_unverifiable': 'localEngine.headless.unverifiable',
+    'local_engine.lock_unavailable': 'localEngine.down.lockUnavailable',
+    'local_engine.spawn_failed': 'localEngine.down.spawnFailed',
+    'local_engine.spawn_refused': 'localEngine.down.spawnRefused',
+    'local_engine.stop_failed': 'localEngine.down.stopFailed',
+    'local_engine.crash_loop': 'localEngine.down.crashLoop',
+    'local_engine.high_water_unreadable': 'localEngine.down.highWaterUnreadable',
+});
+export function localEngineFailText(code, lang) {
+    try {
+        if (code === 'local_engine.principal_unknown')
+            return principalUnknownLine(lang);
+        return typeof code === 'string' && Object.hasOwn(FAIL_KEYS, code) ? say(FAIL_KEYS[code], lang) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function engineTargetLocalOf(input, lang) {
+    try {
+        const raw = own(input, 'lifecycle');
+        const lifecycle = raw === undefined ? undefined : ownSnapshotTyped(raw);
+        const phase = own(lifecycle, 'phase');
+        if (lifecycle === undefined || typeof phase !== 'string')
+            return Object.freeze({});
+        const out = { lifecycle };
+        if (phase === 'down') {
+            const line = downSentence(own(lifecycle, 'reason'), lang);
+            if (line !== undefined)
+                out.lastBootError = line;
+        }
+        const mcpRaw = own(input, 'mcp');
+        const mcp = mcpRaw === undefined ? undefined : ownSnapshotTyped(mcpRaw);
+        if ((phase === 'attached' || phase === 'pending') && mcp !== undefined)
+            out.mcp = mcp;
+        return deepFreeze(out);
+    }
+    catch {
+        return Object.freeze({});
+    }
+}
+function attachedId(s) {
+    const kind = own(s, 'kind');
+    if (kind === 'attached')
+        return own(own(s, 'engine'), 'identity');
+    if (kind === 'pending' && own(s, 'serving') === true)
+        return own(own(s, 'target'), 'identity');
+    return undefined;
+}
+export function engineRestartOutcomeOf(r) {
+    const lang = own(r, 'lang');
+    try {
+        const before = own(r, 'before');
+        const after = own(r, 'after');
+        const effectsRaw = own(r, 'effects');
+        const effects = Array.isArray(effectsRaw) ? effectsRaw : [];
+        const has = (pred) => effects.some((e) => pred(e));
+        const modelRaw = own(r, 'model');
+        const model = typeof modelRaw === 'string' && modelRaw.length > 0 ? modelRaw : null;
+        const afterKind = own(after, 'kind');
+        if (has((e) => own(e, 'kind') === 'notice' && own(own(e, 'notice'), 'key') === 'prepareFailed')) {
+            return Object.freeze({ state: 'failed', reason: say('localEngine.restartOutcome.failedPrepare', lang) });
+        }
+        if (afterKind === 'down') {
+            const detail = downSentence(own(after, 'reason'), lang) ?? '';
+            return Object.freeze({ state: 'failed', reason: say('localEngine.restartOutcome.failedDown', lang, { detail }) });
+        }
+        const beforeAttached = attachedId(before);
+        if (own(r, 'cause') === 'config' && beforeAttached === undefined && own(r, 'demand') !== 'spawn') {
+            return Object.freeze({ state: 'skipped', reason: say('localEngine.restartOutcome.skippedNoDemand', lang) });
+        }
+        if (afterKind === 'unbound' && own(own(after, 'ctx'), 'demand') !== true) {
+            return Object.freeze({ state: 'skipped', reason: say('localEngine.restartOutcome.skippedNoDemand', lang) });
+        }
+        const afterAttached = attachedId(after);
+        if (afterAttached !== undefined) {
+            const spawned = has((e) => own(e, 'kind') === 'spawn');
+            const changed = beforeAttached === undefined || engineIdentityVerdict(beforeAttached, afterAttached) === 'changed';
+            if (own(after, 'kind') === 'attached' && (spawned || changed)) {
+                return Object.freeze({ state: beforeAttached !== undefined ? 'restarted' : 'started', model });
+            }
+        }
+        if (afterKind === 'pending') {
+            const card = own(after, 'card') === 'shown' || has((e) => own(e, 'kind') === 'card' && own(e, 'show') !== null && own(e, 'show') !== undefined);
+            return Object.freeze({ state: 'pending', reason: say(card ? 'localEngine.restartOutcome.pendingCard' : 'localEngine.restartOutcome.pendingBusy', lang) });
+        }
+        return Object.freeze({ state: 'pending', reason: say('localEngine.restartOutcome.pendingBusy', lang) });
+    }
+    catch {
+        return Object.freeze({ state: 'pending', reason: say('localEngine.restartOutcome.pendingBusy', lang) });
+    }
+}

package/dist/localEngineSpawn.d.ts

@@ -0,0 +1,113 @@
+import type { HostSettingsLayer } from './hostSettingsSource.js';
+import type { UiLanguage } from './env/uiLanguage.js';
+export type LocalEngineSpawnPathSlot = 'configHome' | 'dataRoot' | 'configLocalDir';
+export type LocalEngineSpawnDerived = 'agentDataDir' | 'drainPlusH' | 'operatorSingleUser';
+export type LocalEngineSpawnValue = {
+    readonly kind: 'literal';
+    readonly value: string;
+} | {
+    readonly kind: 'delete';
+} | {
+    readonly kind: 'path';
+    readonly slot: LocalEngineSpawnPathSlot;
+} | {
+    readonly kind: 'derived';
+    readonly from: LocalEngineSpawnDerived;
+};
+export interface LocalEngineSpawnEnvRow {
+    readonly key: string;
+    readonly value: LocalEngineSpawnValue;
+    readonly userOverridable: boolean;
+}
+export declare const LOCAL_ENGINE_SPAWN_ENV: readonly LocalEngineSpawnEnvRow[];
+export declare const LOCAL_ENGINE_HOST_BITS: readonly string[];
+export declare const LOCAL_ENGINE_SPAWN_SHAPE: Readonly<{
+    readonly detachedSession: true;
+    readonly stdio: "engine-log-file";
+}>;
+export declare function localEngineOperatorSingleUserOf(inherited: unknown): 'true' | undefined;
+export interface LocalEngineBudgets {
+    readonly storeLockWaitMs: number;
+    readonly healthWaitBudgetMs: number;
+    readonly stopBoundMs: number;
+    readonly lockWaitMs: number;
+}
+export interface LocalEngineSpawnPaths {
+    readonly configHome: string;
+    readonly dataRoot: string;
+    readonly configLocalDir: string;
+}
+export interface LocalEngineSpawnEnvInput {
+    readonly inherited: unknown;
+    readonly paths: LocalEngineSpawnPaths;
+    readonly hostBits: unknown;
+}
+export interface LocalEngineSpawnApplied {
+    readonly key: string;
+    readonly from: 'table' | 'user' | 'host' | 'derived';
+}
+export interface LocalEngineSpawnEnv {
+    readonly env: Readonly<Record<string, string>>;
+    readonly applied: readonly LocalEngineSpawnApplied[];
+    readonly refusedHostBits: readonly string[];
+    readonly budgets: LocalEngineBudgets;
+}
+export declare function localEngineSpawnEnv(input: LocalEngineSpawnEnvInput): LocalEngineSpawnEnv;
+export type LocalEngineSettingsLayerName = Extract<HostSettingsLayer, 'userSettings' | 'flagSettings' | 'policySettings'>;
+export type LocalEngineSettingsLayers = readonly {
+    readonly layer: LocalEngineSettingsLayerName;
+    readonly read: {
+        readonly state: 'ok';
+        readonly env: unknown;
+    } | {
+        readonly state: 'absent';
+    } | {
+        readonly state: 'unreadable';
+        readonly lastHealthy?: unknown;
+    };
+}[];
+export interface LocalEngineSeedInput {
+    readonly baseline: unknown;
+    readonly external: unknown;
+    readonly layers: LocalEngineSettingsLayers;
+    readonly topLevel: unknown;
+    readonly platform: 'posix' | 'win32';
+}
+export interface LocalEngineSeedFrom {
+    readonly key: string;
+    readonly source: 'baseline' | 'external' | LocalEngineSettingsLayerName | 'top-level';
+}
+export interface LocalEngineSeedDropped {
+    readonly key: string;
+    readonly why: 'pinned-at-entry' | 'top-level-invalid' | 'layer-unreadable';
+}
+export interface LocalEngineSeed {
+    readonly env: Readonly<Record<string, string>>;
+    readonly from: readonly LocalEngineSeedFrom[];
+    readonly dropped: readonly LocalEngineSeedDropped[];
+    readonly refuse?: 'policy-unreadable';
+}
+export declare function localEngineSeedEnv(input: LocalEngineSeedInput): LocalEngineSeed;
+export type LocalEnginePrincipal = {
+    readonly kind: 'principal';
+    readonly principal: string;
+    readonly source: 'settings' | 'default';
+    readonly ignoredProcessOverride?: true;
+} | {
+    readonly kind: 'unknown';
+    readonly layer: LocalEngineSettingsLayerName;
+};
+export interface LocalEnginePrincipalView {
+    readonly layers: LocalEngineSettingsLayers;
+    readonly processEnv: unknown;
+}
+export declare function localEnginePrincipalOf(view: LocalEnginePrincipalView): LocalEnginePrincipal;
+export declare function localEnginePrincipalSentence(p: LocalEnginePrincipal, lang?: UiLanguage): string | undefined;
+export interface LocalEngineBootRefusal {
+    readonly code?: string;
+    readonly hint?: string;
+    readonly text: string;
+}
+export declare function engineBootRefusalOf(lines: readonly string[], scrub: (s: string) => string): LocalEngineBootRefusal | undefined;
+export declare function engineBootRefusalSentence(refusal: LocalEngineBootRefusal, lang?: UiLanguage): string | undefined;
+export declare function localEngineFirstShareSentence(lang?: UiLanguage): string;