@sema-agent/client-core 0.94.0 → 0.96.0

package/dist/engineCapReader.js

@@ -1,5 +1,5 @@
-import { snapshotCapsGeneration, capsGenerationStillCurrent } from './engineCapsGenerationGuard.js';
-import { capsGenerationMarkOf, retainCapsGenerationMark } from './engineCapsCache.js';
+import { engineCapsLandingOf } from './engineCapsCache.js';
+import { ownDataField } from './ownKey.js';
 function freezeReading(reading, seen = new Set()) {
     if (reading === null || typeof reading !== 'object' || seen.has(reading))
         return reading;
@@ -11,67 +11,54 @@ function freezeReading(reading, seen = new Set()) {
     }
     return reading;
 }
+const PROJECTING = Symbol('projecting');
 export function createEngineCapReader(spec) {
-    const cellByBase = new Map();
+    let memo = new WeakMap();
     return {
-        note(baseUrl, caps, opts) {
+        note(_baseUrl, _caps, _opts) { },
+        observed(baseUrl) {
             if (typeof baseUrl !== 'string' || baseUrl === '')
-                return;
-            const gen = snapshotCapsGeneration(opts);
-            if (gen === null)
-                return;
-            if (!capsGenerationStillCurrent(baseUrl, gen))
-                return;
-            const mark = retainCapsGenerationMark(baseUrl);
+                return spec.makeUnobserved();
+            const landing = engineCapsLandingOf(baseUrl);
+            if (landing === undefined)
+                return spec.makeUnobserved();
+            const hit = memo.get(landing);
+            if (hit === PROJECTING)
+                return spec.makeUnobserved();
+            if (hit !== undefined)
+                return hit.reading === undefined ? spec.makeUnobserved() : hit.reading;
+            const mine = memo;
+            mine.set(landing, PROJECTING);
             let reading;
             try {
-                reading = spec.project(caps);
+                reading = spec.project(landing.caps);
             }
             catch {
                 reading = undefined;
             }
-            if (capsGenerationMarkOf(baseUrl) !== mark)
-                return;
-            if (reading === undefined) {
-                cellByBase.delete(baseUrl);
-                return;
-            }
-            cellByBase.set(baseUrl, { reading: freezeReading(reading), mark });
-        },
-        observed(baseUrl) {
-            if (typeof baseUrl !== 'string' || baseUrl === '')
-                return spec.makeUnobserved();
-            const cell = cellByBase.get(baseUrl);
-            if (cell === undefined)
-                return spec.makeUnobserved();
-            if (cell.mark !== capsGenerationMarkOf(baseUrl)) {
-                cellByBase.delete(baseUrl);
+            if (engineCapsLandingOf(baseUrl) !== landing) {
+                mine.delete(landing);
                 return spec.makeUnobserved();
             }
-            return cell.reading;
-        },
-        forget(baseUrl) {
-            if (typeof baseUrl !== 'string' || baseUrl === '')
-                return;
-            cellByBase.delete(baseUrl);
+            const done = { reading: reading === undefined ? undefined : freezeReading(reading) };
+            mine.set(landing, done);
+            return done.reading === undefined ? spec.makeUnobserved() : done.reading;
         },
         __resetForTests() {
-            cellByBase.clear();
+            memo = new WeakMap();
         },
     };
 }
-export function capsGenerationOf(caps) {
+export function storeSeatOf(caps) {
     try {
-        if (!Object.hasOwn(caps, 'store'))
-            return { generation: 'old', store: 'absent' };
-        const store = caps.store;
+        const store = ownDataField(caps, 'store');
         if (store === undefined)
-            return { generation: 'old', store: 'absent' };
+            return { kind: 'absent' };
         if (typeof store !== 'object' || store === null || Array.isArray(store))
-            return { generation: 'old', store: 'malformed' };
-        return { generation: 'new', store };
+            return { kind: 'malformed' };
+        return { kind: 'object', store };
     }
     catch {
-        return { generation: 'old', store: 'malformed' };
+        return { kind: 'malformed' };
     }
 }

package/dist/engineCapsCache.d.ts

@@ -1,18 +1,26 @@
 export declare function engineCapsGeneration(baseUrl: string): number;
-export declare function capsGenerationMarkOf(baseUrl: string): object | undefined;
-export declare function retainCapsGenerationMark(baseUrl: string): object;
+export declare function engineCapsLandingOf(baseUrl: string): {
+    readonly caps: object;
+} | undefined;
 export declare function kickEngineCapsProbe(baseUrl: string, probe: () => Promise<unknown>): void;
 export declare function engineCapsSettled(baseUrl: string | undefined, opts?: {
     withinMs?: number;
 }): Promise<'settled' | 'timed_out'>;
 export type EngineCapState = 'true' | 'false' | 'unprobed' | 'absent' | 'non_boolean';
 export declare function engineCapState(baseUrl: string | undefined, key: string): EngineCapState;
+export declare function engineCapStateVia(baseUrl: string | undefined, key: string, probe: (signal?: AbortSignal) => Promise<unknown>, opts?: {
+    withinMs?: number;
+    signal?: AbortSignal;
+}): 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';
 } | {
@@ -22,4 +30,7 @@ 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 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,27 +1,24 @@
+import { settleWithinDeadline } from './abortableSleep.js';
+import { ownDataField } from './ownKey.js';
 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)?.n ?? 0;
+    return genByBase.get(baseUrl) ?? 0;
 }
 export function engineCapsGeneration(baseUrl) {
     return capsGeneration(baseUrl);
 }
-export function capsGenerationMarkOf(baseUrl) {
-    return genByBase.get(baseUrl);
-}
-export function retainCapsGenerationMark(baseUrl) {
-    let mark = genByBase.get(baseUrl);
-    if (mark === undefined) {
-        mark = Object.freeze({ n: 0 });
-        genByBase.set(baseUrl, mark);
-    }
-    return mark;
+export function engineCapsLandingOf(baseUrl) {
+    return capsByBase.get(baseUrl);
 }
 export function kickEngineCapsProbe(baseUrl, probe) {
     if (!baseUrl || capsByBase.has(baseUrl) || inFlight.has(baseUrl))
         return;
+    probeByBase.set(baseUrl, probe);
     const gen = capsGeneration(baseUrl);
     inFlight.add(baseUrl);
     let wake = () => { };
@@ -38,9 +35,8 @@ export function kickEngineCapsProbe(baseUrl, probe) {
             const caps = await probe();
             if (gen !== capsGeneration(baseUrl))
                 return;
-            if (caps && typeof caps === 'object') {
-                capsByBase.set(baseUrl, caps);
-            }
+            if (caps && typeof caps === 'object')
+                landCapsSnapshot(baseUrl, gen, caps);
         }
         catch {
         }
@@ -124,59 +120,227 @@ export async function engineCapsSettled(baseUrl, opts) {
 export function engineCapState(baseUrl, key) {
     if (!baseUrl)
         return 'unprobed';
-    const caps = capsByBase.get(baseUrl);
-    if (caps === undefined)
-        return 'unprobed';
-    if (!(key in caps))
-        return 'absent';
-    const v = caps[key];
-    if (v === true)
-        return 'true';
-    if (v === false)
-        return 'false';
-    return 'non_boolean';
+    return capStateIn(capsByBase.get(baseUrl)?.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) {
+    const snapshot = snapshotCapsBody(caps);
+    if (gen !== capsGeneration(baseUrl))
+        return;
+    capsByBase.set(baseUrl, Object.freeze({ caps: snapshot }));
+}
+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 SLOT_UNOBSERVED;
+    try {
+        const v = ownDataField(caps, key);
+        return v === undefined ? SLOT_ABSENT : { kind: 'present', value: v };
+    }
+    catch {
+        return SLOT_UNREADABLE;
+    }
+}
+function capStateIn(caps, key) {
+    const slot = capSlotIn(caps, key);
+    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) {
+    if (signal === undefined) {
+        await p.catch(() => undefined);
+        return;
+    }
+    if (signal.aborted)
+        return;
+    let onAbort;
+    const aborted = new Promise((resolve) => {
+        onAbort = () => resolve();
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        await Promise.race([p.then(() => undefined, () => undefined), aborted]);
+    }
+    finally {
+        if (onAbort !== undefined)
+            signal.removeEventListener('abort', onAbort);
+    }
+}
+export async function engineCapStateVia(baseUrl, key, probe, opts) {
+    const signal = opts?.signal;
+    if (!baseUrl) {
+        try {
+            if (signal?.aborted)
+                return 'unprobed';
+            return capStateIn(await probe(signal), key);
+        }
+        catch {
+            return 'unprobed';
+        }
+    }
+    const now = engineCapState(baseUrl, key);
+    if (now !== 'unprobed')
+        return now;
+    kickEngineCapsProbe(baseUrl, () => probe());
+    await untilSettledOrAborted(engineCapsSettled(baseUrl, opts?.withinMs !== undefined ? { withinMs: opts.withinMs } : undefined), signal);
+    return engineCapState(baseUrl, key);
 }
 export function engineCapTrue(baseUrl, key) {
     return engineCapState(baseUrl, key) === 'true';
 }
 export function engineCapNestedTrue(baseUrl, parentKey, key) {
+    const state = engineCapNestedValue(baseUrl, parentKey, key);
+    return state.kind === 'value' && state.value === true;
+}
+export function engineCapNestedValue(baseUrl, parentKey, key) {
     if (!baseUrl)
-        return false;
-    const parent = capsByBase.get(baseUrl)?.[parentKey];
-    if (parent === null || typeof parent !== 'object')
-        return false;
-    return parent[key] === true;
+        return { kind: 'unobserved' };
+    const parent = capSlotIn(capsByBase.get(baseUrl)?.caps, parentKey);
+    if (parent.kind !== 'present')
+        return valueStateOfSlot(parent);
+    const group = parent.value;
+    if (group === null || typeof group !== 'object')
+        return { kind: 'not_reported' };
+    return valueStateOfSlot(capSlotIn(group, key));
 }
 export function engineCapValue(baseUrl, key) {
     if (!baseUrl)
         return { kind: 'unobserved' };
-    const caps = capsByBase.get(baseUrl);
-    if (caps === undefined)
-        return { kind: 'unobserved' };
-    if (!(key in caps))
-        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(capsByBase.get(baseUrl)?.caps, 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)?.[key];
-    return typeof v === 'string' && v.length > 0 ? v : undefined;
+    const slot = capSlotIn(capsByBase.get(baseUrl)?.caps, 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) ||
         genByBase.has(baseUrl);
     if (hadState) {
-        genByBase.set(baseUrl, Object.freeze({ n: capsGeneration(baseUrl) + 1 }));
+        genByBase.set(baseUrl, capsGeneration(baseUrl) + 1);
         capsByBase.delete(baseUrl);
         inFlight.delete(baseUrl);
         settleByBase.get(baseUrl)?.wake();
@@ -184,9 +348,77 @@ export function invalidateEngineCaps(baseUrl, probe) {
     if (probe !== undefined)
         kickEngineCapsProbe(baseUrl, probe);
 }
+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) || !isPlainCapsBody(caps))
+                    return false;
+                landCapsSnapshot(baseUrl, gen, caps);
+                return gen === capsGeneration(baseUrl);
+            }
+            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;
+        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/engineCredentialRequirement.d.ts

@@ -0,0 +1,9 @@
+export type EngineProbeAnswer = {
+    readonly ok: true;
+} | {
+    readonly status: number;
+} | {
+    readonly transport: true;
+};
+export type EngineCredentialNeed = 'open' | 'requires' | 'undetermined';
+export declare function engineCredentialRequirementOf(answer: EngineProbeAnswer): EngineCredentialNeed;

package/dist/engineCredentialRequirement.js

@@ -0,0 +1,23 @@
+export function engineCredentialRequirementOf(answer) {
+    try {
+        const a = answer;
+        if (typeof a !== 'object' || a === null || Array.isArray(a))
+            return 'undetermined';
+        const ok = Object.getOwnPropertyDescriptor(a, 'ok');
+        const status = Object.getOwnPropertyDescriptor(a, 'status');
+        const transport = Object.getOwnPropertyDescriptor(a, 'transport');
+        const arms = (ok !== undefined ? 1 : 0) + (status !== undefined ? 1 : 0) + (transport !== undefined ? 1 : 0);
+        if (arms !== 1)
+            return 'undetermined';
+        if (ok !== undefined)
+            return Object.hasOwn(ok, 'value') && ok.value === true ? 'open' : 'undetermined';
+        if (status !== undefined) {
+            const value = Object.hasOwn(status, 'value') ? status.value : undefined;
+            return value === 401 || value === 403 ? 'requires' : 'undetermined';
+        }
+        return 'undetermined';
+    }
+    catch {
+        return 'undetermined';
+    }
+}

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 {};