@try-works/dsh-tool-mode 0.0.0-stage → 0.5.45

package/lib/jev.js

@@ -0,0 +1,366 @@
+/**
+ * Remote Jev (TypeSafe System One) adapter (TOOL-02, DEC-07).
+ *
+ * Jev is a remote typed-question service, not a local checkpoint and not a chat
+ * endpoint. This module speaks its native `systemOne` request/response shape and
+ * converts a choice answer onto the standard `decision.choose` result. The
+ * conversion is VERSIONED and tested; an invalid probability set or an unknown
+ * choice is an error, never an abstention.
+ *
+ * @module @try-works/dsh-tool-mode/jev
+ */
+/** The version of the native-to-standard conversion this build implements. */
+export const JEV_CONVERSION_VERSION = '1.0.0';
+/** A configuration or transport failure; never carries the API key or response body. */
+export class JevError extends Error {
+    /** Stable failure class. */
+    code;
+    /** HTTP status, when the failure came from a response. */
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.name = 'JevError';
+        this.code = code;
+        if (status !== undefined)
+            this.status = status;
+    }
+}
+/** The default TypeSafe API root (the `/v1/systemone` path is appended). */
+export const JEV_DEFAULT_BASE_URL = 'https://api.typesafe.ai';
+/** The default pinned model; callers may pin another documented model. */
+export const JEV_DEFAULT_MODEL = 'jev-1.14';
+/** Convert a probability mass to the standard bucket. */
+export function confidenceBucket(mass) {
+    if (!Number.isFinite(mass))
+        throw new JevError('invalid_response', 'the answer carries no finite confidence');
+    const clamped = Math.max(0, Math.min(1, mass));
+    return clamped >= 0.6 ? 'confident' : clamped >= 0.35 ? 'likely' : 'tentative';
+}
+/**
+ * Build the native request for a choice.
+ * @param decision - the decision text.
+ * @param options - 2–16 distinct nonempty labels.
+ * @param model - the pinned model id.
+ * @returns the native request body.
+ */
+export function buildJevChoiceRequest(decision, options, model = JEV_DEFAULT_MODEL) {
+    if (decision.trim().length === 0)
+        throw new JevError('invalid_request', 'the decision must not be empty');
+    if (options.length < 2 || options.length > 16)
+        throw new JevError('invalid_request', 'a choice needs 2–16 options');
+    const seen = new Set();
+    const criteria = {};
+    for (let index = 0; index < options.length; index += 1) {
+        const label = options[index];
+        if (label.trim().length === 0)
+            throw new JevError('invalid_request', 'an option label must not be empty');
+        if (seen.has(label))
+            throw new JevError('invalid_request', 'option labels must be distinct');
+        seen.add(label);
+        criteria[`option_${index}`] = label;
+    }
+    return {
+        model,
+        state: { decision },
+        questions: {
+            choice: {
+                type: 'choice',
+                instructions: decision,
+                criteria,
+            },
+        },
+    };
+}
+/**
+ * Convert a native response payload to the standard result.
+ * @param payload - the parsed JSON response.
+ * @param options - the caller's option labels, in order.
+ * @returns the standard result.
+ */
+export function convertJevChoiceResponse(payload, options) {
+    if (typeof payload !== 'object' || payload === null)
+        throw new JevError('invalid_response', 'the response is not an object');
+    const answers = payload.answers;
+    if (typeof answers !== 'object' || answers === null)
+        throw new JevError('invalid_response', 'the response has no answers object');
+    const answer = answers.choice;
+    if (typeof answer !== 'object' || answer === null)
+        throw new JevError('invalid_response', 'the response has no choice answer');
+    if (answer.type !== 'choice')
+        throw new JevError('invalid_response', 'the choice answer has the wrong type');
+    if (typeof answer.choice !== 'string')
+        throw new JevError('invalid_response', 'the choice answer has no chosen id');
+    const match = /^option_(\d+)$/.exec(answer.choice);
+    if (match === null)
+        throw new JevError('invalid_response', 'the chosen id is not a supplied option id');
+    const chosen = Number(match[1]);
+    if (!Number.isInteger(chosen) || chosen < 0 || chosen >= options.length) {
+        throw new JevError('invalid_response', 'the chosen option is outside the supplied option set');
+    }
+    const probabilities = answer.probabilities;
+    if (typeof probabilities !== 'object' || probabilities === null || Array.isArray(probabilities)) {
+        throw new JevError('invalid_response', 'the answer carries no probability map');
+    }
+    const map = probabilities;
+    const expected = new Set(options.map((_, index) => `option_${index}`));
+    const actual = Object.keys(map);
+    if (actual.length !== expected.size || actual.some(key => !expected.has(key))) {
+        throw new JevError('invalid_response', 'the probability map does not match the supplied options');
+    }
+    let sum = 0;
+    for (const key of actual) {
+        const value = map[key];
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+            throw new JevError('invalid_response', 'the probability map contains an invalid value');
+        }
+        sum += value;
+    }
+    if (Math.abs(sum - 1) > 1e-6)
+        throw new JevError('invalid_response', 'the probability mass is not normalized');
+    const mass = chosen === undefined ? Number.NaN : Number(map[`option_${chosen}`]);
+    const reported = answer.confidence ?? answer.answer_confidence;
+    if (typeof reported !== 'number' || !Number.isFinite(reported) || reported < 0 || reported > 1) {
+        throw new JevError('invalid_response', 'the answer carries no finite confidence in [0,1]');
+    }
+    // The reported confidence is the provider's own value; the probability mass is
+    // retained in the map and named in the reason. Both are UNCALIBRATED (DEC-08).
+    const label = options[chosen];
+    return {
+        chosen,
+        confidence: confidenceBucket(reported),
+        reason: `Chose ${JSON.stringify(label)} (Jev uncalibrated probability ${mass.toFixed(4)}, conversion ${JEV_CONVERSION_VERSION}).`,
+    };
+}
+/**
+ * Ask Jev one choice question through its native API.
+ * @param decision - the decision text.
+ * @param options - the caller's labels.
+ * @param config - API key, base URL, model and optional transport.
+ * @param signal - cancellation.
+ * @returns the standard result.
+ */
+export async function chooseWithJev(decision, options, config, signal) {
+    if (typeof config.apiKey !== 'string' || config.apiKey.trim().length === 0) {
+        throw new JevError('api_key_missing', 'no Jev API key is configured');
+    }
+    const request = buildJevChoiceRequest(decision, options, config.model ?? JEV_DEFAULT_MODEL);
+    const transport = config.fetch ?? fetch;
+    const base = (config.baseURL ?? JEV_DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 30_000);
+    const forwardAbort = () => controller.abort();
+    signal?.addEventListener('abort', forwardAbort, { once: true });
+    let response;
+    try {
+        response = await transport(`${base}/v1/systemone`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new JevError('aborted', 'the Jev call was aborted');
+        throw new JevError('connection', 'the Jev request failed before a response arrived');
+    }
+    finally {
+        clearTimeout(timeout);
+        signal?.removeEventListener('abort', forwardAbort);
+    }
+    if (!response.ok)
+        throw new JevError('http', `the Jev service returned HTTP ${response.status}`, response.status);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new JevError('invalid_response', 'the Jev response is not JSON');
+    }
+    return convertJevChoiceResponse(payload, options);
+}
+/** Build the native multi-question request. */
+export function buildJevJudgmentsRequest(state, questions, model = JEV_DEFAULT_MODEL) {
+    if (!Array.isArray(questions) || questions.length === 0 || questions.length > 16) {
+        throw new JevError('invalid_request', 'a judgment batch needs 1–16 questions');
+    }
+    const seen = new Set();
+    const native = {};
+    for (const question of questions) {
+        if (typeof question.id !== 'string' || question.id.length === 0 || question.id.length > 64) {
+            throw new JevError('invalid_request', 'every question needs a 1–64 character id');
+        }
+        if (seen.has(question.id))
+            throw new JevError('invalid_request', `question id ${JSON.stringify(question.id)} is duplicated`);
+        seen.add(question.id);
+        if (question.type === 'boolean') {
+            if (typeof question.proposition !== 'string' || question.proposition.trim().length === 0) {
+                throw new JevError('invalid_request', `question ${question.id} needs a non-empty proposition`);
+            }
+            native[question.id] = { type: 'noul', instructions: question.proposition };
+            continue;
+        }
+        if (question.type !== 'choice')
+            throw new JevError('invalid_request', `question ${question.id} has an unknown type`);
+        if (typeof question.instructions !== 'string' || question.instructions.trim().length === 0) {
+            throw new JevError('invalid_request', `question ${question.id} needs non-empty instructions`);
+        }
+        const entries = Object.entries(question.criteria ?? {});
+        if (entries.length < 2 || entries.length > 32)
+            throw new JevError('invalid_request', `question ${question.id} needs 2–32 criteria`);
+        for (const [key, description] of entries) {
+            if (key.length === 0 || typeof description !== 'string' || description.length === 0) {
+                throw new JevError('invalid_request', `question ${question.id} has an invalid criterion`);
+            }
+        }
+        native[question.id] = { type: 'choice', instructions: question.instructions, criteria: question.criteria };
+    }
+    return { model, state, questions: native };
+}
+/** Convert the native batch response; missing or invalid answers are errors. */
+export function convertJevJudgmentsResponse(payload, questions) {
+    if (typeof payload !== 'object' || payload === null)
+        throw new JevError('invalid_response', 'the response is not an object');
+    const root = payload;
+    if (typeof root.answers !== 'object' || root.answers === null)
+        throw new JevError('invalid_response', 'the response has no answers object');
+    const answers = root.answers;
+    const judgments = {};
+    for (const question of questions) {
+        const raw = answers[question.id];
+        if (typeof raw !== 'object' || raw === null)
+            throw new JevError('invalid_response', `the response is missing question ${question.id}`);
+        const answer = raw;
+        if (question.type === 'boolean') {
+            if (answer.type !== 'noul')
+                throw new JevError('invalid_response', `question ${question.id} is not a noul answer`);
+            const probability = answer.noul;
+            if (typeof probability !== 'number' || !Number.isFinite(probability) || probability < 0 || probability > 1) {
+                throw new JevError('invalid_response', `question ${question.id} has no probability in [0,1]`);
+            }
+            judgments[question.id] = { type: 'boolean', probability };
+            continue;
+        }
+        if (answer.type !== 'choice')
+            throw new JevError('invalid_response', `question ${question.id} is not a choice answer`);
+        const chosen = answer.choice;
+        if (chosen !== null && typeof chosen !== 'string')
+            throw new JevError('invalid_response', `question ${question.id} has an invalid chosen value`);
+        if (typeof chosen === 'string' && !Object.hasOwn(question.criteria, chosen)) {
+            throw new JevError('invalid_response', `question ${question.id} chose ${JSON.stringify(chosen)}, not a supplied criterion`);
+        }
+        const probabilities = answer.probabilities;
+        if (typeof probabilities !== 'object' || probabilities === null || Array.isArray(probabilities)) {
+            throw new JevError('invalid_response', `question ${question.id} has no probability map`);
+        }
+        const map = probabilities;
+        const expected = Object.keys(question.criteria);
+        if (Object.keys(map).length !== expected.length || expected.some(key => !Object.hasOwn(map, key))) {
+            throw new JevError('invalid_response', `question ${question.id} probability keys do not match its criteria`);
+        }
+        let sum = 0;
+        for (const key of expected) {
+            const value = map[key];
+            if (typeof value !== 'number' || !Number.isFinite(value) || value < 0 || value > 1) {
+                throw new JevError('invalid_response', `question ${question.id} has an invalid probability`);
+            }
+            sum += value;
+        }
+        if (Math.abs(sum - 1) > 1e-6)
+            throw new JevError('invalid_response', `question ${question.id} probabilities are not normalized`);
+        const confidence = answer.confidence;
+        if (typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) {
+            throw new JevError('invalid_response', `question ${question.id} has no finite confidence`);
+        }
+        judgments[question.id] = { type: 'choice', chosen, probabilities: map, confidence };
+    }
+    return { model: typeof root.model === 'string' ? root.model : 'unknown', judgments };
+}
+/**
+ * Ask independent atomic judgments in ONE native request.
+ * @param state - the same state for every question.
+ * @param questions - 1–16 independent questions.
+ * @param config - API key, base URL, model and optional transport.
+ * @param signal - cancellation.
+ * @returns native judgments keyed by question id.
+ */
+export async function judgeWithJev(state, questions, config, signal) {
+    if (typeof config.apiKey !== 'string' || config.apiKey.trim().length === 0) {
+        throw new JevError('api_key_missing', 'no Jev API key is configured');
+    }
+    const request = buildJevJudgmentsRequest(state, questions, config.model ?? JEV_DEFAULT_MODEL);
+    const transport = config.fetch ?? fetch;
+    const base = (config.baseURL ?? JEV_DEFAULT_BASE_URL).replace(/\/+$/, '');
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 30_000);
+    const forwardAbort = () => controller.abort();
+    signal?.addEventListener('abort', forwardAbort, { once: true });
+    let response;
+    try {
+        response = await transport(`${base}/v1/systemone`, {
+            method: 'POST',
+            headers: { Authorization: `Bearer ${config.apiKey}`, 'Content-Type': 'application/json' },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        if (controller.signal.aborted)
+            throw new JevError('aborted', 'the Jev call was aborted');
+        throw new JevError('connection', 'the Jev request failed before a response arrived');
+    }
+    finally {
+        clearTimeout(timeout);
+        signal?.removeEventListener('abort', forwardAbort);
+    }
+    if (!response.ok)
+        throw new JevError('http', `the Jev service returned HTTP ${response.status}`, response.status);
+    let payload;
+    try {
+        payload = await response.json();
+    }
+    catch {
+        throw new JevError('invalid_response', 'the Jev response is not JSON');
+    }
+    return convertJevJudgmentsResponse(payload, questions);
+}
+/** The MCP contract for the atomic judgment batch. */
+export const JEV_JUDGMENTS_CONTRACT = {
+    contract: 'decision.judgments.jev',
+    version: '1.0.0',
+    toolName: 'decision_judgments_jev',
+    description: 'Ask independent atomic boolean/choice questions through Jev in one native request.',
+    inputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['state', 'questions'],
+        properties: {
+            state: { type: 'object', additionalProperties: true },
+            questions: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        },
+    },
+    outputSchema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['model', 'judgments'],
+        properties: {
+            model: { type: 'string' },
+            judgments: { type: 'object', additionalProperties: true },
+        },
+    },
+    semantics: { deterministic: false, readsInputs: true },
+    limits: {},
+    unsupported: ['no local Jev weights', 'no chat schema'],
+};
+/** The MCP contract for the single-choice Jev tool. */
+export const JEV_CHOOSE_CONTRACT = {
+    contract: 'decision.choose.jev', version: '1.0.0', toolName: 'decision_choose_jev',
+    description: 'Choose 2–16 options through the remote Jev typed-question API on the standard decision result.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['decision', 'options'], properties: { decision: { type: 'string' }, options: { type: 'array', items: { type: 'string' } } } },
+    outputSchema: { type: 'object', additionalProperties: false, required: ['chosen', 'confidence', 'reason'], properties: { chosen: { type: 'integer' }, confidence: { type: 'string', enum: ['confident', 'likely', 'tentative'] }, reason: { type: 'string' } } },
+    semantics: { deterministic: false, readsInputs: true }, limits: {},
+};
+//# sourceMappingURL=jev.js.map

package/lib/legacy-migration.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The startup hook that migrates a legacy model-id era `state.json` into the
+ * versioned world (BASE-09, BASE-10), ONCE per profile — as a REAL
+ * transaction with crash recovery, not a read-then-overwrite.
+ *
+ * Before this module the migration table existed only as an SDK library with
+ * tests: nothing in the host's production startup ever ran it, so a real
+ * upgrade kept reading the old-world document forever. This module is the
+ * production caller. Its guarantees:
+ *
+ * - ONCE-ANCHOR + COMMIT: a non-secret sidecar marker
+ *   (`<stateFile>.migrated.json`) is the commit record, written ATOMICALLY
+ *   (temp + fsync + rename) as the LAST step of the transaction. The host's
+ *   own state document keeps its exact shape — the store's writes are
+ *   untouched and no parallel format is written. A marker is VALIDATED on
+ *   every read (parse + exact version + list shape): a corrupt or
+ *   foreign-version marker FAILS CLOSED instead of silently counting the
+ *   profile as migrated;
+ * - IMMUTABLE JOURNAL: before ANY mutation, the original legacy document is
+ *   journaled to `<stateFile>.legacy-backup.json` with EXCLUSIVE creation
+ *   (`wx`). The journal is the legacy INPUT for every recovery. Its
+ *   first-write-wins behavior is guaranteed BY THE TRANSACTION LOCK (the
+ *   exists-check before the rename is advisory, not a lock);
+ * - RECOVERY: a crash between the host write and the marker leaves a journal
+ *   WITHOUT a committed marker. The next boot detects that state and re-runs
+ *   the transaction FROM THE VALIDATED JOURNAL — never from the already-
+ *   rewritten state file, which has lost the staged enables, provider picks
+ *   and prepared-asset facts. The host write MERGES with the current
+ *   document (current enables are operator-era facts and are preserved;
+ *   legacy disables are added), so an operator change after the crash is
+ *   never discarded. A corrupt journal with no marker FAILS CLOSED;
+ * - TRANSACTION LOCK: the whole transaction runs under an exclusive lock
+ *   file with an ownership token and pid. A stale lock is NEVER taken over
+ *   automatically — the read-then-remove sequence is not atomic and two
+ *   concurrent reapers could delete a successor's fresh lock — so a held lock
+ *   FAILS CLOSED at the deadline and the operator removes it deliberately;
+ *   release removes only a token-owned lock (the same discipline as the
+ *   credential store);
+ * - the SDK profile half runs THROUGH the SDK's own
+ *   `migrateLegacyProfileState` (its lock, idempotence, version gate) BEFORE
+ *   the host document is written;
+ * - DISABLED legacy choices are preserved — ALL of them, mapped or not: an
+ *   unmapped disabled id that vanished from the host state would let a later
+ *   package restore silently enable what the operator turned off. Unresolved
+ *   ids are REPORTED separately, never enabled;
+ * - legacy ENABLES are STAGED, never granted (BASE-10: a legacy enable is
+ *   not consent to install, activate or prepare third-party code);
+ * - every persisted artifact (marker, journal, lock) is NON-SECRET by
+ *   construction: model ids, provider identifiers and counts, never a secret.
+ *
+ * @module @try-works/dsh-tool-mode/legacy-migration
+ */
+import { type PersistedState, type StateStore } from './state.ts';
+/** The marker version this host writes; equality, never a lower bound. */
+export declare const MIGRATION_MARKER_VERSION: 1;
+/** What the startup hook did. */
+export interface LegacyStartupOutcome {
+    /** False when there was nothing to migrate (marker present, or fresh profile). */
+    readonly ran: boolean;
+    /** The host choices to adopt after the run (the caller replaces its persisted copy). */
+    readonly hostState: PersistedState;
+    /** Legacy model ids that were ENABLED and are therefore STAGED, never granted. */
+    readonly staged: readonly string[];
+    /** Legacy ids the table could not map; reported, never enabled. */
+    readonly unresolved: readonly string[];
+    /** A non-secret one-line summary for the startup log, when anything happened. */
+    readonly logLine: string | undefined;
+    /** True when this run RECOVERED an interrupted transaction from the journal. */
+    readonly recovered: boolean;
+}
+/** The marker path for one state file. */
+export declare function migrationMarkerPath(stateFile: string): string;
+/** The backup path for one state file. */
+export declare function legacyBackupPath(stateFile: string): string;
+/** The transaction lock path for one state file. */
+export declare function migrationLockPath(stateFile: string): string;
+/**
+ * Run the one-time legacy startup migration (with crash recovery).
+ *
+ * @param options.stateFile - the host's configured isolated state path.
+ * @param options.store - the host's state store over that path.
+ * @param options.extensionStoreDir - when the deployment mounts an extension
+ *   store, the SDK profile migration runs there too.
+ * @param options.log - a non-secret log sink (the host's logger).
+ * @returns the outcome; the caller ALWAYS adopts `hostState` (the hook returns
+ * a fresh post-lock read on every path, so adopting it never re-applies a
+ * pre-hook snapshot).
+ */
+export declare function runLegacyStartupMigration(options: {
+    readonly stateFile: string;
+    readonly store: StateStore;
+    readonly extensionStoreDir?: string;
+    readonly log?: (line: string) => void;
+}): Promise<LegacyStartupOutcome>;
+//# sourceMappingURL=legacy-migration.d.ts.map

package/lib/legacy-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-migration.d.ts","sourceRoot":"","sources":["../src/legacy-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AAqBH,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAA;AAGjE,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,EAAG,CAAU,CAAA;AAElD,iCAAiC;AACjC,MAAM,WAAW,oBAAoB;IACnC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,wFAAwF;IACxF,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAA;IAClC,kFAAkF;IAClF,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;IAClC,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IACtC,iFAAiF;IACjF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IACpC,gFAAgF;IAChF,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAC5B;AA2BD,0CAA0C;AAC1C,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,oDAAoD;AACpD,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE3D;AA+ND;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE;IACvD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CACtC,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAWhC"}