@sqdr2/dsh-fusion 0.0.0-stage → 0.3.2

package/lib/types/host/native-checks.d.ts

@@ -0,0 +1,104 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
+import type { ToolEvidence, WorkOrder, WorkerReport } from '../contracts.js';
+import { evaluateReport } from '../evidence/gate.js';
+import type { CheckPlan, PlannedReceipt } from '../evidence/receipts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+export interface CheckDefinition {
+    id: string;
+    description: string;
+    command: string;
+    kind: 'test' | 'static-check';
+    parser: TestParser | 'exit-code';
+    /** Existing acceptance test files. Their bytes may not change during execution. May be empty for a new project. */
+    definitionPaths: readonly string[];
+    /** Per-check limit; defaults to the work-order policy. */
+    timeoutSeconds?: number;
+    /**
+     * `no-new-failures`: a broad regression suite measured against the untouched workspace. The Host runs it
+     * once before the Worker starts and freezes the failing test ids; the candidate passes when every failure
+     * it shows was already failing there. Default: every test must pass.
+     */
+    baseline?: 'no-new-failures';
+}
+/** Parsers that name each failing test, which baseline-relative checks need. Mocha's default report spreads a name over several lines. */
+export declare const BASELINE_PARSERS: readonly ["unittest", "pytest", "vitest", "jest", "tap", "go", "cargo"];
+export type BaselineParser = typeof BASELINE_PARSERS[number];
+export declare const TEST_PARSERS: readonly ["unittest", "pytest", "vitest", "jest", "mocha", "tap", "go", "cargo"];
+export type TestParser = typeof TEST_PARSERS[number];
+export declare const MAX_CHECK_SECONDS = 3600;
+export interface FrozenCheck {
+    definition: CheckDefinition;
+    plan: CheckPlan;
+}
+/** Shell setup failures need a corrected check, rather than an implementation repair. */
+export declare function checkCommandUnavailable(exitCode: number | null, stderr: string, platform?: NodeJS.Platform): boolean;
+export declare function freezeChecks(order: WorkOrder, root: string, definitions: readonly CheckDefinition[]): FrozenCheck[];
+/**
+ * Counts passed tests from a runner's summary. A suite passes when nothing failed or errored and at
+ * least one test ran; skipped, deselected, pending, ignored and expected-failure tests were not
+ * executed and do not veto the result (real projects routinely skip optional-dependency tests; study
+ * 2026-09-26: "799 passed, 86 skipped" blocked an otherwise verified acceptance).
+ */
+export declare function parseTestCounts(parser: CheckDefinition['parser'], text: string): PlannedReceipt['counts'];
+/**
+ * Passed count and the ids of failing tests, only when the output names every failure the summary counts:
+ * a failure without a name, or two failures under one name, would let a candidate trade a frozen failure for
+ * a new one. Ids must stay the same across runs, so positions (TAP numbers, durations) are not part of them.
+ */
+export declare function parseTestFailures(parser: CheckDefinition['parser'], text: string): {
+    passed: number;
+    failedIds: string[];
+} | undefined;
+/**
+ * Bare program names each simple command segment starts with. Paths are left
+ * out because an earlier `cd` in the same command changes where they resolve;
+ * anything this cannot parse is simply not probed.
+ */
+export declare function checkPrograms(command: string, platform?: NodeJS.Platform): string[];
+/**
+ * Resolves program names the way the native bash tool will: `bash -c` with the
+ * Host's own PATH (its subprocess scrub removes only credential-shaped and
+ * DSH_* names). Running here instead of through the tool keeps this read-only
+ * probe out of the user's approval flow. Returns undefined when inconclusive,
+ * for example without bash; the recorded check result is then the fallback.
+ */
+export declare function probeMissingPrograms(root: string, programs: readonly string[]): Promise<{
+    missing: string[];
+    alternatives: Record<string, string[]>;
+    locations: Record<string, string[]>;
+} | undefined>;
+/**
+ * Where a program missing from the Host PATH is installed anyway. A desktop app started from the Dock gets only
+ * the system PATH, so Homebrew, version-manager and per-user tools are invisible to bash there; naming the
+ * absolute path lets the Lead retry once instead of searching.
+ */
+export declare function programLocations(name: string, home?: string): string[];
+/** Trusted producer: commands run through native dispatch/permission and retain the enclosing tool token. */
+interface CheckInput {
+    ctx: Context;
+    store: SqliteFusionStore;
+    exec: ToolRunContext;
+    root: string;
+    order: WorkOrder;
+    nativeTimeout?: boolean;
+    authorizeNested(callId: string): () => void;
+    uncertain?(evidence: ToolEvidence): void;
+}
+/**
+ * Runs every baseline-relative check on the untouched workspace before the Worker starts and freezes the
+ * failing test ids into its plan. An unreadable baseline refuses the delegation: guessing would let a
+ * candidate hide new failures.
+ */
+export declare function runBaselineChecks(input: CheckInput & {
+    checks: readonly FrozenCheck[];
+}): Promise<FrozenCheck[]>;
+export declare function runNativeChecks(input: CheckInput & {
+    report: WorkerReport;
+    checks: readonly FrozenCheck[];
+}): Promise<{
+    report: WorkerReport;
+    receipts: PlannedReceipt[];
+    verdict: ReturnType<typeof evaluateReport>;
+}>;
+export {};

package/lib/types/host/native-compaction.d.ts

@@ -0,0 +1,8 @@
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+import type { PairProfile, PhysicalRoute } from '../contracts.js';
+/**
+ * Public llm/stream routing for the Host's mutable, one-shot summary envelope.
+ * The Host still owns the compaction transaction and records this exact target.
+ * Never replace a prepared AgentLoop request or start a nested model call.
+ */
+export declare function routeNativeCompaction(request: GenerateOptions, profile: PairProfile, effectiveRoute?: PhysicalRoute): void;

package/lib/types/host/native-context.d.ts

@@ -0,0 +1,36 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+import type { PhysicalRoute, Role, TokenMeasurement } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { SessionBinding } from './bindings.js';
+import { type NativeTaskContext } from './native-task-context.js';
+import type { NativeAuxiliaryRequests } from './native-auxiliary.js';
+type Owner = {
+    binding: SessionBinding;
+    role: Role;
+};
+interface ContextCheck {
+    route: PhysicalRoute;
+    measurement: TokenMeasurement;
+    budget: number;
+    purpose: GenerateOptions['purpose'] | 'conversation' | 'cache-keepalive';
+    logRevision: number;
+    nativeBaseline: string;
+    minimumRetainedInputTokens: number;
+}
+/** Optional summary routing, then final admission and the Host's single compaction owner. */
+export declare class NativeContextGuard {
+    #private;
+    readonly ctx: Context;
+    readonly store: SqliteFusionStore;
+    readonly owner: (agent: Agent) => Owner | undefined;
+    readonly blocked: (owner: Owner, reason: string) => void;
+    readonly taskContext?: NativeTaskContext | undefined;
+    readonly auxiliary?: NativeAuxiliaryRequests | undefined;
+    readonly route?: ((binding: SessionBinding, role: Role) => PhysicalRoute) | undefined;
+    constructor(ctx: Context, store: SqliteFusionStore, owner: (agent: Agent) => Owner | undefined, blocked: (owner: Owner, reason: string) => void, taskContext?: NativeTaskContext | undefined, auxiliary?: NativeAuxiliaryRequests | undefined, route?: ((binding: SessionBinding, role: Role) => PhysicalRoute) | undefined);
+    measure(agent: Agent, owner: Owner, request: GenerateOptions): Promise<ContextCheck>;
+    install(admit: (agent: Agent, owner: Owner, request: GenerateOptions) => void, ready: (agent: Agent, request: GenerateOptions) => void): () => void;
+}
+export {};

package/lib/types/host/native-effects.d.ts

@@ -0,0 +1,75 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { JobView } from '@deepseek-ai/dsh-jobs';
+import type { ArtifactRef, Role, TaskId } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { SessionBinding } from './bindings.js';
+interface EffectRecord {
+    schemaVersion: 1;
+    taskId: TaskId;
+    agentId: string;
+    role: Role;
+    callId: string;
+    rootCallId: string;
+    toolName: string;
+    processId: number;
+    startedAt: string;
+    state: 'dispatch-started' | 'returned' | 'outcome-unknown' | 'inspected';
+    arguments: ArtifactRef;
+    endedAt?: string;
+    nativeIsError?: boolean;
+    inspectionEvidence?: string;
+    quiescenceBasis?: 'explicit-user-inspection';
+    nativeJob?: {
+        id: string;
+        startedAt: number;
+        deadlineAt: number | null;
+        status: JobView['status'];
+        detail?: string;
+    };
+}
+/** Public native dispatch journal; it never wraps a provider or invents a PID. */
+export declare class NativeEffects {
+    #private;
+    readonly ctx: Context;
+    readonly store: SqliteFusionStore;
+    readonly callbacks: {
+        owner(agent: Agent): {
+            binding: SessionBinding;
+            role: Role;
+        } | undefined;
+        track(exec: Readonly<ToolExecution>): boolean;
+        failed(agent: Agent, error: unknown): void;
+        backgroundMaxMs?(exec: Readonly<ToolExecution>, binding: SessionBinding): number | null;
+    };
+    constructor(ctx: Context, store: SqliteFusionStore, callbacks: {
+        owner(agent: Agent): {
+            binding: SessionBinding;
+            role: Role;
+        } | undefined;
+        track(exec: Readonly<ToolExecution>): boolean;
+        failed(agent: Agent, error: unknown): void;
+        backgroundMaxMs?(exec: Readonly<ToolExecution>, binding: SessionBinding): number | null;
+    });
+    install(): () => void;
+    backgroundProblem(exec: Readonly<ToolExecution>): string | undefined;
+    jobProblem(exec: Readonly<ToolExecution>, taskId: TaskId): string | undefined;
+    waitingForJob(agent: Agent): boolean;
+    /**
+     * Whether a tool call this process is running belongs to this task, or a
+     * native job it started there is still unsettled. This is the in-process half
+     * of the deletion guard: a durable row alone cannot tell a live call from the
+     * residue of an interrupted one, because both look like `dispatch-started`.
+     */
+    live(taskId: TaskId): boolean;
+    onlyBackgroundPending(taskId: TaskId): boolean;
+    stopJobs(taskId: TaskId): Promise<void>;
+    pending(taskId: TaskId): readonly {
+        id: string;
+        record: EffectRecord;
+    }[];
+    assertInspection(taskId: TaskId, effectsStopped: boolean): void;
+    inspected(taskId: TaskId, evidence: string, effectsStopped: boolean): void;
+}
+export {};

package/lib/types/host/native-evidence.d.ts

@@ -0,0 +1,4 @@
+import type { TaskId } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+/** Coverage uses logical receipt IDs; ordinary evidence uses content digests. */
+export declare function readNativeEvidence(store: SqliteFusionStore, taskId: TaskId, id: string): Uint8Array;

package/lib/types/host/native-exploration.d.ts

@@ -0,0 +1,15 @@
+import type { ExplorationReport, ExplorationSource, WorkOrder } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { WorkspaceSnapshot } from './workspace.js';
+/**
+ * Source-backed handoff. Completed reports are checked against the files they cite,
+ * not against every other file in a non-git root. blocked and needs-decision reports
+ * are always recorded, with drift or a failed whole-tree snapshot named, and are not acceptance.
+ *
+ * `current` is omitted when snapshotting the tree threw. The failure is stored on a
+ * non-completed report. A completed report ignores that unrelated failure and still
+ * stands or falls on the cited files alone.
+ */
+export declare function captureExploration(store: SqliteFusionStore, order: WorkOrder, baseline: WorkspaceSnapshot, current: WorkspaceSnapshot | undefined, submitted: Pick<ExplorationReport, 'summary' | 'status' | 'unresolved'>, sources: readonly ExplorationSource[], snapshotFailure?: string): ExplorationReport;
+/** Path of the first cited file whose bytes no longer match the captured digest, if any. */
+export declare function citedEvidenceChanged(root: string, baseline: WorkspaceSnapshot, report: Pick<ExplorationReport, 'sources'>): string | undefined;

package/lib/types/host/native-keepalive.d.ts

@@ -0,0 +1,82 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+import type { Role, TaskId } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { SessionBinding } from './bindings.js';
+import type { CacheMode } from './cache-defaults.js';
+import { NativeAuxiliaryRequests } from './native-auxiliary.js';
+/** R19 recovered schedule. */
+export declare const KEEPALIVE_INTERVAL_MS = 285000;
+/**
+ * The line appended after the copied prefix. maxTokens: 1 is not enough on its own: the ChatGPT Codex route
+ * rejects an output cap and pi-ai omits it, so a ping that said "continue" made the Lead think and call tools
+ * (live log: median 463 output tokens, all ending in tool calls). Measured 2026-10-01 on gpt-6-astra (Codex):
+ * "Reply OK" answered "OK" in 5 output tokens, 0 reasoning, no tool calls, 16/16 with tools still offered,
+ * full cache hit; "continue" called tools 8/8 and a bare "OK" read as approval and produced a plan.
+ * Tool choice and reasoning effort cannot change here: effort is part of OpenAI's cache key (effort "low"
+ * missed the cache entirely) and DSH requests carry no tool_choice.
+ */
+export declare const KEEPALIVE_PROMPT = "Reply OK";
+export declare const KEEPALIVE_ATTEMPTS = 11;
+export interface KeepaliveClock {
+    now(): number;
+    schedule(callback: () => void, delayMs: number): () => void;
+}
+type Owner = {
+    binding: SessionBinding;
+    role: Role;
+};
+interface Callbacks {
+    owner(agent: Agent): Owner | undefined;
+    allowed(agent: Agent, owner: Owner): boolean;
+    failed(agent: Agent, reason: string): void;
+    /** Per-model mode and interval (user setting, learned, defaults); absent: the pair profile and a fixed interval. */
+    policy?(owner: Owner, provider: string, model: string): {
+        mode: CacheMode;
+        intervalMs: number;
+    };
+    /** Evidence for learning and the settings page: a request after a wait, or a ping. */
+    observe?(owner: Owner, provider: string, model: string, sample: {
+        gapSeconds: number;
+        ping: boolean;
+        hit: boolean;
+        cacheRead: number;
+        input: number;
+        output?: number;
+    }): void;
+}
+export interface KeepaliveRecord {
+    schemaVersion: 1;
+    id: string;
+    taskId: TaskId;
+    sessionId: string;
+    role: Role;
+    profileDigest: string;
+    inputDigest: string;
+    createdAt: string;
+    updatedAt: string;
+    state: 'generating' | 'scheduled' | 'inflight' | 'stopped';
+    attempts: number;
+    successes: number;
+    stopReason?: string;
+}
+/** Retains only plugin-owned requests in memory; never replays timers on restart. */
+/** Explicit per-role choice; unset is automatic for the Lead (armed only on observed cache reads), off for the Worker. */
+export declare function keepalivePolicy(binding: SessionBinding, role: Role): boolean | 'auto';
+export declare class NativeCacheKeepalive {
+    #private;
+    readonly ctx: Context;
+    readonly store: SqliteFusionStore;
+    readonly auxiliary: NativeAuxiliaryRequests;
+    readonly callbacks: Callbacks;
+    readonly clock: KeepaliveClock;
+    constructor(ctx: Context, store: SqliteFusionStore, auxiliary: NativeAuxiliaryRequests, callbacks: Callbacks, clock?: KeepaliveClock);
+    stopSession(sessionId: string, reason: string): Promise<void>;
+    stopTask(taskId: TaskId, reason: string): Promise<void>;
+    /** Called again after asynchronous context measurement, before spend admission. */
+    assertRequest(agent: Agent, request: GenerateOptions): void;
+    install(): void;
+    close(): Promise<void>;
+}
+export {};

package/lib/types/host/native-model-control.d.ts

@@ -0,0 +1,99 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { LlmFailure, UserMessage } from '@deepseek-ai/dsh-llm';
+import type { PhysicalRoute, Role } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import { type SessionBinding } from './bindings.js';
+export interface ModelControl {
+    schemaVersion: 1;
+    sessionId: string;
+    profileDigest: string;
+    epoch: number;
+    recoveryEpoch?: number;
+    /** Lead-cleared recoverable Worker waits for the current task (bounded). */
+    leadRecoveries?: {
+        taskId: string;
+        count: number;
+    };
+    routes: Record<Role, PhysicalRoute>;
+    waits: Partial<Record<Role, {
+        taskId: string;
+        code: string;
+        at: string;
+        retryNotBefore?: string;
+        quotaResetAt: null;
+    }>>;
+    operation?: {
+        id: string;
+        taskId: string;
+        state: 'prepared' | 'dispatching' | 'delivered' | 'failed';
+        message?: UserMessage;
+        error?: string;
+    };
+    schedule?: {
+        id: string;
+        taskId: string;
+        epoch: number;
+        dueAt: string;
+        userSeq: number;
+        state: 'scheduled' | 'cancelled' | 'fired' | 'failed';
+        reason?: string;
+    };
+}
+export interface ControlView extends ModelControl {
+    revision: number;
+}
+export declare function readModelControl(store: SqliteFusionStore, binding: SessionBinding): ControlView | undefined;
+interface Callbacks {
+    owner(agent: Agent): {
+        binding: SessionBinding;
+        role: Role;
+    } | undefined;
+    resolve(sessionId: string): Promise<Agent>;
+    pause(agent: Agent): Promise<void>;
+    resume(agent: Agent): Promise<void>;
+    settled(binding: SessionBinding): boolean;
+    stopAuxiliary(binding: SessionBinding): void;
+}
+/** Durable local controls. No provider polling, synthetic user identity, or silent routing fallback. */
+export declare class NativeModelControl {
+    #private;
+    readonly ctx: Context;
+    readonly store: SqliteFusionStore;
+    readonly callbacks: Callbacks;
+    constructor(ctx: Context, store: SqliteFusionStore, callbacks: Callbacks);
+    reset(binding: SessionBinding): void;
+    write(view: ControlView): number;
+    route(binding: SessionBinding, role: Role): PhysicalRoute;
+    waiting(binding: SessionBinding, role: Role): {
+        taskId: string;
+        code: string;
+        at: string;
+        retryNotBefore?: string;
+        quotaResetAt: null;
+    } | undefined;
+    /**
+     * Clear a role wait the Lead can resolve itself by sending a new instruction: a missing report or
+     * transition (WORKFLOW_INCOMPLETE), a repeated unchanged result (NO_PROGRESS) or an unclassified
+     * error (UNKNOWN). At most LEAD_RECOVERIES per task; quota and credential stops are never cleared here.
+     */
+    leadRecover(binding: SessionBinding, role: Role): boolean;
+    /** The role stalled again after the Lead already redirected it LEAD_RECOVERIES times this task. */
+    recoveriesExhausted(binding: SessionBinding, role: Role): boolean;
+    blocked(binding: SessionBinding, role: Role): string | undefined;
+    reconcileDelivery(agent: Agent, binding: SessionBinding, evidenceId: string): void;
+    failure(binding: SessionBinding, role: Role, failure: LlmFailure): void;
+    private require;
+    private userSeq;
+    cancel(binding: SessionBinding, reason?: string): void;
+    schedule(sessionId: string, taskId: string, revision: number, dueAt: string): Promise<void>;
+    continue(sessionId: string, taskId: string, revision: number, change?: {
+        role: Role;
+        route: PhysicalRoute;
+    }, scheduledId?: string): Promise<void>;
+    private runContinue;
+    private clearTimer;
+    private arm;
+    close(): Promise<void>;
+}
+export {};

package/lib/types/host/native-on-demand-context.d.ts

@@ -0,0 +1,39 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { Role } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { SessionBinding } from './bindings.js';
+import type { NativeTaskContext } from './native-task-context.js';
+/** No per-step snapshots. Emit a compact pointer only after loss of context. */
+export declare class NativeOnDemandContext {
+    #private;
+    readonly store: SqliteFusionStore;
+    readonly facts: NativeTaskContext;
+    constructor(store: SqliteFusionStore, facts: NativeTaskContext);
+    private id;
+    message(agent: Agent, binding: SessionBinding, role: Role): ({
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        source: {
+            kind: "plugin:dsh-fusion";
+            form: "snapshot";
+            sections: {
+                name: string;
+                text: string;
+            }[];
+        };
+    } & Pick<import("@deepseek-ai/dsh-llm").UserMessage, "role" | "id">) | undefined;
+    blocked(agent: Agent, binding: SessionBinding): string | undefined;
+    read(agent: Agent, binding: SessionBinding, role: Role, offset?: number, limit?: number): {
+        bytes: number;
+        encoding: string;
+        offsetUnit: string;
+        offset: number;
+        totalCharacters: number;
+        text: string;
+        truncated: boolean;
+        nextOffset: number | null;
+        taskId: import("../contracts.js").TaskId;
+    };
+}

package/lib/types/host/native-request.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { GenerateOptions } from '@deepseek-ai/dsh-llm';
+/** Auxiliary native calls may carry a session without an active Agent turn. */
+export declare function nativeRequestAgent(ctx: Context, request: GenerateOptions): Agent | undefined;

package/lib/types/host/native-review.d.ts

@@ -0,0 +1,11 @@
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { ReviewTicket, TaskId } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+/** Capture before the Lead request starts; later tool callbacks cannot bind to a newer report. */
+export declare function captureNativeReviewRequest(store: SqliteFusionStore, agent: Agent, turn: number, step: number, ticket: ReviewTicket): void;
+export declare function nativeReviewProof(store: SqliteFusionStore, taskId: TaskId, exec: ToolExecution): {
+    ticket: Readonly<ReviewTicket>;
+    terminalEvidenceRef: string;
+    finishReason: 'tool_calls' | 'stop';
+};

package/lib/types/host/native-role-sandbox.d.ts

@@ -0,0 +1,49 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { Role } from '../contracts.js';
+import type { SqliteFusionStore } from '../task/sqlite-store.js';
+import type { SessionBinding } from './bindings.js';
+type Mode = 'read-only' | 'workspace-write' | 'danger-full-access';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        'sandbox/mode': {
+            mode: Mode;
+            source?: 'delegation';
+        };
+    }
+}
+export declare const roleSeparated: (binding: SessionBinding) => boolean;
+/**
+ * Role separation enforced below the prompt: the Lead's session runs under the
+ * Host's own read-only sandbox (bash and filesystem are refused by the OS
+ * backend), while the Sidekick keeps the mode the user chose. The plugin never
+ * widens a mode: the Sidekick gets exactly the user's mode, and leaving Fusion
+ * restores it on the conversation. Only public session events are written.
+ */
+export declare class NativeRoleSandbox {
+    #private;
+    readonly ctx: Context;
+    readonly store: SqliteFusionStore;
+    readonly binding: (sessionId: string) => SessionBinding | undefined;
+    constructor(ctx: Context, store: SqliteFusionStore, binding: (sessionId: string) => SessionBinding | undefined);
+    /**
+     * Called before every model request of an enforced-v3 role. `writer` is true only while the Lead holds the
+     * write lease through a Host-unlocked takeover; it then runs under the user's own mode, like the Sidekick.
+     */
+    ensure(agent: Agent, binding: SessionBinding, role: Role, writer?: boolean): void;
+    /**
+     * Frozen acceptance checks are plugin-issued and nested in a Lead tool call, so
+     * they would inherit the Lead's read-only session. They run under the user's
+     * mode; the Lead's own shell stays refused meanwhile because leadShellProblem
+     * requires an actual read-only resolution at execution time.
+     */
+    whileChecking<T>(agent: Agent, binding: SessionBinding, run: () => Promise<T>): Promise<T>;
+    /** A Lead shell is allowed only when the Host will actually run it read-only and without escalation. */
+    leadShellProblem(exec: Readonly<ToolExecution>): string | undefined;
+    /** Put the user's own mode back when the conversation leaves Fusion. */
+    restore(agent: Agent): void;
+    /** A mode switch the user makes while Fusion is selected becomes the Sidekick's mode; the Lead stays read-only. */
+    install(): () => void;
+}
+export {};

package/lib/types/host/native-scopes.d.ts

@@ -0,0 +1,49 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import type { UserMessage } from '@deepseek-ai/dsh-llm';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { PhysicalRoute, Role } from '../contracts.js';
+import type { SessionBinding } from './bindings.js';
+export interface FusionScopeCallbacks {
+    route?(binding: SessionBinding, role: Role): PhysicalRoute;
+    beforeTurn?(agent: Agent, binding: SessionBinding, role: Role, turn: number): SessionBinding;
+    taskContext?(agent: Agent, binding: SessionBinding, role: Role): UserMessage | undefined;
+    beforeStep?(agent: Agent, binding: SessionBinding, role: Role): void;
+    projectMessage?(agent: Agent, binding: SessionBinding, role: Role, message: UserMessage): UserMessage;
+    /** All independent pause, budget, recovery and unknown-effect gates are checked here. */
+    canAccess?(agent: Agent, binding: SessionBinding, role: Role): string | undefined;
+    /** Shared gates plus limits that apply only to admitting a new generation. */
+    prepareRequest?(agent: Agent, binding: SessionBinding, role: Role, signal: AbortSignal): Promise<void>;
+    canRequest(agent: Agent, binding: SessionBinding, role: Role): string | undefined;
+    canExecute(exec: Readonly<ToolExecution>, binding: SessionBinding, role: Role): string | undefined;
+    beforeRequest(agent: Agent, turn: number, step: number, binding: SessionBinding, role: Role): void;
+    /** Disclosed context window for this physical model, read when the request is built. */
+    modelLimits?(provider: string, model: string): Promise<{
+        contextWindow: number;
+        defaultMaxTokens?: number;
+        testedOutputCap?: number;
+    }>;
+    /** Read-stage tools, presented natively. Undefined restores the native composition. */
+    readOnlyTools?(agent: Agent, binding: SessionBinding, role: Role): readonly string[] | undefined;
+    installTools(scope: Context, agent: Agent, binding: SessionBinding, role: Role): readonly (() => void)[];
+}
+/** Physical routing, prompt and tools live in the exact native Agent scope. */
+export declare class NativeFusionScopes {
+    #private;
+    private readonly callbacks;
+    constructor(callbacks: FusionScopeCallbacks);
+    get(agent: Agent): {
+        binding: SessionBinding;
+        role: Role;
+    } | undefined;
+    assertReady(agent: Agent): void;
+    install(agent: Agent, binding: SessionBinding, role: Role): void;
+    /** Refresh at the persisted state transition, before native prompt providers run. */
+    refreshTools(agent: Agent): void;
+    /**
+     * Caller owns quiescence and the original session-controller model selection.
+     * Removing these listeners reveals that existing selection; it does not mutate
+     * a request header or fabricate a replacement global default.
+     */
+    detach(agent: Agent): void;
+}

package/lib/types/host/native-selection.d.ts

@@ -0,0 +1,29 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmResolvedModelInfo, ModelModality, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { PhysicalRoute } from '../contracts.js';
+import { FUSION_MODEL, FUSION_PROVIDER, isFusionSelection } from '../identity.js';
+import type { ResolvedProfile } from '../profile/resolve.js';
+import type { FusionCoordinator } from './coordinator.js';
+export { FUSION_MODEL, FUSION_PROVIDER, isFusionSelection };
+/** Resolves the configured Lead's declared input modalities; undefined means unconfigured or unverifiable. */
+export type LeadInputModalities = () => Promise<readonly ModelModality[] | undefined>;
+/** Catalog-only local adapter; the native request is physically routed before dispatch. */
+export declare class FusionCatalogAdapter extends LlmAdapter {
+    private readonly leadInputModalities?;
+    constructor(leadInputModalities?: LeadInputModalities | undefined);
+    providerInfo(provider: string): {
+        id: string;
+        name: string;
+    };
+    listModels(provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(provider: string, model: string): Promise<LlmResolvedModelInfo>;
+    stream(_options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+/** Public native lifecycle integration. No model-menu replacement or Host patch. */
+export declare function installNativeFusionSelection(ctx: Context, input: {
+    coordinator(): FusionCoordinator | undefined;
+    profile(): ResolvedProfile | undefined;
+    selection(agent: Agent): PhysicalRoute | undefined;
+}): () => void;