@sema-agent/client-core 0.95.0 → 0.97.0

package/dist/engineCapReader.d.ts

@@ -1,16 +1,22 @@
 interface EngineCapReaderSpec<R> {
     name: string;
     project: (caps: unknown) => R | undefined;
-    makeUnobserved: () => R;
 }
+type ReaderUnobserved = {
+    kind: 'unobserved';
+};
+type ReaderUnreadable = {
+    kind: 'unreadable';
+};
 interface EngineCapReader<R> {
     note(baseUrl: string, caps: unknown, opts?: {
         generation?: number;
     }): void;
-    observed(baseUrl: string | undefined): R;
+    observed(baseUrl: string | undefined): R | ReaderUnobserved | ReaderUnreadable;
     __resetForTests(): void;
 }
 export declare function createEngineCapReader<R>(spec: EngineCapReaderSpec<R>): EngineCapReader<R>;
+export declare function unreadableReadingDetail(subject?: string): string;
 export type StoreSeat = {
     kind: 'object';
     store: object;

package/dist/engineCapReader.js

@@ -1,5 +1,7 @@
 import { engineCapsLandingOf } from './engineCapsCache.js';
 import { ownDataField } from './ownKey.js';
+const unobserved = () => ({ kind: 'unobserved' });
+const unreadable = () => ({ kind: 'unreadable' });
 function freezeReading(reading, seen = new Set()) {
     if (reading === null || typeof reading !== 'object' || seen.has(reading))
         return reading;
@@ -18,15 +20,17 @@ export function createEngineCapReader(spec) {
         note(_baseUrl, _caps, _opts) { },
         observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
-                return spec.makeUnobserved();
+                return unobserved();
             const landing = engineCapsLandingOf(baseUrl);
-            if (landing === undefined)
-                return spec.makeUnobserved();
+            if (landing.kind === 'not_landed')
+                return unobserved();
+            if (landing.kind === 'unreadable')
+                return unreadable();
             const hit = memo.get(landing);
             if (hit === PROJECTING)
-                return spec.makeUnobserved();
+                return unobserved();
             if (hit !== undefined)
-                return hit.reading === undefined ? spec.makeUnobserved() : hit.reading;
+                return hit.reading === undefined ? unreadable() : hit.reading;
             const mine = memo;
             mine.set(landing, PROJECTING);
             let reading;
@@ -38,17 +42,21 @@ export function createEngineCapReader(spec) {
             }
             if (engineCapsLandingOf(baseUrl) !== landing) {
                 mine.delete(landing);
-                return spec.makeUnobserved();
+                return unobserved();
             }
             const done = { reading: reading === undefined ? undefined : freezeReading(reading) };
             mine.set(landing, done);
-            return done.reading === undefined ? spec.makeUnobserved() : done.reading;
+            return done.reading === undefined ? unreadable() : done.reading;
         },
         __resetForTests() {
             memo = new WeakMap();
         },
     };
 }
+export function unreadableReadingDetail(subject) {
+    const head = typeof subject === 'string' && subject.length > 0 ? `${subject} could not be read` : 'could not be read';
+    return `${head} — the engine's /v1/capabilities report arrived, but this entry is not in a form this client reads, so it is shown as unknown, not as absent; probing the same engine again will not change it while the engine reports it this way`;
+}
 export function storeSeatOf(caps) {
     try {
         const store = ownDataField(caps, 'store');

package/dist/engineCapsCache.d.ts

@@ -1,7 +1,13 @@
+export type EngineCapsLanding = {
+    readonly kind: 'landed';
+    readonly caps: Readonly<Record<string, unknown>>;
+} | {
+    readonly kind: 'not_landed';
+} | {
+    readonly kind: 'unreadable';
+};
 export declare function engineCapsGeneration(baseUrl: string): number;
-export declare function engineCapsLandingOf(baseUrl: string): {
-    readonly caps: object;
-} | undefined;
+export declare function engineCapsLandingOf(baseUrl: string | undefined): EngineCapsLanding;
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
 export declare function engineCapsSettled(baseUrl: string | undefined, opts?: {
     withinMs?: number;
@@ -14,10 +20,13 @@ export declare function engineCapStateVia(baseUrl: string | undefined, key: stri
 }): Promise<EngineCapState>;
 export declare function engineCapTrue(baseUrl: string | undefined, key: string): boolean;
 export declare function engineCapNestedTrue(baseUrl: string | undefined, parentKey: string, key: string): boolean;
+export declare function engineCapNestedValue(baseUrl: string | undefined, parentKey: string, key: string): EngineCapValueState;
 export type EngineCapValueState = {
     kind: 'unobserved';
 } | {
     kind: 'not_reported';
+} | {
+    kind: 'unreadable';
 } | {
     kind: 'null';
 } | {
@@ -27,4 +36,9 @@ export type EngineCapValueState = {
 export declare function engineCapValue(baseUrl: string | undefined, key: string): EngineCapValueState;
 export declare function engineCapString(baseUrl: string | undefined, key: string): string | undefined;
 export declare function invalidateEngineCaps(baseUrl: string | undefined, probe?: () => Promise<unknown>): void;
+export type EngineCapsProbeRotation = 'started' | 'registered' | 'ignored';
+export declare function rotateEngineCapsProbe(baseUrl: string | undefined, probe: () => Promise<unknown>): EngineCapsProbeRotation;
+export declare function refreshEngineCapsOnce(baseUrl: string | undefined, opts?: {
+    withinMs?: number;
+}): Promise<'settled' | 'timed_out' | 'no_probe'>;
 export declare function __resetEngineCapsCacheForTests(): void;

package/dist/engineCapsCache.js

@@ -1,7 +1,12 @@
+import { settleWithinDeadline } from './abortableSleep.js';
+import { ownDataField } from './ownKey.js';
+const NOT_LANDED = Object.freeze({ kind: 'not_landed' });
 const capsByBase = new Map();
 const inFlight = new Set();
 const settleByBase = new Map();
 const genByBase = new Map();
+const probeByBase = new Map();
+const refreshByBase = new Map();
 function capsGeneration(baseUrl) {
     return genByBase.get(baseUrl) ?? 0;
 }
@@ -9,11 +14,17 @@ export function engineCapsGeneration(baseUrl) {
     return capsGeneration(baseUrl);
 }
 export function engineCapsLandingOf(baseUrl) {
-    return capsByBase.get(baseUrl);
+    if (typeof baseUrl !== 'string' || baseUrl === '')
+        return NOT_LANDED;
+    return capsByBase.get(baseUrl) ?? NOT_LANDED;
 }
 export function kickEngineCapsProbe(baseUrl, probe) {
+    startEngineCapsProbe(baseUrl, probe);
+}
+function startEngineCapsProbe(baseUrl, probe) {
     if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
-        return;
+        return false;
+    probeByBase.set(baseUrl, probe);
     const gen = capsGeneration(baseUrl);
     inFlight.add(baseUrl);
     let wake = () => { };
@@ -30,9 +41,7 @@ export function kickEngineCapsProbe(baseUrl, probe) {
             const caps = await probe();
             if (gen !== capsGeneration(baseUrl))
                 return;
-            if (caps && typeof caps === 'object') {
-                capsByBase.set(baseUrl, Object.freeze({ caps: caps }));
-            }
+            landCapsSnapshot(baseUrl, gen, caps);
         }
         catch {
         }
@@ -45,6 +54,7 @@ export function kickEngineCapsProbe(baseUrl, probe) {
             markSettled();
         }
     })();
+    return true;
 }
 const MAX_WITHIN_MS = 2_147_483_647;
 function waitBudgetOf(opts) {
@@ -114,25 +124,152 @@ export async function engineCapsSettled(baseUrl, opts) {
     }
 }
 export function engineCapState(baseUrl, key) {
-    if (!baseUrl)
-        return 'unprobed';
-    return capStateIn(capsByBase.get(baseUrl)?.caps, key);
+    return stateOfSlot(slotInLanding(engineCapsLandingOf(baseUrl), key));
 }
-function capStateIn(caps, key) {
+const SNAPSHOT_MAX_DEPTH = 64;
+const SNAPSHOT_MAX_NODES = 100_000;
+const SNAPSHOT_PROBE_KEY = '\u0000capabilities-snapshot-probe\u0000';
+const FOREIGN_PROTOTYPE = Object.freeze(Object.create(null));
+function unreadableError() {
+    return new TypeError('capabilities body position is not readable (accessor or throwing proxy)');
+}
+const UNREADABLE_NODE = new Proxy(Object.freeze({}), {
+    getOwnPropertyDescriptor: () => {
+        throw unreadableError();
+    },
+    ownKeys: () => {
+        throw unreadableError();
+    },
+    has: () => {
+        throw unreadableError();
+    },
+    get: () => {
+        throw unreadableError();
+    },
+    getPrototypeOf: () => {
+        throw unreadableError();
+    },
+});
+function throwingAccessor() {
+    return {
+        get: () => {
+            throw unreadableError();
+        },
+        enumerable: true,
+        configurable: false,
+    };
+}
+function landCapsSnapshot(baseUrl, gen, caps) {
+    if (!isPlainCapsBody(caps))
+        return 'not_a_record';
+    const snapshot = snapshotCapsBody(caps);
+    if (gen !== capsGeneration(baseUrl))
+        return 'superseded';
+    const record = snapshot === UNREADABLE_NODE
+        ? Object.freeze({ kind: 'unreadable' })
+        : Object.freeze({ kind: 'landed', caps: snapshot });
+    capsByBase.set(baseUrl, record);
+    return 'landed';
+}
+function snapshotCapsBody(body) {
+    if (body === null || typeof body !== 'object')
+        return body;
+    const seen = new WeakMap();
+    let nodes = 0;
+    const copy = (src, depth) => {
+        const known = seen.get(src);
+        if (known !== undefined)
+            return known;
+        if (depth > SNAPSHOT_MAX_DEPTH || ++nodes > SNAPSHOT_MAX_NODES)
+            return UNREADABLE_NODE;
+        let keys;
+        let out;
+        let isArray;
+        try {
+            isArray = Array.isArray(src);
+            keys = Object.getOwnPropertyNames(src);
+            Object.getOwnPropertyDescriptor(src, SNAPSHOT_PROBE_KEY);
+            let length = 0;
+            if (isArray) {
+                const ld = Object.getOwnPropertyDescriptor(src, 'length');
+                if (ld === undefined || !Object.hasOwn(ld, 'value') || typeof ld.value !== 'number')
+                    return UNREADABLE_NODE;
+                length = ld.value;
+            }
+            const proto = isArray ? null : Object.getPrototypeOf(src);
+            out = isArray ? new Array(length) : proto === Object.prototype || proto === null ? {} : Object.create(FOREIGN_PROTOTYPE);
+        }
+        catch {
+            return UNREADABLE_NODE;
+        }
+        seen.set(src, out);
+        for (const k of keys) {
+            if (isArray && k === 'length')
+                continue;
+            let d;
+            try {
+                d = Object.getOwnPropertyDescriptor(src, k);
+            }
+            catch {
+                Object.defineProperty(out, k, throwingAccessor());
+                continue;
+            }
+            if (d === undefined)
+                continue;
+            if (!Object.hasOwn(d, 'value')) {
+                Object.defineProperty(out, k, throwingAccessor());
+                continue;
+            }
+            const v = d.value;
+            Object.defineProperty(out, k, {
+                value: v !== null && typeof v === 'object' ? copy(v, depth + 1) : v,
+                enumerable: d.enumerable === true,
+                writable: false,
+                configurable: false,
+            });
+        }
+        Object.freeze(out);
+        return out;
+    };
+    return copy(body, 0);
+}
+const SLOT_UNOBSERVED = Object.freeze({ kind: 'unobserved' });
+const SLOT_ABSENT = Object.freeze({ kind: 'absent' });
+const SLOT_UNREADABLE = Object.freeze({ kind: 'unreadable' });
+function capSlotIn(caps, key) {
     if (caps === undefined || caps === null || typeof caps !== 'object')
-        return 'unprobed';
+        return SLOT_UNOBSERVED;
     try {
-        if (!(key in caps))
-            return 'absent';
-        const v = caps[key];
-        if (v === true)
-            return 'true';
-        if (v === false)
-            return 'false';
-        return 'non_boolean';
+        const v = ownDataField(caps, key);
+        return v === undefined ? SLOT_ABSENT : { kind: 'present', value: v };
     }
     catch {
-        return 'unprobed';
+        return SLOT_UNREADABLE;
+    }
+}
+function slotInLanding(landing, key) {
+    switch (landing.kind) {
+        case 'not_landed':
+            return SLOT_UNOBSERVED;
+        case 'unreadable':
+            return SLOT_UNREADABLE;
+        case 'landed':
+            return capSlotIn(landing.caps, key);
+    }
+}
+function capStateIn(caps, key) {
+    return stateOfSlot(capSlotIn(caps, key));
+}
+function stateOfSlot(slot) {
+    switch (slot.kind) {
+        case 'unobserved':
+            return 'unprobed';
+        case 'absent':
+            return 'absent';
+        case 'unreadable':
+            return 'non_boolean';
+        case 'present':
+            return slot.value === true ? 'true' : slot.value === false ? 'false' : 'non_boolean';
     }
 }
 async function untilSettledOrAborted(p, signal) {
@@ -161,7 +298,8 @@ export async function engineCapStateVia(baseUrl, key, probe, opts) {
         try {
             if (signal?.aborted)
                 return 'unprobed';
-            return capStateIn(await probe(signal), key);
+            const body = await probe(signal);
+            return isPlainCapsBody(body) ? capStateIn(body, key) : 'unprobed';
         }
         catch {
             return 'unprobed';
@@ -178,37 +316,42 @@ export function engineCapTrue(baseUrl, key) {
     return engineCapState(baseUrl, key) === 'true';
 }
 export function engineCapNestedTrue(baseUrl, parentKey, key) {
-    if (!baseUrl)
-        return false;
-    const parent = capsByBase.get(baseUrl)?.caps[parentKey];
-    if (parent === null || typeof parent !== 'object')
-        return false;
-    return parent[key] === true;
+    const state = engineCapNestedValue(baseUrl, parentKey, key);
+    return state.kind === 'value' && state.value === true;
 }
-export function engineCapValue(baseUrl, key) {
-    if (!baseUrl)
-        return { kind: 'unobserved' };
-    const caps = capsByBase.get(baseUrl)?.caps;
-    if (caps === undefined)
-        return { kind: 'unobserved' };
-    if (!(key in caps))
+export function engineCapNestedValue(baseUrl, parentKey, key) {
+    const parent = slotInLanding(engineCapsLandingOf(baseUrl), parentKey);
+    if (parent.kind !== 'present')
+        return valueStateOfSlot(parent);
+    const group = parent.value;
+    if (group === null || typeof group !== 'object')
         return { kind: 'not_reported' };
-    const v = caps[key];
-    if (v === undefined)
-        return { kind: 'not_reported' };
-    if (v === null)
-        return { kind: 'null' };
-    return { kind: 'value', value: v };
+    return valueStateOfSlot(capSlotIn(group, key));
+}
+export function engineCapValue(baseUrl, key) {
+    return valueStateOfSlot(slotInLanding(engineCapsLandingOf(baseUrl), key));
+}
+function valueStateOfSlot(slot) {
+    switch (slot.kind) {
+        case 'unobserved':
+            return { kind: 'unobserved' };
+        case 'absent':
+            return { kind: 'not_reported' };
+        case 'unreadable':
+            return { kind: 'unreadable' };
+        case 'present':
+            return slot.value === null ? { kind: 'null' } : { kind: 'value', value: slot.value };
+    }
 }
 export function engineCapString(baseUrl, key) {
-    if (!baseUrl)
-        return undefined;
-    const v = capsByBase.get(baseUrl)?.caps[key];
-    return typeof v === 'string' && v.length > 0 ? v : undefined;
+    const slot = slotInLanding(engineCapsLandingOf(baseUrl), key);
+    return slot.kind === 'present' && typeof slot.value === 'string' && slot.value.length > 0 ? slot.value : undefined;
 }
 export function invalidateEngineCaps(baseUrl, probe) {
     if (!baseUrl)
         return;
+    if (probe === undefined)
+        probeByBase.delete(baseUrl);
     const hadState = capsByBase.has(baseUrl) ||
         inFlight.has(baseUrl) ||
         settleByBase.has(baseUrl) ||
@@ -222,9 +365,91 @@ export function invalidateEngineCaps(baseUrl, probe) {
     if (probe !== undefined)
         kickEngineCapsProbe(baseUrl, probe);
 }
+export function rotateEngineCapsProbe(baseUrl, probe) {
+    try {
+        if (typeof baseUrl !== 'string' || baseUrl === '' || typeof probe !== 'function')
+            return 'ignored';
+        if (startEngineCapsProbe(baseUrl, probe))
+            return 'started';
+        probeByBase.set(baseUrl, probe);
+        return 'registered';
+    }
+    catch {
+        return 'ignored';
+    }
+}
+export async function refreshEngineCapsOnce(baseUrl, opts) {
+    try {
+        if (typeof baseUrl !== 'string' || baseUrl === '')
+            return 'no_probe';
+        const budget = waitBudgetOf(opts);
+        const probe = probeByBase.get(baseUrl);
+        if (probe === undefined)
+            return 'no_probe';
+        const flying = refreshByBase.get(baseUrl);
+        if (flying !== undefined && flying.gen === capsGeneration(baseUrl))
+            return await awaitRefreshWithin(flying, budget);
+        if (!capsByBase.has(baseUrl)) {
+            kickEngineCapsProbe(baseUrl, probe);
+            return await engineCapsSettled(baseUrl, budget === undefined ? undefined : { withinMs: budget });
+        }
+        const gen = capsGeneration(baseUrl);
+        let finish = () => { };
+        const entry = { gen, promise: new Promise((resolve) => { finish = resolve; }) };
+        refreshByBase.set(baseUrl, entry);
+        void (async () => {
+            try {
+                const caps = await probe();
+                if (gen !== capsGeneration(baseUrl) || !capsByBase.has(baseUrl))
+                    return false;
+                return landCapsSnapshot(baseUrl, gen, caps) === 'landed';
+            }
+            catch {
+                return false;
+            }
+            finally {
+                if (refreshByBase.get(baseUrl) === entry)
+                    refreshByBase.delete(baseUrl);
+            }
+        })().then(finish);
+        return await awaitRefreshWithin(entry, budget);
+    }
+    catch {
+        return 'timed_out';
+    }
+}
+function isPlainCapsBody(caps) {
+    try {
+        if (typeof caps !== 'object' || caps === null)
+            return false;
+        if (Array.isArray(caps))
+            return false;
+        const proto = Object.getPrototypeOf(caps);
+        if (proto !== null && Object.getPrototypeOf(proto) !== null)
+            return false;
+        for (const key of Reflect.ownKeys(caps))
+            Object.getOwnPropertyDescriptor(caps, key);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function awaitRefreshWithin(entry, budget) {
+    if (budget === undefined) {
+        await entry.promise;
+        return 'settled';
+    }
+    if (budget === 0)
+        return 'timed_out';
+    const out = await settleWithinDeadline(budget, () => entry.promise);
+    return out.kind === 'deadline' ? 'timed_out' : 'settled';
+}
 export function __resetEngineCapsCacheForTests() {
     capsByBase.clear();
     inFlight.clear();
     settleByBase.clear();
     genByBase.clear();
+    probeByBase.clear();
+    refreshByBase.clear();
 }

package/dist/engineDirectory.d.ts

@@ -0,0 +1,79 @@
+declare const KIND_WORDS: readonly ["managed"];
+declare const POSTURE_WORDS: readonly ["single", "multi"];
+declare const RULE_WORDS: readonly ["only-one", "none", "ambiguous"];
+export type EngineKindWord = (typeof KIND_WORDS)[number];
+export type EnginePostureWord = (typeof POSTURE_WORDS)[number];
+export type MeEngineRuleWord = (typeof RULE_WORDS)[number];
+export type OpenWordReading<K extends string> = {
+    readonly kind: 'listed';
+    readonly word: K;
+} | {
+    readonly kind: 'unlisted';
+    readonly word: string;
+} | {
+    readonly kind: 'unreadable';
+};
+export interface EngineRowReading {
+    readonly name: string;
+    readonly kind: OpenWordReading<EngineKindWord>;
+    readonly scope: string | undefined;
+    readonly online: boolean | undefined;
+    readonly posture: OpenWordReading<EnginePostureWord>;
+    readonly viaCenter: string;
+}
+export interface EngineRowSet {
+    readonly rows: readonly EngineRowReading[];
+    readonly unreadableRows: number;
+    readonly unreadableNames: readonly string[];
+}
+export type MeEngineTargetReading = {
+    readonly kind: 'row';
+    readonly row: EngineRowReading;
+} | {
+    readonly kind: 'null';
+} | {
+    readonly kind: 'unreadable';
+};
+export interface MeEngineReading {
+    readonly rule: OpenWordReading<MeEngineRuleWord>;
+    readonly target: MeEngineTargetReading;
+    readonly candidates: EngineRowSet | undefined;
+}
+export type MeEngineUnresolvedReason = 'body' | 'rule' | 'rule-unlisted' | 'target' | 'candidates' | 'conflict';
+export type MeEngineDecision = {
+    readonly kind: 'connect';
+    readonly engine: EngineRowReading;
+    readonly rule: OpenWordReading<MeEngineRuleWord>;
+} | {
+    readonly kind: 'no-engine';
+} | {
+    readonly kind: 'choose';
+    readonly candidates: EngineRowSet;
+} | {
+    readonly kind: 'unresolved';
+    readonly reason: MeEngineUnresolvedReason;
+    readonly rule: OpenWordReading<MeEngineRuleWord>;
+    readonly candidates: EngineRowSet | undefined;
+};
+export type EngineOverrideDecision = {
+    readonly kind: 'select';
+    readonly engine: EngineRowReading;
+} | {
+    readonly kind: 'not-listed';
+    readonly candidates: EngineRowSet;
+} | {
+    readonly kind: 'duplicate';
+    readonly name: string;
+} | {
+    readonly kind: 'row-unreadable';
+    readonly name: string;
+} | {
+    readonly kind: 'unreadable';
+} | {
+    readonly kind: 'invalid';
+};
+export declare function projectEngineDirectory(body: unknown): EngineRowSet | undefined;
+export declare function projectMeEngine(body: unknown): MeEngineReading | undefined;
+export declare function decideMeEngine(reading: MeEngineReading | undefined): MeEngineDecision;
+export declare function engineOverrideOf(set: EngineRowSet | undefined, requested: unknown): EngineOverrideDecision;
+export {};