@sema-agent/client-core 0.105.0 → 0.106.0

package/dist/sessionEngine.js

@@ -0,0 +1,464 @@
+import { engineNamespaceKeyFor } from './sessionMap.js';
+import { carriesNoCredentialSlots, isCenterRelativePath, tupleOriginUrlOf } from './engineAddress.js';
+import { ownSendableField, readOwnDataNonEmptyString, readOwnDataValue } from './ownKey.js';
+import { slotReadOf } from './wireFailureShape.js';
+import { msg } from './i18n/translate.js';
+const V1 = 'v1';
+const SELF_KEY = JSON.stringify([V1, 'self']);
+const EMPTY = Object.freeze({});
+function isObj(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function isCanonicalAddress(s) {
+    return s !== '' && tupleOriginUrlOf(s) !== undefined && engineNamespaceKeyFor(s) === s;
+}
+function decodeKey(key) {
+    let parsed;
+    try {
+        parsed = JSON.parse(key);
+    }
+    catch {
+        return undefined;
+    }
+    if (!Array.isArray(parsed) || !parsed.every((x) => typeof x === 'string'))
+        return undefined;
+    const t = parsed;
+    if (JSON.stringify(t) !== key || t[0] !== V1)
+        return undefined;
+    if (t[1] === 'self' && t.length === 2)
+        return { identityKind: 'self' };
+    if (t[1] === 'declared' && t.length === 5) {
+        const [, , center, scope, name] = t;
+        return isCanonicalAddress(center) && scope !== '' && name !== '' ? { identityKind: 'declared', center, scope, name } : undefined;
+    }
+    if (t[1] === 'address' && t.length === 3) {
+        const address = t[2];
+        return isCanonicalAddress(address) ? { identityKind: 'address', address } : undefined;
+    }
+    return undefined;
+}
+const fail = (reason) => Object.freeze({ ok: false, reason });
+function selfBinding() {
+    return Object.freeze({ ok: true, identityKind: 'self', key: SELF_KEY, presentation: EMPTY });
+}
+function declaredBinding(center, scope, name, viaCenter) {
+    return Object.freeze({
+        ok: true,
+        identityKind: 'declared',
+        key: JSON.stringify([V1, 'declared', center, scope, name]),
+        presentation: Object.freeze({ center, scope, name }),
+        connect: Object.freeze({ viaCenter }),
+    });
+}
+function addressBinding(raw) {
+    const u = tupleOriginUrlOf(raw);
+    if (u === undefined || !carriesNoCredentialSlots(u))
+        return fail('address-invalid');
+    const address = engineNamespaceKeyFor(raw);
+    return Object.freeze({
+        ok: true,
+        identityKind: 'address',
+        key: JSON.stringify([V1, 'address', address]),
+        presentation: Object.freeze({ address }),
+        connect: Object.freeze({ url: raw }),
+    });
+}
+export function sessionEngineBindingFor(input) {
+    try {
+        if (!isObj(input))
+            return fail('input-invalid');
+        const role = readOwnDataValue(input, 'role');
+        const row = slotReadOf(input, 'row');
+        const address = slotReadOf(input, 'address');
+        const center = slotReadOf(input, 'center');
+        if (role === 'self') {
+            return row.presence === 'absent' && address.presence === 'absent' && center.presence === 'absent' ? selfBinding() : fail('input-invalid');
+        }
+        if (role !== 'external')
+            return fail('input-invalid');
+        const rowGiven = row.presence !== 'absent';
+        if (rowGiven === (address.presence !== 'absent'))
+            return fail('input-invalid');
+        if (!rowGiven) {
+            if (center.presence !== 'absent')
+                return fail('input-invalid');
+            return address.presence === 'present' && typeof address.value === 'string' ? addressBinding(address.value) : fail('address-invalid');
+        }
+        if (row.presence !== 'present' || !isObj(row.value))
+            return fail('row-incomplete');
+        const r = row.value;
+        const name = readOwnDataNonEmptyString(r, 'name');
+        const scope = readOwnDataNonEmptyString(r, 'scope');
+        const viaCenter = readOwnDataNonEmptyString(r, 'viaCenter');
+        if (name === undefined || scope === undefined || viaCenter === undefined || !isCenterRelativePath(viaCenter))
+            return fail('row-incomplete');
+        if (center.presence !== 'present' || typeof center.value !== 'string' || tupleOriginUrlOf(center.value) === undefined)
+            return fail('center-invalid');
+        return declaredBinding(engineNamespaceKeyFor(center.value), scope, name, viaCenter);
+    }
+    catch {
+        return fail('input-invalid');
+    }
+}
+function assignmentOf(kindRaw, keyRaw, connectSlot) {
+    if (kindRaw !== 'local' && kindRaw !== 'cloud')
+        return undefined;
+    if (typeof keyRaw !== 'string')
+        return undefined;
+    const decoded = decodeKey(keyRaw);
+    if (decoded === undefined)
+        return undefined;
+    const connectAbsent = connectSlot.presence === 'absent' || (connectSlot.presence === 'present' && connectSlot.value === undefined);
+    let identity;
+    if (decoded.identityKind === 'self') {
+        if (!connectAbsent)
+            return undefined;
+        identity = selfBinding();
+    }
+    else {
+        if (connectSlot.presence !== 'present' || !isObj(connectSlot.value))
+            return undefined;
+        const c = connectSlot.value;
+        if (decoded.identityKind === 'address') {
+            const url = readOwnDataValue(c, 'url');
+            if (typeof url !== 'string')
+                return undefined;
+            const re = addressBinding(url);
+            if (!re.ok || re.key !== keyRaw)
+                return undefined;
+            identity = re;
+        }
+        else {
+            const viaCenter = readOwnDataNonEmptyString(c, 'viaCenter');
+            if (viaCenter === undefined || !isCenterRelativePath(viaCenter))
+                return undefined;
+            identity = declaredBinding(decoded.center, decoded.scope, decoded.name, viaCenter);
+            if (identity.key !== keyRaw)
+                return undefined;
+        }
+    }
+    return Object.freeze({ kind: kindRaw, identity });
+}
+function sameAssignment(a, b) {
+    if (a.kind !== b.kind || a.identity.key !== b.identity.key || a.identity.identityKind !== b.identity.identityKind)
+        return false;
+    if (a.identity.identityKind === 'address' && b.identity.identityKind === 'address')
+        return a.identity.connect.url === b.identity.connect.url;
+    if (a.identity.identityKind === 'declared' && b.identity.identityKind === 'declared')
+        return a.identity.connect.viaCenter === b.identity.connect.viaCenter;
+    return true;
+}
+function viewOf(a) {
+    const id = a.identity;
+    if (id.identityKind === 'self')
+        return Object.freeze({ kind: a.kind, identityKind: 'self', identity: Object.freeze({ key: id.key, presentation: id.presentation }) });
+    if (id.identityKind === 'declared')
+        return Object.freeze({ kind: a.kind, identityKind: 'declared', identity: Object.freeze({ key: id.key, presentation: id.presentation }) });
+    return Object.freeze({ kind: a.kind, identityKind: 'address', identity: Object.freeze({ key: id.key, presentation: id.presentation }) });
+}
+function snapshotOf(a) {
+    const id = a.identity;
+    if (id.identityKind === 'address')
+        return { kind: a.kind, key: id.key, connect: { url: id.connect.url } };
+    if (id.identityKind === 'declared')
+        return { kind: a.kind, key: id.key, connect: { viaCenter: id.connect.viaCenter } };
+    return { kind: a.kind, key: id.key };
+}
+export function isSessionEngineView(v) {
+    try {
+        if (!isObj(v))
+            return false;
+        const kind = ownSendableField(v, 'kind');
+        if (kind !== 'local' && kind !== 'cloud')
+            return false;
+        const identityKind = ownSendableField(v, 'identityKind');
+        const identity = ownSendableField(v, 'identity');
+        if (!isObj(identity))
+            return false;
+        const key = ownSendableField(identity, 'key');
+        const presentation = ownSendableField(identity, 'presentation');
+        if (typeof key !== 'string' || !isObj(presentation))
+            return false;
+        const decoded = decodeKey(key);
+        if (decoded === undefined || decoded.identityKind !== identityKind)
+            return false;
+        const fields = decoded.identityKind === 'self' ? {} : decoded.identityKind === 'declared' ? { center: decoded.center, scope: decoded.scope, name: decoded.name } : { address: decoded.address };
+        if (Reflect.ownKeys(presentation).length !== Object.keys(fields).length)
+            return false;
+        return Object.keys(fields).every((k) => ownSendableField(presentation, k) === fields[k]);
+    }
+    catch {
+        return false;
+    }
+}
+function entryIdOf(record, key) {
+    const engines = slotReadOf(record, 'engines');
+    if (engines.presence !== 'present' || !isObj(engines.value))
+        return undefined;
+    const entry = slotReadOf(engines.value, key);
+    if (entry.presence !== 'present' || !isObj(entry.value))
+        return undefined;
+    return readOwnDataNonEmptyString(entry.value, 'engineSessionId');
+}
+function hasHistory(record) {
+    const engines = slotReadOf(record, 'engines');
+    if (engines.presence === 'unreadable')
+        return true;
+    if (engines.presence === 'present' && engines.value !== undefined) {
+        if (!isObj(engines.value))
+            return true;
+        if (Reflect.ownKeys(engines.value).length > 0)
+            return true;
+    }
+    const top = slotReadOf(record, 'engineSessionId');
+    if (top.presence === 'unreadable')
+        return true;
+    return top.presence === 'present' && top.value !== undefined && top.value !== '';
+}
+export function readSessionEngine(record) {
+    try {
+        if (record === undefined || record === null)
+            return NONE;
+        if (!isObj(record))
+            return UNRESOLVED;
+        const snap = slotReadOf(record, 'boundEngine');
+        if (snap.presence === 'unreadable')
+            return UNRESOLVED;
+        if (snap.presence === 'present' && snap.value !== undefined) {
+            if (!isObj(snap.value))
+                return UNRESOLVED;
+            const s = snap.value;
+            const binding = assignmentOf(readOwnDataValue(s, 'kind'), readOwnDataValue(s, 'key'), slotReadOf(s, 'connect'));
+            if (binding === undefined)
+                return UNRESOLVED;
+            const uuid = entryIdOf(record, binding.identity.key);
+            if (uuid === undefined)
+                return UNRESOLVED;
+            return Object.freeze({ kind: 'bound', binding, engine: viewOf(binding), uuid });
+        }
+        return hasHistory(record) ? LEGACY : NONE;
+    }
+    catch {
+        return UNRESOLVED;
+    }
+}
+const NONE = Object.freeze({ kind: 'none' });
+const LEGACY = Object.freeze({ kind: 'legacy' });
+const UNRESOLVED = Object.freeze({ kind: 'unresolved' });
+function judgeNotice(a) {
+    return a.identity.identityKind === 'self' && a.kind !== 'local' ? msg('session.engine.selfNotLocal') : undefined;
+}
+function committed(a) {
+    const notice = judgeNotice(a);
+    const engine = viewOf(a);
+    return Object.freeze(notice === undefined ? { kind: 'committed', engine } : { kind: 'committed', engine, notice });
+}
+const unresolvedCommit = (reason) => Object.freeze({ kind: 'unresolved', reason });
+const STORE_FAILED = Object.freeze({ kind: 'store-failed' });
+function requestAssignmentOf(raw) {
+    if (!isObj(raw))
+        return undefined;
+    const identity = readOwnDataValue(raw, 'identity');
+    if (!isObj(identity) || readOwnDataValue(identity, 'ok') !== true)
+        return undefined;
+    const a = assignmentOf(readOwnDataValue(raw, 'kind'), readOwnDataValue(identity, 'key'), slotReadOf(identity, 'connect'));
+    if (a === undefined || readOwnDataValue(identity, 'identityKind') !== a.identity.identityKind)
+        return undefined;
+    return a;
+}
+function legacyKeyOf(a) {
+    const id = a.identity;
+    if (id.identityKind === 'self')
+        return 'local';
+    if (id.identityKind === 'address')
+        return engineNamespaceKeyFor(id.connect.url);
+    const center = tupleOriginUrlOf(id.presentation.center);
+    return center === undefined ? undefined : engineNamespaceKeyFor(center.origin + id.connect.viaCenter);
+}
+const nextOf = (step) => (Object.hasOwn(step, 'next') ? step.next : undefined);
+function firstWrite(prior, session, a, now) {
+    const engines = { ...(prior?.engines ?? {}) };
+    const existing = Object.hasOwn(engines, a.identity.key) ? engines[a.identity.key] : undefined;
+    Object.defineProperty(engines, a.identity.key, {
+        value: { ...existing, engineSessionId: session.uuid, updatedAt: now },
+        writable: true,
+        enumerable: true,
+        configurable: true,
+    });
+    return { ...prior, shellSessionId: session.shellSessionId, boundEngine: snapshotOf(a), engines, updatedAt: now };
+}
+function commitStep(prior, session, arm, a, chosenByUser) {
+    const reading = readSessionEngine(prior);
+    if (prior !== undefined && prior !== null) {
+        const handle = isObj(prior) ? readOwnDataValue(prior, 'shellSessionId') : undefined;
+        if (handle !== session.shellSessionId) {
+            return { result: reading.kind === 'bound' ? Object.freeze({ kind: 'conflict', bound: reading.engine }) : unresolvedCommit('record-mismatch') };
+        }
+    }
+    if (reading.kind === 'unresolved')
+        return { result: unresolvedCommit('record-unreadable') };
+    if (reading.kind === 'bound') {
+        if (sameAssignment(reading.binding, a) && reading.uuid === session.uuid)
+            return { result: committed(a) };
+        return { result: Object.freeze({ kind: 'conflict', bound: reading.engine }) };
+    }
+    const now = new Date().toISOString();
+    if (reading.kind === 'none') {
+        if (arm !== 'create')
+            return { result: unresolvedCommit('record-unbound') };
+        return { result: committed(a), next: firstWrite(prior, session, a, now) };
+    }
+    if (arm !== 'recover')
+        return { result: unresolvedCommit('record-legacy') };
+    const oldKey = legacyKeyOf(a);
+    const proven = oldKey !== undefined &&
+        isObj(prior) &&
+        entryIdOf(prior, oldKey) === session.uuid &&
+        (a.identity.identityKind !== 'declared' || chosenByUser) &&
+        (entryIdOf(prior, a.identity.key) ?? session.uuid) === session.uuid;
+    if (!proven)
+        return { result: unresolvedCommit('recover-unproven') };
+    return { result: committed(a), next: firstWrite(prior, session, a, now) };
+}
+export function commitSessionEngine(store, session, request) {
+    let readMergeWrite;
+    let ref;
+    let arm;
+    let assignment;
+    let chosenByUser = false;
+    try {
+        if (!isObj(store) || !isObj(session) || !isObj(request))
+            return unresolvedCommit('request-invalid');
+        const rmw = methodOf(store, 'readMergeWrite');
+        if (rmw === undefined)
+            return unresolvedCommit('request-invalid');
+        readMergeWrite = (build) => rmw.call(store, build);
+        const shellSessionId = readOwnDataNonEmptyString(session, 'shellSessionId');
+        const uuid = readOwnDataNonEmptyString(session, 'uuid');
+        if (shellSessionId === undefined || uuid === undefined)
+            return unresolvedCommit('request-invalid');
+        ref = Object.freeze({ shellSessionId, uuid });
+        const armRaw = readOwnDataValue(request, 'arm');
+        if (armRaw !== 'create' && armRaw !== 'resume' && armRaw !== 'recover')
+            return unresolvedCommit('request-invalid');
+        arm = armRaw;
+        const a = requestAssignmentOf(readOwnDataValue(request, 'binding'));
+        if (a === undefined)
+            return unresolvedCommit('request-invalid');
+        assignment = a;
+        if (arm === 'recover')
+            chosenByUser = readOwnDataValue(request, 'chosenByUser') === true;
+    }
+    catch {
+        return unresolvedCommit('request-invalid');
+    }
+    let step;
+    try {
+        const returned = readMergeWrite((prior) => {
+            step = commitStep(prior, ref, arm, assignment, chosenByUser);
+            return nextOf(step);
+        });
+        if (step === undefined)
+            return STORE_FAILED;
+        if (nextOf(step) !== undefined && !isObj(returned))
+            return STORE_FAILED;
+        return step.result;
+    }
+    catch {
+        return STORE_FAILED;
+    }
+}
+function methodOf(o, key) {
+    try {
+        const v = o[key];
+        return typeof v === 'function' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const REFUSAL_KEYS = {
+    'not-wired': 'session.engine.dispatch.notWired',
+    'scope-mismatch': 'session.engine.dispatch.scopeMismatch',
+    'scope-unproven': 'session.engine.dispatch.scopeUnproven',
+    unresolved: 'session.engine.dispatch.unresolved',
+};
+const refused = (refusal) => Object.freeze({ kind: 'refused', refusal, message: msg(REFUSAL_KEYS[refusal]) });
+function authOf(ctx) {
+    const slot = slotReadOf(ctx, 'auth');
+    if (slot.presence === 'absent' || (slot.presence === 'present' && slot.value === undefined))
+        return { kind: 'none' };
+    if (slot.presence !== 'present' || !isObj(slot.value))
+        return { kind: 'unknown' };
+    const a = slot.value;
+    const kind = readOwnDataValue(a, 'kind');
+    if (kind === 'token')
+        return { kind: 'token' };
+    if (kind !== 'registry')
+        return { kind: 'unknown' };
+    const registryUrl = readOwnDataValue(a, 'registryUrl');
+    const u = typeof registryUrl === 'string' ? tupleOriginUrlOf(registryUrl) : undefined;
+    if (u === undefined || typeof registryUrl !== 'string')
+        return { kind: 'unknown' };
+    const scopeSlot = slotReadOf(a, 'scope');
+    if (scopeSlot.presence === 'unreadable')
+        return { kind: 'unknown' };
+    const scope = scopeSlot.presence === 'present' && typeof scopeSlot.value === 'string' && scopeSlot.value !== '' ? scopeSlot.value : undefined;
+    return { kind: 'registry', center: engineNamespaceKeyFor(registryUrl), origin: u.origin, scope };
+}
+function addressSetOf(ctx, key) {
+    const out = new Set();
+    const v = readOwnDataValue(ctx, key);
+    if (!Array.isArray(v))
+        return out;
+    const n = readOwnDataValue(v, 'length');
+    if (typeof n !== 'number' || !Number.isSafeInteger(n) || n < 0)
+        return out;
+    for (let i = 0; i < n; i += 1) {
+        const s = readOwnDataValue(v, String(i));
+        if (typeof s === 'string' && tupleOriginUrlOf(s) !== undefined)
+            out.add(engineNamespaceKeyFor(s));
+    }
+    return out;
+}
+export function sessionDispatchTarget(reading, ctx) {
+    try {
+        if (!isObj(reading) || readOwnDataValue(reading, 'kind') !== 'bound')
+            return refused('unresolved');
+        const a = requestAssignmentOf(readOwnDataValue(reading, 'binding'));
+        if (a === undefined)
+            return refused('unresolved');
+        if (!isObj(ctx))
+            return refused('not-wired');
+        const id = readOwnDataNonEmptyString(ctx, 'id');
+        if (id === undefined)
+            return refused('not-wired');
+        const identity = a.identity;
+        if (identity.identityKind === 'self') {
+            return readOwnDataValue(ctx, 'selfSpawned') === true ? Object.freeze({ kind: 'self', wiringSnapshotId: id }) : refused('not-wired');
+        }
+        const auth = authOf(ctx);
+        if (identity.identityKind === 'declared') {
+            if (auth.kind !== 'registry' || auth.center !== identity.presentation.center || auth.scope === undefined)
+                return refused('scope-unproven');
+            if (auth.scope !== identity.presentation.scope)
+                return refused('scope-mismatch');
+            return Object.freeze({ kind: 'center', url: auth.origin + identity.connect.viaCenter, wiringSnapshotId: id });
+        }
+        const url = identity.connect.url;
+        const u = tupleOriginUrlOf(url);
+        if (u === undefined)
+            return refused('unresolved');
+        const address = engineNamespaceKeyFor(url);
+        const viaOtherOrigin = auth.kind === 'registry' && auth.origin !== u.origin;
+        const explicitDirect = auth.kind === 'none' && addressSetOf(ctx, 'explicitAddresses').has(address) && u.pathname.replace(/\/+$/, '') === '';
+        if (!viaOtherOrigin && !explicitDirect)
+            return refused('scope-unproven');
+        if (!addressSetOf(ctx, 'wiredAddresses').has(address))
+            return refused('not-wired');
+        return Object.freeze({ kind: 'address', url, wiringSnapshotId: id });
+    }
+    catch {
+        return refused('unresolved');
+    }
+}

package/dist/sessionMap.d.ts

@@ -15,15 +15,25 @@ export interface SessionMapRecord {
         reason: string;
         at: string;
     };
+    boundEngine?: SessionEngineSnapshot;
     updatedAt: string;
 }
+export interface SessionEngineSnapshot {
+    kind: 'local' | 'cloud';
+    key: string;
+    connect?: {
+        url: string;
+    } | {
+        viaCenter: string;
+    };
+}
 export declare function engineNamespaceKeyFor(baseUrl: string | undefined): string;
 export type SessionMapMergeVerdict = {
     ok: true;
     record: SessionMapRecord;
 } | {
     ok: false;
-    reason: 'no-shell-session-id' | 'no-engine-session-id';
+    reason: 'no-shell-session-id' | 'no-engine-session-id' | 'bound-entry-conflict';
 };
 export declare function mergeSessionMapRecord(prior: SessionMapRecord | undefined, partial: Partial<SessionMapRecord> & {
     shellSessionId?: string;

package/dist/sessionMap.js

@@ -1,22 +1,41 @@
+import { tupleOriginUrlOf } from './engineAddress.js';
+import { readOwnDataValue } from './ownKey.js';
 export function engineNamespaceKeyFor(baseUrl) {
     if (!baseUrl)
         return 'local';
-    try {
-        const u = new URL(baseUrl);
-        if (!/^(?:https?|wss?|ftp):$/.test(u.protocol))
-            return baseUrl.toLowerCase();
-        return u.origin.toLowerCase() + u.pathname.replace(/\/+$/, '');
-    }
-    catch {
+    const u = tupleOriginUrlOf(baseUrl);
+    if (u === undefined)
         return baseUrl.toLowerCase();
-    }
+    return u.origin.toLowerCase() + u.pathname.replace(/\/+$/, '');
+}
+function boundEntryKept(prior, nextEngines) {
+    const key = prior?.boundEngine?.key;
+    if (typeof key !== 'string')
+        return true;
+    const before = prior?.engines !== undefined && Object.hasOwn(prior.engines, key) ? prior.engines[key] : undefined;
+    const has = nextEngines !== undefined && nextEngines !== null && Object.hasOwn(nextEngines, key);
+    const after = has ? readOwnDataValue(nextEngines, key) : undefined;
+    if (has && after === undefined)
+        return false;
+    if (before === undefined || after === undefined)
+        return before === after;
+    if (after === before)
+        return true;
+    return typeof after === 'object' && after !== null && readOwnDataValue(after, 'engineSessionId') === before.engineSessionId;
 }
 const isoNow = () => new Date().toISOString();
 export function mergeSessionMapRecord(prior, partial, now = isoNow) {
     const shellSessionId = partial.shellSessionId ?? prior?.shellSessionId;
     if (!shellSessionId)
         return { ok: false, reason: 'no-shell-session-id' };
-    return { ok: true, record: { ...prior, ...partial, shellSessionId, updatedAt: now() } };
+    const record = { ...prior, ...partial, shellSessionId, updatedAt: now() };
+    if (prior?.boundEngine !== undefined)
+        record.boundEngine = prior.boundEngine;
+    else
+        delete record.boundEngine;
+    if (!boundEntryKept(prior, record.engines))
+        return { ok: false, reason: 'bound-entry-conflict' };
+    return { ok: true, record };
 }
 export function mergeEngineEntry(prior, key, partial, shellSessionId, now = isoNow) {
     const priorEntry = prior?.engines?.[key];
@@ -26,6 +45,13 @@ export function mergeEngineEntry(prior, key, partial, shellSessionId, now = isoN
     const sid = shellSessionId ?? prior?.shellSessionId;
     if (!sid)
         return { ok: false, reason: 'no-shell-session-id' };
+    if (prior?.boundEngine !== undefined && key === prior.boundEngine.key) {
+        if (priorEntry === undefined ||
+            engineSessionId !== priorEntry.engineSessionId ||
+            (Object.hasOwn(partial, 'engineSessionId') && readOwnDataValue(partial, 'engineSessionId') !== priorEntry.engineSessionId)) {
+            return { ok: false, reason: 'bound-entry-conflict' };
+        }
+    }
     const entry = { ...priorEntry, ...partial, engineSessionId, updatedAt: now() };
     return {
         ok: true,

package/dist/sessionMemorySync.d.ts

@@ -0,0 +1,31 @@
+import { SDK_SESSION_MEMORY_UNOBSERVED_REASONS } from './generated/sdkFactTables.js';
+import { type UiLanguage } from './env/uiLanguage.js';
+type UnobservedReason = (typeof SDK_SESSION_MEMORY_UNOBSERVED_REASONS)[number];
+export type SessionMemorySyncReportReading = {
+    readonly scopes: readonly string[];
+} & ({
+    readonly layers: readonly object[];
+    readonly refused?: undefined;
+} | {
+    readonly refused: object;
+    readonly layers?: undefined;
+});
+export type SessionMemorySyncState = {
+    readonly kind: 'not_configured';
+    readonly report: SessionMemorySyncReportReading;
+} | {
+    readonly kind: 'reported';
+    readonly report: SessionMemorySyncReportReading;
+} | {
+    readonly kind: 'unobtainable';
+    readonly reason?: UnobservedReason;
+    readonly activeTaskId?: string;
+};
+export type SessionMemorySyncSettled = {
+    readonly report: {} | null | undefined;
+} | {
+    readonly error: {} | null | undefined;
+};
+export declare function sessionMemorySyncStateOf(settled: SessionMemorySyncSettled | null | undefined): SessionMemorySyncState | null;
+export declare function sessionMemorySyncNotice(state: SessionMemorySyncState | null | undefined, lang?: UiLanguage | (string & {})): string | undefined;
+export {};

package/dist/sessionMemorySync.js

@@ -0,0 +1,95 @@
+import { CONFLICT_SESSION_MEMORY_UNOBSERVED } from './engineErrorCodes.js';
+import { SDK_SESSION_MEMORY_UNOBSERVED_REASONS } from './generated/sdkFactTables.js';
+import { isUiLanguage } from './env/uiLanguage.js';
+import { msg, renderMessage } from './i18n/translate.js';
+import { slotReadOf, isSlotCarrier, readErrorString } from './wireFailureShape.js';
+import { effectiveWireErrorCode } from './wireErrorTriage.js';
+const reasonOf = (v) => SDK_SESSION_MEMORY_UNOBSERVED_REASONS.find((w) => w === v);
+function scopesOf(report) {
+    const r = slotReadOf(report, 'scopes');
+    if (r.presence !== 'present' || !Array.isArray(r.value))
+        return undefined;
+    const out = [];
+    const len = r.value.length;
+    if (typeof len !== 'number' || !Number.isSafeInteger(len) || len < 0)
+        return undefined;
+    for (let i = 0; i < len; i++) {
+        const item = r.value[i];
+        if (typeof item !== 'string')
+            return undefined;
+        out.push(item);
+    }
+    return out;
+}
+export function sessionMemorySyncStateOf(settled) {
+    try {
+        if (typeof settled !== 'object' || settled === null)
+            return null;
+        const reportSlot = slotReadOf(settled, 'report');
+        const errorSlot = slotReadOf(settled, 'error');
+        if (reportSlot.presence === 'present' && errorSlot.presence === 'absent') {
+            const report = reportSlot.value;
+            if (typeof report !== 'object' || report === null || Array.isArray(report))
+                return null;
+            const scopes = scopesOf(report);
+            if (scopes === undefined)
+                return null;
+            const refused = slotReadOf(report, 'refused');
+            const layers = slotReadOf(report, 'layers');
+            if (refused.presence === 'unreadable' || layers.presence === 'unreadable')
+                return null;
+            const refusedArm = refused.presence === 'present';
+            if (refusedArm === (layers.presence === 'present'))
+                return null;
+            if (refusedArm ? typeof refused.value !== 'object' || refused.value === null || Array.isArray(refused.value) : !Array.isArray(layers.value))
+                return null;
+            const kind = scopes.length === 0 && !refusedArm ? 'not_configured' : 'reported';
+            return Object.freeze({ kind, report: report });
+        }
+        if (errorSlot.presence === 'present' && reportSlot.presence === 'absent') {
+            const err = errorSlot.value;
+            if (!isSlotCarrier(err))
+                return null;
+            if (effectiveWireErrorCode(err) !== CONFLICT_SESSION_MEMORY_UNOBSERVED)
+                return null;
+            const o = err;
+            const reason = reasonOf(readErrorString(o, 'reason'));
+            const active = readErrorString(o, 'activeTaskId');
+            return Object.freeze({
+                kind: 'unobtainable',
+                ...(reason !== undefined ? { reason } : {}),
+                ...(typeof active === 'string' && active !== '' ? { activeTaskId: active } : {}),
+            });
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+const UNOBTAINABLE_KEYS = Object.freeze({
+    no_settled_run: 'session.memorySyncTrigger.noSettledRun',
+    run_result_missing: 'session.memorySyncTrigger.runUnobserved',
+    run_result_unobserved: 'session.memorySyncTrigger.runUnobserved',
+    memory_not_mounted: 'session.memorySyncTrigger.memoryNotMounted',
+    no_leaf: 'session.memorySyncTrigger.noLeaf',
+});
+export function sessionMemorySyncNotice(state, lang) {
+    try {
+        if (typeof state !== 'object' || state === null)
+            return undefined;
+        const kind = slotReadOf(state, 'kind');
+        if (kind.presence !== 'present')
+            return undefined;
+        if (kind.value === 'not_configured')
+            return renderMessage(msg('session.memorySyncTrigger.notConfigured'), isUiLanguage(lang) ? lang : undefined);
+        if (kind.value !== 'unobtainable')
+            return undefined;
+        const reason = slotReadOf(state, 'reason');
+        const word = reason.presence === 'present' && typeof reason.value === 'string' ? reasonOf(reason.value) : undefined;
+        return renderMessage(msg(word !== undefined ? UNOBTAINABLE_KEYS[word] : 'session.memorySyncTrigger.unobtainable'), isUiLanguage(lang) ? lang : undefined);
+    }
+    catch {
+        return undefined;
+    }
+}