@vincemakes/kiso-runtime 0.15.11 → 0.16.0

package/dist/agent.d.ts

@@ -80,6 +80,7 @@ export declare class AgentRuntime {
     /** Load an existing session from disk, or create a fresh one. */
     session(options: {
         id: string;
+        acceptDrift?: boolean;
     }): Promise<AgentSession>;
 }
 /** The one-liner the README promises. */

package/dist/agent.js

@@ -11,6 +11,8 @@
  * package (optional peers — an unused provider costs nothing). The kernel
  * itself stays dependency-free; the SDKs live in the provider packages.
  */
+import { resolveContinuationScope } from "./provider/manifest.js";
+import { assessProfileDrift, buildProfile, profilePath, readProfile, writeProfile } from "./profile.js";
 import { EventLog, ToolRegistry } from "@vincemakes/kiso-core";
 import { AgentSession } from "./session.js";
 /** @deprecated the canonical name is `Agent` (root export, 1.1.0); this alias is removed in the next major. */
@@ -53,9 +55,73 @@ export class AgentRuntime {
         const records = store.load(options.id);
         const log = new EventLog(records.map((r) => r.event));
         const adapter = await this.#adapterPromise;
+        const startupScope = resolveContinuationScope(this.#definition.provider, this.#definition.model, this.#definition.baseUrl);
+        // ── XP-1: the durable execution profile, FAIL-CLOSED ─────────────
+        const meta = readProfile(store.root, options.id);
+        if (meta.kind === "corrupt") {
+            throw new Error(`the session profile ${profilePath(store.root, options.id)} is unreadable (${meta.error}) — BLOCKED: restore the file, or re-create the session; a corrupt profile is never silently rebuilt under today's defaults`);
+        }
+        const hasEnvelope = log.all.some((e) => e.type === "stop" && e.continuation !== undefined);
+        if (meta.kind === "absent" && hasEnvelope) {
+            throw new Error(`the session log carries scoped continuation envelopes but ${profilePath(store.root, options.id)} is missing — BLOCKED: an XP-era session without its profile is an integrity failure, never a legacy session`);
+        }
+        // The CURRENT candidate — what THIS process would run.
+        const candidate = buildProfile({
+            revision: 0,
+            modelId: this.#definition.model,
+            provider: startupScope ?? null,
+            ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
+            registry: this.#registry,
+        });
+        let restored = null;
+        let profilePending = false;
+        if (meta.kind === "ok") {
+            const drift = assessProfileDrift(meta.profile, {
+                provider: startupScope ?? null,
+                systemPromptDigest: candidate.systemPromptDigest,
+                tools: candidate.tools,
+            });
+            if (drift.kind === "material" && options.acceptDrift !== true) {
+                const listed = drift.reasons.map((r) => `- ${r}`).join("\n");
+                throw new Error(`the recorded execution profile no longer matches this process:\n${listed}\nre-open with acceptDrift (the CLI's --accept-drift flag) to proceed under the CURRENT configuration — the acknowledgement is recorded as a new revision; silently rebuilding is forbidden`);
+            }
+            if (drift.kind === "material") {
+                // acknowledged: the current configuration wins, DURABLY.
+                writeProfile(store.root, options.id, {
+                    ...buildProfile({
+                        revision: meta.profile.revision + 1,
+                        modelId: this.#definition.model,
+                        provider: startupScope ?? null,
+                        ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
+                        registry: this.#registry,
+                    }),
+                });
+            }
+            else {
+                // RESTORE — the recorded profile wins over the process default
+                // (the truthfulness core: the row and the request agree).
+                const scope = meta.profile.provider === null ? undefined : meta.profile.provider;
+                restored = { model: meta.profile.modelId, reasoning: meta.profile.reasoning, scope };
+            }
+        }
+        else if (log.all.length === 0) {
+            // a NEW session: revision 1 lands BEFORE any durable event.
+            writeProfile(store.root, options.id, { ...candidate, revision: 1 });
+        }
+        else {
+            // legacy (pre-XP log, no sidecar): generation absence is not
+            // drift — restore under current configuration; revision 1 lands
+            // at the next explicit selection or first request.
+            profilePending = true;
+        }
         const config = {
-            model: this.#definition.model,
+            model: restored?.model ?? this.#definition.model,
             ...(this.#definition.provider !== undefined ? { provider: this.#definition.provider } : {}),
+            ...((restored !== null ? restored.scope : startupScope) !== undefined
+                ? { continuationScope: (restored !== null ? restored.scope : startupScope) }
+                : {}),
+            ...(restored !== null ? { reasoning: restored.reasoning } : {}),
+            ...(profilePending ? { profilePending: true } : {}),
             ...(this.#definition.systemPrompt !== undefined ? { systemPrompt: this.#definition.systemPrompt } : {}),
             registry: this.#registry,
             ...(this.#definition.permissionPolicy !== undefined || this.#definition.hooks !== undefined
@@ -137,9 +203,15 @@ async function resolveAdapter(definition) {
         }
         case "openai-compat": {
             const { createOpenAICompatProvider } = await import("@vincemakes/kiso-provider-openai");
+            // MG-1 (A5): the adapter's replay identity — the SAME resolution
+            // the run's stamping scope uses, so emit and replay agree.
+            const scope = resolveContinuationScope("openai-compat", "", definition.baseUrl);
             return createOpenAICompatProvider({
                 ...(definition.apiKey !== undefined ? { apiKey: definition.apiKey } : {}),
                 ...(definition.baseUrl !== undefined ? { baseUrl: definition.baseUrl } : {}),
+                ...(scope !== undefined
+                    ? { scope: { providerId: scope.providerId, ...(scope.endpoint !== undefined ? { endpoint: scope.endpoint } : {}) } }
+                    : {}),
             });
         }
         default:

package/dist/internal.d.ts

@@ -25,3 +25,4 @@ export * from "./extensions.js";
 export * from "./trust.js";
 export * from "./provider/metadata.js";
 export { canonicalizeUsageForModel } from "./usage/canonical.js";
+export { BUILTIN_MANIFESTS, resolveContinuationScope, type ModelRef, type ProviderManifest } from "./provider/manifest.js";

package/dist/internal.js

@@ -30,3 +30,5 @@ export * from "./provider/metadata.js";
 // PH-1c: the model-keyed cost derivation rides the same door (the root
 // surface keeps only the frozen canonicalizeUsage).
 export { canonicalizeUsageForModel } from "./usage/canonical.js";
+// MG-1 (A5): the identity layer — manifests and the scope resolver.
+export { BUILTIN_MANIFESTS, resolveContinuationScope } from "./provider/manifest.js";

package/dist/profile.d.ts

@@ -0,0 +1,114 @@
+/**
+ * XP-1 — the durable execution profile (the ratified spec §3).
+ *
+ * ONE product contract: a session must know what will answer its next
+ * request after a restart. The profile is a durable session fact OUTSIDE
+ * the event log — ADR-0051 §6's OUT class ("session metadata that is not
+ * an event"), so no contract amendment is spent on persistence; the §6
+ * purity gate extends instead: the correctness derivation never reads it.
+ *
+ * The sidecar is `<id>.meta.json` (the adjudicated namespaced file — the
+ * profile is its first tenant, SX-1's naming joins later), written
+ * FAIL-CLOSED: temp → fsync(file) → rename → fsync(parent directory),
+ * full replacement per revision. A new session writes revision 1 BEFORE
+ * its first durable event; an unreadable sidecar is BLOCKED, never
+ * silently treated as absent (the "corrupt = legacy = today's defaults"
+ * misclassification is the exact silent rebuild the spec forbids).
+ *
+ * Never a secret: the profile carries the profile NAME and env-var-shaped
+ * references at most — no key, token, or credential material.
+ */
+import type { ToolRegistry } from "@vincemakes/kiso-core";
+import type { ReasoningSetting } from "./provider/metadata.js";
+export interface ProfileModelRef {
+    readonly providerId: string;
+    readonly apiId: string;
+    readonly modelId: string;
+    readonly endpoint?: string;
+}
+/** One tool of the recorded surface — the INVENTORY itself, not only a
+ *  digest: a single hash can say "changed" but never WHAT changed, and
+ *  the drift protocol must tell compatible additions from removals and
+ *  schema changes. */
+export interface ProfileToolRecord {
+    readonly name: string;
+    readonly schemaHash: string;
+    readonly descriptionHash: string;
+}
+export interface ExecutionProfile {
+    /** monotone per session, from 1. */
+    readonly revision: number;
+    /** ISO time of this revision. */
+    readonly at: string;
+    /** the RESOLVED model id — recorded even for unscoped bindings: the
+     *  session must know what answers its next request either way. */
+    readonly modelId: string;
+    /** null = an unscoped binding (SDK-injected adapter). */
+    readonly provider: ProfileModelRef | null;
+    /** the config profile NAME — the credential reference is at most the
+     *  env-var name the config carries; never the secret. */
+    readonly profileName: string | null;
+    readonly reasoning: ReasoningSetting;
+    readonly systemPromptDigest: string;
+    /** sorted by name; the digest below is DERIVED from this inventory. */
+    readonly tools: readonly ProfileToolRecord[];
+    readonly toolManifestDigest: string;
+}
+export declare function toolInventory(registry: ToolRegistry): readonly ProfileToolRecord[];
+export declare function buildProfile(input: {
+    readonly revision: number;
+    readonly modelId: string;
+    readonly provider: ProfileModelRef | null;
+    readonly profileName?: string;
+    readonly reasoning?: ReasoningSetting;
+    readonly systemPrompt?: string;
+    readonly registry: ToolRegistry;
+}): ExecutionProfile;
+export declare function profilePath(root: string, sessionId: string): string;
+/** Atomic, fail-closed write: a reader sees the previous revision or the
+ *  new one, never a torn file — and the RENAME itself is made durable by
+ *  the parent-directory fsync. */
+export declare function writeProfile(root: string, sessionId: string, profile: ExecutionProfile): void;
+export type ProfileReadResult = {
+    readonly kind: "ok";
+    readonly profile: ExecutionProfile;
+} | {
+    readonly kind: "absent";
+} | {
+    readonly kind: "corrupt";
+    readonly error: string;
+};
+export declare function readProfile(root: string, sessionId: string): ProfileReadResult;
+export type ProfileDrift = {
+    readonly kind: "clean";
+}
+/** the tool surface or the composed prompt moved — NAMED and surfaced
+ *  (never presented as restored), but composition is per-process BY
+ *  ARCHITECTURE here (extensions, modes, the E5-ratified task flip,
+ *  subagent roles), so it never refuses an open. */
+ | {
+    readonly kind: "surface-changed";
+    readonly notes: readonly string[];
+}
+/** new tools only — every recorded tool present and identical. */
+ | {
+    readonly kind: "compatible-additions";
+    readonly added: readonly string[];
+}
+/** WHO ANSWERS changed — the one class that blocks without an
+ *  explicit acknowledgement. */
+ | {
+    readonly kind: "material";
+    readonly reasons: readonly string[];
+};
+/** The drift protocol's classifier — computed from the INVENTORY diff,
+ *  never from digest inequality alone: every recorded tool present with
+ *  identical hashes plus new names = compatible additions (a one-line
+ *  notice); a missing name, a changed hash, a provider/model divergence,
+ *  or a system-prompt divergence = MATERIAL (explicit resolution; a
+ *  digest mismatch is never presented as restoration). */
+export declare function assessProfileDrift(recorded: ExecutionProfile, current: {
+    readonly provider: ProfileModelRef | null;
+    readonly systemPromptDigest: string;
+    readonly tools: readonly ProfileToolRecord[];
+}): ProfileDrift;

package/dist/profile.js

@@ -0,0 +1,151 @@
+/**
+ * XP-1 — the durable execution profile (the ratified spec §3).
+ *
+ * ONE product contract: a session must know what will answer its next
+ * request after a restart. The profile is a durable session fact OUTSIDE
+ * the event log — ADR-0051 §6's OUT class ("session metadata that is not
+ * an event"), so no contract amendment is spent on persistence; the §6
+ * purity gate extends instead: the correctness derivation never reads it.
+ *
+ * The sidecar is `<id>.meta.json` (the adjudicated namespaced file — the
+ * profile is its first tenant, SX-1's naming joins later), written
+ * FAIL-CLOSED: temp → fsync(file) → rename → fsync(parent directory),
+ * full replacement per revision. A new session writes revision 1 BEFORE
+ * its first durable event; an unreadable sidecar is BLOCKED, never
+ * silently treated as absent (the "corrupt = legacy = today's defaults"
+ * misclassification is the exact silent rebuild the spec forbids).
+ *
+ * Never a secret: the profile carries the profile NAME and env-var-shaped
+ * references at most — no key, token, or credential material.
+ */
+import { closeSync, fsyncSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { dirname, join } from "node:path";
+const sha = (text) => createHash("sha256").update(text).digest("hex");
+export function toolInventory(registry) {
+    return registry
+        .toSpecs()
+        .map((spec) => ({
+        name: spec.name,
+        schemaHash: sha(JSON.stringify(spec.inputSchema ?? null)),
+        descriptionHash: sha(spec.description ?? ""),
+    }))
+        .sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+export function buildProfile(input) {
+    const tools = toolInventory(input.registry);
+    return {
+        revision: input.revision,
+        at: new Date().toISOString(),
+        modelId: input.modelId,
+        provider: input.provider,
+        profileName: input.profileName ?? null,
+        reasoning: input.reasoning ?? { thinking: "default", effort: "default" },
+        systemPromptDigest: sha(input.systemPrompt ?? ""),
+        tools,
+        toolManifestDigest: sha(JSON.stringify(tools)),
+    };
+}
+export function profilePath(root, sessionId) {
+    return join(root, `${sessionId}.meta.json`);
+}
+/** Atomic, fail-closed write: a reader sees the previous revision or the
+ *  new one, never a torn file — and the RENAME itself is made durable by
+ *  the parent-directory fsync. */
+export function writeProfile(root, sessionId, profile) {
+    const path = profilePath(root, sessionId);
+    const tmpDir = mkdtempSync(join(root, ".meta-"));
+    const tmp = join(tmpDir, "meta.json");
+    try {
+        writeFileSync(tmp, `${JSON.stringify({ profile }, null, "\t")}\n`);
+        const fd = openSync(tmp, "r");
+        try {
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(tmp, path);
+        const dirFd = openSync(dirname(path), "r");
+        try {
+            fsyncSync(dirFd);
+        }
+        finally {
+            closeSync(dirFd);
+        }
+    }
+    finally {
+        rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+export function readProfile(root, sessionId) {
+    const path = profilePath(root, sessionId);
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { kind: "absent" };
+        return { kind: "corrupt", error: String(err.message ?? err) };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const p = parsed.profile;
+        if (p === undefined ||
+            typeof p.revision !== "number" ||
+            typeof p.at !== "string" ||
+            typeof p.modelId !== "string" ||
+            typeof p.systemPromptDigest !== "string" ||
+            typeof p.toolManifestDigest !== "string" ||
+            !Array.isArray(p.tools)) {
+            return { kind: "corrupt", error: "the profile tenant is missing or malformed" };
+        }
+        return { kind: "ok", profile: p };
+    }
+    catch (err) {
+        return { kind: "corrupt", error: String(err.message ?? err) };
+    }
+}
+/** The drift protocol's classifier — computed from the INVENTORY diff,
+ *  never from digest inequality alone: every recorded tool present with
+ *  identical hashes plus new names = compatible additions (a one-line
+ *  notice); a missing name, a changed hash, a provider/model divergence,
+ *  or a system-prompt divergence = MATERIAL (explicit resolution; a
+ *  digest mismatch is never presented as restoration). */
+export function assessProfileDrift(recorded, current) {
+    const reasons = [];
+    const notes = [];
+    const r = recorded.provider;
+    const c = current.provider;
+    if ((r === null) !== (c === null)) {
+        reasons.push(`the recorded binding is ${r === null ? "unscoped" : `${r.providerId}/${r.modelId}`} but the current process serves ${c === null ? "an unscoped adapter" : `${c.providerId}/${c.modelId}`}`);
+    }
+    else if (r !== null && c !== null && r.providerId !== c.providerId) {
+        reasons.push(`the recorded provider is ${r.providerId} but the current process serves ${c.providerId}`);
+    }
+    if (recorded.systemPromptDigest !== current.systemPromptDigest) {
+        notes.push(`the composed system prompt differs from the recorded one (${recorded.systemPromptDigest.slice(0, 12)}… → ${current.systemPromptDigest.slice(0, 12)}…)`);
+    }
+    const currentByName = new Map(current.tools.map((t) => [t.name, t]));
+    const added = [];
+    for (const t of recorded.tools) {
+        const now = currentByName.get(t.name);
+        if (now === undefined) {
+            notes.push(`the recorded tool "${t.name}" is not loaded in this process`);
+        }
+        else if (now.schemaHash !== t.schemaHash) {
+            notes.push(`the tool "${t.name}" changed its schema since it was recorded`);
+        }
+        currentByName.delete(t.name);
+    }
+    for (const name of currentByName.keys())
+        added.push(name);
+    if (reasons.length > 0)
+        return { kind: "material", reasons };
+    if (notes.length > 0)
+        return { kind: "surface-changed", notes };
+    if (added.length > 0)
+        return { kind: "compatible-additions", added };
+    return { kind: "clean" };
+}

package/dist/provider/manifest.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MG-1 — the identity layer above the adapter port (ADR-0051 Amendment 5
+ * carries the wire half; this file carries WHO things are).
+ *
+ * Four concepts `openai-compat` used to conflate, separated: the PROVIDER
+ * (a vendor identity), the API DIALECT it is driven through, the MODEL,
+ * and (for custom endpoints) the ORIGIN. A provider chooses a dialect; it
+ * is not itself a dialect. Manifests here are IDENTITY ONLY — no
+ * capability data (capabilities are dated claims and live in the metadata
+ * registry), no credential material ever.
+ *
+ * Lives under runtime/internal — the curated root surface does not move.
+ */
+import type { ContinuationScope } from "@vincemakes/kiso-core";
+export interface ModelRef {
+    readonly providerId: string;
+    readonly apiId: string;
+    readonly modelId: string;
+}
+export interface ProviderManifest {
+    readonly id: string;
+    /** A dated claim snapshot, not an API promise (date-stamped ordinal). */
+    readonly revision: string;
+    readonly authMethods: readonly string[];
+    readonly apiIds: readonly string[];
+    readonly defaultEndpoint?: string;
+}
+/** The five built-in identities. `custom` is the honest bucket for any
+ *  OpenAI-compatible endpoint the origin table does not recognize —
+ *  capabilities default to UNKNOWN there, never borrowed from OpenAI. */
+export declare const BUILTIN_MANIFESTS: readonly ProviderManifest[];
+/** The run's continuation scope, resolved from the live binding. An
+ *  undefined provider (a directly injected SDK/faux adapter) is an
+ *  UNSCOPED run: the kernel strips adapter-emitted continuation. */
+export declare function resolveContinuationScope(provider: "anthropic" | "openai-compat" | undefined, model: string, baseUrl?: string): ContinuationScope | undefined;

package/dist/provider/manifest.js

@@ -0,0 +1,57 @@
+/**
+ * MG-1 — the identity layer above the adapter port (ADR-0051 Amendment 5
+ * carries the wire half; this file carries WHO things are).
+ *
+ * Four concepts `openai-compat` used to conflate, separated: the PROVIDER
+ * (a vendor identity), the API DIALECT it is driven through, the MODEL,
+ * and (for custom endpoints) the ORIGIN. A provider chooses a dialect; it
+ * is not itself a dialect. Manifests here are IDENTITY ONLY — no
+ * capability data (capabilities are dated claims and live in the metadata
+ * registry), no credential material ever.
+ *
+ * Lives under runtime/internal — the curated root surface does not move.
+ */
+/** The five built-in identities. `custom` is the honest bucket for any
+ *  OpenAI-compatible endpoint the origin table does not recognize —
+ *  capabilities default to UNKNOWN there, never borrowed from OpenAI. */
+export const BUILTIN_MANIFESTS = [
+    { id: "anthropic", revision: "2026-08-26.1", authMethods: ["api-key", "none"], apiIds: ["anthropic-messages"], defaultEndpoint: "https://api.anthropic.com" },
+    { id: "openai", revision: "2026-08-26.1", authMethods: ["api-key", "none"], apiIds: ["openai-chat", "openai-responses"], defaultEndpoint: "https://api.openai.com" },
+    { id: "deepseek", revision: "2026-08-26.1", authMethods: ["api-key", "none"], apiIds: ["openai-chat"], defaultEndpoint: "https://api.deepseek.com" },
+    { id: "zai", revision: "2026-08-26.1", authMethods: ["api-key", "none"], apiIds: ["openai-chat"], defaultEndpoint: "https://api.z.ai" },
+    { id: "custom", revision: "2026-08-26.1", authMethods: ["api-key", "none"], apiIds: ["openai-chat"] },
+];
+/** Known-origin recognition (the ratified Q3 answer): a compat profile
+ *  whose baseUrl origin equals a built-in manifest's endpoint resolves to
+ *  that provider identity — deterministic and manifest-driven, so a
+ *  pre-preset DeepSeek envelope is not foreign the day presets ship. */
+const KNOWN_ORIGINS = {
+    "https://api.deepseek.com": "deepseek",
+    "https://api.z.ai": "zai",
+    "https://open.bigmodel.cn": "zai",
+    "https://api.openai.com": "openai",
+};
+/** The run's continuation scope, resolved from the live binding. An
+ *  undefined provider (a directly injected SDK/faux adapter) is an
+ *  UNSCOPED run: the kernel strips adapter-emitted continuation. */
+export function resolveContinuationScope(provider, model, baseUrl) {
+    if (provider === undefined)
+        return undefined;
+    if (provider === "anthropic") {
+        return { providerId: "anthropic", apiId: "anthropic-messages", modelId: model };
+    }
+    if (baseUrl === undefined) {
+        return { providerId: "openai", apiId: "openai-chat", modelId: model };
+    }
+    let origin;
+    try {
+        origin = new URL(baseUrl).origin;
+    }
+    catch {
+        return { providerId: "custom", apiId: "openai-chat", modelId: model, endpoint: baseUrl };
+    }
+    const known = KNOWN_ORIGINS[origin];
+    if (known !== undefined)
+        return { providerId: known, apiId: "openai-chat", modelId: model };
+    return { providerId: "custom", apiId: "openai-chat", modelId: model, endpoint: origin };
+}

package/dist/provider/metadata.d.ts

@@ -26,8 +26,57 @@ export interface ModelCapabilities {
      *  OpenAI); "explicit" — the request must place cache_control
      *  breakpoints (Anthropic); "none" — no caching; null = unknown. */
     readonly promptCaching: "none" | "automatic" | "explicit" | null;
-    /** the model emits a reasoning stream (thinking); null = unknown. */
-    readonly reasoning: boolean | null;
+    /** XP-1: the reasoning capability matrix — supersedes the pre-XP-1
+     *  boolean IN PLACE (zero consumers existed, verified). null = unknown:
+     *  no mode list, no effort levels, nothing downstream may guess. */
+    readonly reasoning: ReasoningCapabilities | null;
+    /** MG-1: the input parts the model accepts (e.g. ["text","image"]);
+     *  null = unknown — the CLI treats unknown as text-only with an honest
+     *  notice, never a guess. Evidenced by 0.15.7's image attachments:
+     *  the gateway must know before the request is built. */
+    readonly inputModalities: readonly string[] | null;
+}
+/** XP-1 (the ratified spec §4.1): the two ORTHOGONAL axes. "default" on
+ *  each axis means the provider's own default, displayed honestly as
+ *  such. The union nesting effort under enabled stays rejected: Anthropic
+ *  effort affects whole responses with or without explicit thinking, and
+ *  some model/effort combinations forbid thinking-disabled. */
+export type ThinkingMode = "default" | "adaptive" | "enabled" | "disabled";
+export type ReasoningEffort = "default" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+export interface ReasoningSetting {
+    readonly thinking: ThinkingMode;
+    readonly effort: ReasoningEffort;
+}
+/** XP-1 §4.2: the per-model matrix. A provider's toggle semantics are a
+ *  dated claim about someone else's API — the same class as a price, so
+ *  the block carries asOf + source exactly as pricing does. */
+export interface ReasoningCapabilities {
+    /** the old boolean's meaning, preserved under its own name. */
+    readonly emitsThinkingStream: boolean | null;
+    /** null = no request-time toggle is known for this model. */
+    readonly thinking: {
+        readonly modes: readonly Exclude<ThinkingMode, "default">[];
+        readonly default: Exclude<ThinkingMode, "default"> | null;
+    } | null;
+    /** null = no effort control is known. `levels` are NATIVE only —
+     *  compatibility mappings are displayed as their resolution, never as
+     *  distinct native levels. `wire` names the dialect parameter. */
+    readonly effort: {
+        readonly levels: readonly Exclude<ReasoningEffort, "default">[];
+        readonly default: Exclude<ReasoningEffort, "default"> | null;
+        readonly wire: string;
+    } | null;
+    /** invalid combinations the provider documents (e.g. thinking-disabled
+     *  at certain efforts). */
+    readonly forbidden?: readonly ReasoningSetting[];
+    readonly asOf: string | null;
+    readonly source: string | null;
+}
+/** XP-1: the resolved wire values — what an adapter actually serializes.
+ *  Empty = provider defaults, byte-identical to a pre-XP-1 request. */
+export interface WireReasoning {
+    readonly thinking?: "adaptive" | "enabled" | "disabled";
+    readonly effort?: string;
 }
 export interface ModelPricing {
     readonly inputPerM: number;
@@ -45,7 +94,19 @@ export interface ModelMetadataEntry {
     /** origin qualifier (e.g. "https://api.deepseek.com"): when present,
      *  the entry matches only requests aimed at that endpoint. */
     readonly endpoint?: string;
+    /** MG-1: the provider identity (manifest id) — retires the string
+     *  inference from the model id's hyphen prefix. */
+    readonly providerId?: string;
     readonly capabilities: ModelCapabilities;
+    /** XP-1: a provider-announced retirement, dated and sourced. */
+    readonly deprecated?: {
+        readonly asOf: string;
+        readonly source: string;
+    };
+    /** MG-1: capability values are dated claims exactly as prices are —
+     *  null marks an undated legacy claim (the pre-MG-1 table). */
+    readonly capabilitiesAsOf?: string | null;
+    readonly capabilitiesSource?: string | null;
     readonly pricing: ModelPricing | null;
 }
 /**
@@ -54,3 +115,19 @@ export interface ModelMetadataEntry {
  * one matches any endpoint. Unknown model → null, never a default.
  */
 export declare function lookupModelMetadata(model: string, endpoint?: string): ModelMetadataEntry | null;
+/**
+ * XP-1 §4.2 — native-only resolution. The rules, in order:
+ *   default/default → NO wire fields (the byte-identity anchor — a
+ *   default-profile session's requests are byte-identical to pre-XP-1);
+ *   an unknown model refuses any non-default selection (unknown stays
+ *   unknown — nothing downstream guesses a level into existence);
+ *   a value outside the matrix's NATIVE list is refused with the native
+ *   list named — never silently downgraded, never silently mapped.
+ */
+export declare function resolveReasoning(model: string, setting: ReasoningSetting, endpoint?: string): {
+    readonly ok: true;
+    readonly wire: WireReasoning;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};

package/dist/provider/metadata.js

@@ -34,26 +34,82 @@ const DEEPSEEK_PRICING = {
 const ENTRIES = [
     {
         model: "deepseek-chat",
+        providerId: "deepseek",
+        // XP-1: the changelog entry dated 2026-04-24 discontinues the two
+        // legacy names on 2026-07-24 (they pointed at v4-flash during the
+        // transition). v6's "unsourced" rider cited the wrong page.
+        deprecated: { asOf: "2026-07-24", source: "https://api-docs.deepseek.com/updates/" },
         endpoint: "https://api.deepseek.com",
-        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: false },
+        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: { emitsThinkingStream: false, thinking: null, effort: null, asOf: null, source: null }, inputModalities: null },
         pricing: DEEPSEEK_PRICING,
     },
     {
         model: "deepseek-reasoner",
+        providerId: "deepseek",
+        // XP-1: the changelog entry dated 2026-04-24 discontinues the two
+        // legacy names on 2026-07-24 (they pointed at v4-flash during the
+        // transition). v6's "unsourced" rider cited the wrong page.
+        deprecated: { asOf: "2026-07-24", source: "https://api-docs.deepseek.com/updates/" },
         endpoint: "https://api.deepseek.com",
-        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: true },
+        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: { emitsThinkingStream: true, thinking: null, effort: null, asOf: null, source: null }, inputModalities: null },
         pricing: DEEPSEEK_PRICING,
     },
     {
         model: "claude-sonnet-5",
-        capabilities: { contextWindow: 200_000, maxOutputTokens: null, promptCaching: "explicit", reasoning: true },
+        providerId: "anthropic",
+        capabilities: { contextWindow: 200_000, maxOutputTokens: null, promptCaching: "explicit",
+            reasoning: {
+                emitsThinkingStream: true,
+                thinking: null,
+                effort: { levels: ["low", "medium", "high", "xhigh", "max"], default: "high", wire: "output_config.effort" },
+                asOf: "2026-08-26",
+                source: "https://platform.claude.com/docs/en/build-with-claude/effort",
+            },
+            inputModalities: null },
         // Priced only when the rates are read from the live billing page
         // and dated — never copied from memory (the review's boundary ②).
         pricing: null,
     },
+    {
+        // XP-1: the current DeepSeek line — the model every RD-1 benchmark
+        // artifact was produced with, previously ABSENT (null pricing and
+        // capabilities everywhere). Thinking is a request-time toggle,
+        // default-ENABLED; effort is native low/high/max (foreign levels
+        // are the provider's own mapping, never shown as native). Pricing
+        // stays null until read from the live billing page and dated.
+        model: "deepseek-v4-flash",
+        providerId: "deepseek",
+        endpoint: "https://api.deepseek.com",
+        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: {
+                emitsThinkingStream: true,
+                thinking: { modes: ["enabled", "disabled"], default: "enabled" },
+                effort: { levels: ["low", "high", "max"], default: "high", wire: "reasoning_effort" },
+                asOf: "2026-08-26",
+                source: "https://api-docs.deepseek.com/guides/thinking_mode",
+            }, inputModalities: null },
+        capabilitiesAsOf: "2026-08-26",
+        capabilitiesSource: "https://api-docs.deepseek.com/guides/thinking_mode",
+        pricing: null,
+    },
+    {
+        model: "deepseek-v4-pro",
+        providerId: "deepseek",
+        endpoint: "https://api.deepseek.com",
+        capabilities: { contextWindow: null, maxOutputTokens: null, promptCaching: "automatic", reasoning: {
+                emitsThinkingStream: true,
+                thinking: { modes: ["enabled", "disabled"], default: "enabled" },
+                effort: { levels: ["low", "high", "max"], default: "high", wire: "reasoning_effort" },
+                asOf: "2026-08-26",
+                source: "https://api-docs.deepseek.com/guides/thinking_mode",
+            }, inputModalities: null },
+        capabilitiesAsOf: "2026-08-26",
+        capabilitiesSource: "https://api-docs.deepseek.com/guides/thinking_mode",
+        pricing: null,
+    },
     {
         model: "gpt-4o",
-        capabilities: { contextWindow: 128_000, maxOutputTokens: null, promptCaching: "automatic", reasoning: false },
+        providerId: "openai",
+        capabilities: { contextWindow: 128_000, maxOutputTokens: null, promptCaching: "automatic", reasoning: { emitsThinkingStream: false, thinking: null, effort: null, asOf: null, source: null }, inputModalities: null },
         pricing: null,
     },
 ];
@@ -80,3 +136,41 @@ function originOf(endpoint) {
         return endpoint;
     }
 }
+/**
+ * XP-1 §4.2 — native-only resolution. The rules, in order:
+ *   default/default → NO wire fields (the byte-identity anchor — a
+ *   default-profile session's requests are byte-identical to pre-XP-1);
+ *   an unknown model refuses any non-default selection (unknown stays
+ *   unknown — nothing downstream guesses a level into existence);
+ *   a value outside the matrix's NATIVE list is refused with the native
+ *   list named — never silently downgraded, never silently mapped.
+ */
+export function resolveReasoning(model, setting, endpoint) {
+    if (setting.thinking === "default" && setting.effort === "default")
+        return { ok: true, wire: {} };
+    const r = lookupModelMetadata(model, endpoint)?.capabilities.reasoning ?? null;
+    if (r === null) {
+        return { ok: false, reason: `no reasoning capabilities are known for ${model} — unknown stays unknown; only default/default resolves` };
+    }
+    const wire = {};
+    if (setting.thinking !== "default") {
+        if (r.thinking === null || !r.thinking.modes.includes(setting.thinking)) {
+            const modes = r.thinking === null ? "none known" : r.thinking.modes.join("/");
+            return { ok: false, reason: `${model} does not support thinking mode "${setting.thinking}" (native: ${modes})` };
+        }
+        wire.thinking = setting.thinking;
+    }
+    if (setting.effort !== "default") {
+        if (r.effort === null || !r.effort.levels.includes(setting.effort)) {
+            const levels = r.effort === null ? "none known" : r.effort.levels.join("/");
+            return { ok: false, reason: `${model} does not support effort "${setting.effort}" (native: ${levels})` };
+        }
+        wire.effort = setting.effort;
+    }
+    for (const f of r.forbidden ?? []) {
+        if (f.thinking === setting.thinking && f.effort === setting.effort) {
+            return { ok: false, reason: `${model} forbids thinking=${setting.thinking} with effort=${setting.effort}` };
+        }
+    }
+    return { ok: true, wire };
+}

package/dist/run.js

@@ -5,6 +5,7 @@
  */
 import { denialResult, loop } from "@vincemakes/kiso-core";
 import { ABORTED, MergedSignal, abortable, openRunId } from "./recovery.js";
+import { resolveReasoning } from "./provider/metadata.js";
 import { deriveRecoveryPlan, invocationSeqOf } from "./recovery-plan.js";
 import { composeApprovalChain, composeSystemPrompt, composeToolTable, microcompactFor } from "./compose.js";
 import { truncationGuard } from "./truncation-guard.js";
@@ -131,6 +132,12 @@ export class Run {
                 ...(this.#config.compaction !== undefined ? { compaction: this.#config.compaction } : {}),
                 ...(microcompact !== undefined ? { microcompact } : {}),
                 ...(this.#config.maxRetries !== undefined ? { maxRetries: this.#config.maxRetries } : {}),
+                // MG-1 (A5): the kernel stamps committed envelopes with this.
+                ...(this.#config.continuationScope !== undefined ? { continuationScope: this.#config.continuationScope } : {}),
+                // XP-1: native-only resolution — an unsupported recorded
+                // setting REFUSES the run with the reason (no silent
+                // downgrade); default/default adds nothing (byte anchor).
+                ...(this.#config.reasoning !== undefined ? resolveReasoningOrThrow(this.#config.model, this.#config.reasoning) : {}),
                 // E1: the composed approval chain — the extensions'
                 // policies composed into ONE gate (deny > allow > ask).
                 ...(approvalChain !== undefined ? { approvalPolicy: approvalChain } : {}),
@@ -788,3 +795,11 @@ export class Run {
         });
     }
 }
+/** XP-1: the run-side half of "no silent downgrade" — a setting the
+ *  matrix refuses becomes an actionable failure, never a quiet default. */
+function resolveReasoningOrThrow(model, setting) {
+    const r = resolveReasoning(model, setting);
+    if (!r.ok)
+        throw new Error(`the session's recorded reasoning setting cannot run here: ${r.reason}`);
+    return Object.keys(r.wire).length > 0 ? { reasoning: r.wire } : {};
+}

package/dist/session.d.ts

@@ -29,6 +29,8 @@
  */
 import { EventLog, type AbortSignalLike, type Adapter, type Event, type KisoExtension, type Message, type PermissionDecision, type Tool } from "@vincemakes/kiso-core";
 import { type TaskAssessment } from "./task-assessment.js";
+import { type ContinuationScope } from "@vincemakes/kiso-core";
+import type { ReasoningSetting } from "./provider/metadata.js";
 import { type SessionStore } from "./store.js";
 import { Run } from "./run.js";
 /** TUI2-R3v2 ③ — one off-trajectory model request (session.sideQuery).
@@ -129,12 +131,24 @@ export declare class AgentSession {
         readonly adapter: Adapter;
         readonly model: string;
         readonly provider?: "anthropic" | "openai-compat";
+        /** MG-1 (A5): the run's continuation scope — moves atomically with
+         *  the adapter (absent = unscoped: the kernel strips envelopes). */
+        readonly scope?: ContinuationScope;
+        /** XP-1: the reasoning axes travel with the binding too; absent =
+         *  fresh defaults (a new binding never inherits stale effort). */
+        readonly reasoning?: ReasoningSetting;
     }): void;
     /** E2: the adapter identity ("anthropic" | "openai-compat") — the route
      *  key the canonical consumer (CLI usage, the trace block) keys on. The
      *  per-run tracer reads the SAME live binding; one source, one
      *  route — the CLI and the trace can never disagree. */
     get provider(): "anthropic" | "openai-compat" | undefined;
+    /** XP-1: the model that will answer the NEXT request — the live
+     *  binding, restored from the durable profile on open. The status row
+     *  reads THIS, so the row and the request can never disagree. */
+    get model(): string;
+    /** XP-1: the selected reasoning axes (resolution happens per request). */
+    get reasoning(): ReasoningSetting;
     /**
      * TUI2-R3v2 ③ — ONE model request that belongs to no run (the
      * safer-options seam, adjudicated 2026-08-18).
@@ -358,6 +372,13 @@ export interface SessionConfig {
     /** E1: the adapter identity ("anthropic" | "openai-compat") — trace
      *  provenance, additive (S1 surface untouched: type-only, optional). */
     readonly provider?: "anthropic" | "openai-compat";
+    /** MG-1 (A5): the run's continuation scope — the kernel stamps it on
+     *  committed envelopes; absent = unscoped (envelopes stripped). */
+    readonly continuationScope?: import("@vincemakes/kiso-core").ContinuationScope;
+    /** XP-1: the selected reasoning axes (native-only resolution per request). */
+    readonly reasoning?: import("./provider/metadata.js").ReasoningSetting;
+    /** XP-1 internal: a legacy session's deferred revision-1 write. */
+    readonly profilePending?: true;
     readonly systemPrompt?: string;
     readonly tools?: readonly Tool<any>[];
     readonly registry: import("@vincemakes/kiso-core").ToolRegistry;

package/dist/session.js

@@ -35,6 +35,7 @@ import { assessTasks } from "./task-assessment.js";
  *  verification surface. Override per call for custom evidence tools. */
 const DEFAULT_EVIDENCE_TOOLS = new Set(["shell"]);
 import { denialResult } from "@vincemakes/kiso-core";
+import { buildProfile, readProfile, writeProfile } from "./profile.js";
 import { DROP_PLACEHOLDER, estimateSummarySavings, KEEP_RECENT_ROUNDS, KEEP_TOKENS_DEFAULT, lastSummaryPoint, MAX_SUMMARY_FAILURES, policyTriggerFromWindow, serializeCovered, SUMMARY_MAX_OUTPUT, summarizeConversation, summaryBoundarySeq, } from "./summarize.js";
 import { canonicalizeUsageForModel } from "./usage/canonical.js";
 import { appendFileSync, mkdirSync } from "node:fs";
@@ -84,6 +85,13 @@ export class AgentSession {
     // setAdapter always had).
     #model;
     #provider;
+    // MG-1 (A5): travels WITH the adapter, same next-turn semantics.
+    #continuationScope;
+    // XP-1: the selected axes; resolved per request (next-turn semantics).
+    #reasoning;
+    // XP-1: a legacy session records revision 1 at the next explicit
+    // selection or first request — never eagerly at open.
+    #profilePending;
     #pendingResolvers = new Map();
     #uncertaintyResolvers = new Map();
     #answered = new Set();
@@ -137,14 +145,23 @@ export class AgentSession {
         this.#config = composedHooks === undefined ? config : { ...config, hooks: composedHooks };
         this.#model = config.model;
         this.#provider = config.provider;
+        this.#continuationScope = config.continuationScope;
+        this.#reasoning = config.reasoning ?? { thinking: "default", effort: "default" };
+        this.#profilePending = config.profilePending === true;
     }
     /** The config a NEW run/resume/summary sees: the frozen startup config
      *  with the LIVE binding fields (model, provider) substituted. Built
      *  fresh per call so an in-flight run keeps the config it started with
      *  — the same boundary setAdapter has always drawn. */
     #effectiveConfig() {
-        const { provider: _startup, ...rest } = this.#config;
-        return { ...rest, model: this.#model, ...(this.#provider !== undefined ? { provider: this.#provider } : {}) };
+        const { provider: _startup, continuationScope: _startupScope, ...rest } = this.#config;
+        return {
+            ...rest,
+            model: this.#model,
+            ...(this.#provider !== undefined ? { provider: this.#provider } : {}),
+            ...(this.#continuationScope !== undefined ? { continuationScope: this.#continuationScope } : {}),
+            reasoning: this.#reasoning,
+        };
     }
     /** Write-ahead through the store; a rejected write POISONS the session
      *  (round 1/round 4): the in-memory log no longer matches the disk — whatever
@@ -204,6 +221,11 @@ export class AgentSession {
         this.#adapter = binding.adapter;
         this.#model = binding.model;
         this.#provider = binding.provider;
+        this.#continuationScope = binding.scope;
+        this.#reasoning = binding.reasoning ?? { thinking: "default", effort: "default" };
+        // XP-1: an explicit selection is DURABLE — the setting survives
+        // /resume because a revision records it now, not at some later flush.
+        this.#recordProfile();
     }
     /** E2: the adapter identity ("anthropic" | "openai-compat") — the route
      *  key the canonical consumer (CLI usage, the trace block) keys on. The
@@ -212,6 +234,31 @@ export class AgentSession {
     get provider() {
         return this.#provider;
     }
+    /** XP-1: the model that will answer the NEXT request — the live
+     *  binding, restored from the durable profile on open. The status row
+     *  reads THIS, so the row and the request can never disagree. */
+    get model() {
+        return this.#model;
+    }
+    /** XP-1: the selected reasoning axes (resolution happens per request). */
+    get reasoning() {
+        return this.#reasoning;
+    }
+    /** XP-1: record the live binding as the next durable profile revision
+     *  (read-modify-write under the session's single-writer ownership). */
+    #recordProfile() {
+        const prior = readProfile(this.#store.root, this.id);
+        const revision = prior.kind === "ok" ? prior.profile.revision + 1 : 1;
+        writeProfile(this.#store.root, this.id, buildProfile({
+            revision,
+            modelId: this.#model,
+            provider: this.#continuationScope ?? null,
+            reasoning: this.#reasoning,
+            ...(this.#config.systemPrompt !== undefined ? { systemPrompt: this.#config.systemPrompt } : {}),
+            registry: this.#config.registry,
+        }));
+        this.#profilePending = false;
+    }
     /**
      * TUI2-R3v2 ③ — ONE model request that belongs to no run (the
      * safer-options seam, adjudicated 2026-08-18).
@@ -299,6 +346,8 @@ export class AgentSession {
      *  send one. */
     run(input, options) {
         this.ensureHealthy();
+        if (this.#profilePending)
+            this.#recordProfile(); // XP-1: legacy revision 1, before the first request
         return new Run(this.#store, this.#adapter, this.#effectiveConfig(), this, input, options?.signal, false, options?.source);
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-runtime",
-	"version": "0.15.11",
+	"version": "0.16.0",
 	"description": "kiso runtime \u2014 durable multi-turn agent sessions: AgentDefinition, AgentRuntime, AgentSession, Run, append-only JSONL store.",
 	"type": "module",
 	"license": "MIT",
@@ -25,11 +25,11 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-core": "0.15.11"
+		"@vincemakes/kiso-core": "0.16.0"
 	},
 	"peerDependencies": {
-		"@vincemakes/kiso-provider-anthropic": "0.15.11",
-		"@vincemakes/kiso-provider-openai": "0.15.11"
+		"@vincemakes/kiso-provider-anthropic": "0.16.0",
+		"@vincemakes/kiso-provider-openai": "0.16.0"
 	},
 	"peerDependenciesMeta": {
 		"@vincemakes/kiso-provider-anthropic": {
@@ -40,7 +40,7 @@
 		}
 	},
 	"devDependencies": {
-		"@vincemakes/kiso-evals": "0.15.11",
+		"@vincemakes/kiso-evals": "0.16.0",
 		"@types/node": "^26.1.2",
 		"typescript": "^5.7.2",
 		"vitest": "^3.0.0"