@deepseek-harness-tui/dsh-tui 0.14.0 → 0.15.0

package/lib/types/dsh-adapter/fresh-agent.js

@@ -0,0 +1,221 @@
+import { Context } from '@deepseek-ai/cordis';
+import { snapshotLiveSessionEvents } from './compat/liveSession.js';
+import { concreteService } from './host-access.js';
+const captures = new WeakMap();
+/** Capture only this factory's public write handle; concurrent creates share one tap. */
+function captureWriter(source, id, receive) {
+    let capture = captures.get(source);
+    if (capture === undefined) {
+        const descriptor = Object.getOwnPropertyDescriptor(source, 'create');
+        const create = source.create;
+        const receivers = new Map();
+        const tapped = async function (header, options) {
+            const writer = await create.call(this, header, options);
+            receivers.get(writer.id)?.(writer);
+            return writer;
+        };
+        source.create = tapped;
+        capture = {
+            receivers,
+            restore() {
+                if (source.create === tapped) {
+                    if (descriptor === undefined)
+                        delete source.create;
+                    else
+                        Object.defineProperty(source, 'create', descriptor);
+                }
+                captures.delete(source);
+            },
+        };
+        captures.set(source, capture);
+    }
+    if (capture.receivers.has(id))
+        throw new Error(`dsh-tui: fresh session "${id}" is already being created`);
+    capture.receivers.set(id, receive);
+    return () => {
+        capture.receivers.delete(id);
+        if (capture.receivers.size === 0)
+            capture.restore();
+    };
+}
+/** Policy facts held in memory until the session has further activity. */
+export const INITIAL_POLICY_EVENTS = new Set(['permission/preset', 'sandbox/mode', 'approval/policy', 'plan/mode']);
+/** The command envelope a session-policy switch runs through. */
+const POLICY_ACTIVITY_EVENTS = new Set(['command/run', 'command/done']);
+/** Source-less legacy messages and explicit user messages count as human input. */
+export function isHumanSource(source) {
+    if (source === undefined || source === null)
+        return true;
+    if (typeof source !== 'object')
+        return false;
+    return source['kind'] === 'user';
+}
+/** Policy commands also emit command envelopes and nonhuman inbox notices. */
+export function isPolicyPlaneActivity(event) {
+    if (INITIAL_POLICY_EVENTS.has(event.type) || POLICY_ACTIVITY_EVENTS.has(event.type))
+        return true;
+    if (event.type !== 'agent/inbox/spliced')
+        return false;
+    const inserted = event.data?.inserted;
+    if (!Array.isArray(inserted))
+        return false;
+    for (const message of inserted) {
+        if (message === null || typeof message !== 'object')
+            continue;
+        const entry = message;
+        if (entry['role'] === 'user' && isHumanSource(entry['source']))
+            return false;
+    }
+    return true;
+}
+const unstoredSessions = new WeakSet();
+/** Initialization-only fresh session with no persistence requested yet. */
+export function isUnstoredFreshSession(session) {
+    return session !== undefined && unstoredSessions.has(session);
+}
+/** Keep initial policy facts live, but route them to JSONL only with subsequent work. */
+function deferInitialPolicy(ctx, session, writer, source) {
+    if (session.seq !== 0)
+        return;
+    const providerFiber = concreteService(source.ctx.fiber);
+    const descriptor = Object.getOwnPropertyDescriptor(session, Context.filter);
+    const originalFilter = session[Context.filter];
+    const flush = writer.flush;
+    const close = writer.close;
+    let deferred = true;
+    let started = false;
+    let failed = false;
+    let storedCount = 0;
+    let draining;
+    const start = () => {
+        started = true;
+        unstoredSessions.delete(session);
+    };
+    const filter = (listener) => (originalFilter?.call(session, listener) ?? true) &&
+        (!deferred || concreteService(listener.fiber) !== providerFiber);
+    let stopEvents;
+    let stopFlush;
+    const release = () => {
+        deferred = false;
+        stopEvents?.();
+        stopFlush?.();
+        if (session[Context.filter] === filter) {
+            if (descriptor === undefined)
+                delete session[Context.filter];
+            else
+                Object.defineProperty(session, Context.filter, descriptor);
+        }
+        if (writer.flush === guardedFlush)
+            writer.flush = flush;
+        if (writer.close === guardedClose)
+            writer.close = close;
+    };
+    // Live routing stays paused throughout the asynchronous handoff. Any events
+    // arriving during append are part of the next suffix, never duplicated by
+    // the backend's own router. A failed suffix remains available for a flush retry.
+    const drain = () => draining ??= (async () => {
+        while (deferred) {
+            const events = snapshotLiveSessionEvents(session);
+            const suffix = events.slice(storedCount);
+            if (suffix.length === 0) {
+                release();
+                break;
+            }
+            await writer.append(suffix);
+            storedCount = events.length;
+        }
+    })().finally(() => { draining = undefined; });
+    const guardedFlush = async () => {
+        // Projection checkpoints flush on creation; only later activity publishes the session.
+        if (!started)
+            return;
+        await drain();
+        await flush.call(writer);
+    };
+    const guardedClose = async () => {
+        // The provider can unload before the Agent scope. Its handle close must
+        // wait for the suffix still being handed off, while idle policy is discarded.
+        const failures = [];
+        try {
+            if (started)
+                await drain();
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        try {
+            await close.call(writer);
+        }
+        catch (error) {
+            failures.push(error);
+        }
+        finally {
+            release();
+        }
+        if (failures.length === 1)
+            throw failures[0];
+        if (failures.length > 1)
+            throw new AggregateError(failures, `dsh-tui: fresh session "${session.id}" close failed`);
+    };
+    ctx.effect(() => {
+        unstoredSessions.add(session);
+        session[Context.filter] = filter;
+        writer.flush = guardedFlush;
+        writer.close = guardedClose;
+        return async () => {
+            try {
+                if (started)
+                    await drain();
+            }
+            finally {
+                release();
+            }
+        };
+    }, 'dsh-tui fresh session policy');
+    stopEvents = ctx.on('session/event', (subject, event) => {
+        if (subject !== session || (!started && isPolicyPlaneActivity(event)))
+            return;
+        start();
+        if (failed || draining !== undefined)
+            return;
+        void drain().catch((error) => {
+            failed = true;
+            ctx.logger.warn(`dsh-tui: fresh session "${session.id}" write failed (events retained for flush): ${String(error)}`);
+        });
+    }, { prepend: true });
+    stopFlush = ctx.on('session/flush', subject => subject === session ? writer.flush() : undefined);
+}
+/**
+ * Startup and `/new` use an unseeded DSH session. Permission initialization
+ * alone must not publish a stored conversation; all facts still belong to
+ * the real Session, and the official JSONL writer owns their eventual storage.
+ */
+export async function createFreshAgent(ctx, agents, options) {
+    const service = ctx.get('sessionPersistence');
+    // Legacy id-addressed stores and custom providers retain their own routing.
+    if (service?.name !== 'session-persistence-jsonl' || typeof service.open !== 'function')
+        return agents.create(options);
+    const source = concreteService(service);
+    let writer;
+    const stopCapture = captureWriter(source, String(options.sessionId), value => { writer = value; });
+    const setup = async (agentCtx, agent) => {
+        const commit = await options.setup?.(agentCtx, agent);
+        const defer = () => {
+            if (writer !== undefined)
+                deferInitialPolicy(agentCtx, agent.session, writer, source);
+        };
+        if (commit === undefined) {
+            defer();
+            return;
+        }
+        // Setup history belongs to the factory's pre-publication append. Install
+        // the gate only after the original commit has finished composing it.
+        return { commit() { commit.commit(); defer(); } };
+    };
+    try {
+        return await agents.create({ ...options, setup });
+    }
+    finally {
+        stopCapture();
+    }
+}

package/lib/types/dsh-adapter/host-access.d.ts

@@ -1,4 +1,18 @@
 import { Context } from '@deepseek-ai/cordis';
+/**
+ * Hold the root-capability guard back on `root` until the returned release
+ * runs. The entry mounts the TUI before composing the profile into the same
+ * root, and DSH's plugins use root capabilities while they activate, which
+ * the guard would refuse. Fiber tracking starts at once either way.
+ */
+export declare function deferRootCapabilityGuard(root: Context): () => void;
+/**
+ * The composition of a deferred root starts: the guard now arrives with the
+ * first TUI row's activation, as on the `dsh --profile` path, so every row
+ * after it (third-party ones included) is guarded. The release still installs
+ * it once the composition settles if no TUI row activated.
+ */
+export declare function armRootCapabilityGuard(root: Context): void;
 /** Host-only escape hatch for process teardown paths that intentionally act on
  * the composition root while running from a host plugin callback. This module
  * is internal and is not part of the public plugin package surface. */
@@ -14,7 +28,8 @@ export declare function activationFiber(ctx: Context): object | undefined;
 export declare function activationContext(ctx: Context): Context | undefined;
 /** Resolve a service's composition root once.  Service methods are invoked
  * through caller-bound Cordis proxies; keeping this root in host state avoids
- * resolving sibling services through an attacker-provided caller shadow. */
+ * resolving sibling services through an attacker-provided caller shadow.
+ * Also the first TUI row's activation signal for an armed deferred guard. */
 export declare function compositionRoot(ctx: Context): Context;
 /** Recover the composition root that owns a traceable service. Cordis stores
  * the provider context on the concrete Service instance; callers may reach

package/lib/types/dsh-adapter/host-access.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host-access.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/host-access.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAS,MAAM,qBAAqB,CAAA;AAoSpD;;uEAEuE;AACvE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAE9D;AA8FD,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAe/D;AAED;0EAC0E;AAC1E,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,OAAO,EACvB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,OAAO,KAAK,IAAI,GAC9C,OAAO,CA2BT;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMhE;AAED;+EAC+E;AAC/E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAInE;AAED;;4EAE4E;AAC5E,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAwDrD;AAuDD;;;4EAG4E;AAC5E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAO3E;AAED;;;iEAGiE;AACjE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAehH;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAmBlG"}
+{"version":3,"file":"host-access.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/host-access.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAS,MAAM,qBAAqB,CAAA;AAkLpD;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,IAAI,CAGlE;AAWD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE1D;AAkID;;uEAEuE;AACvE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,CAE9D;AA8FD,wBAAgB,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,CAe/D;AAED;0EAC0E;AAC1E,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,OAAO,EACvB,YAAY,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,OAAO,KAAK,IAAI,GAC9C,OAAO,CA2BT;AAED,yEAAyE;AACzE,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAMhE;AAED;+EAC+E;AAC/E,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,GAAG,SAAS,CAInE;AAED;;;6EAG6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAIrD;AAiHD;;;4EAG4E;AAC5E,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAO3E;AAED;;;iEAGiE;AACjE,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAehH;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAmBlG"}

package/lib/types/dsh-adapter/host-access.js

@@ -176,7 +176,52 @@ function trackCompositionRoot(root) {
         // Minimal embedders may expose Context without an event helper. The
         // shape/lifecycle checks below remain as a conservative fallback.
     }
-    guardRootCapabilities(root);
+    if (!deferredGuardRoots.has(root))
+        guardRootCapabilities(root);
+}
+/** Roots whose capability guard waits for their composition (below). */
+const deferredGuardRoots = new WeakSet();
+/**
+ * Hold the root-capability guard back on `root` until the returned release
+ * runs. The entry mounts the TUI before composing the profile into the same
+ * root, and DSH's plugins use root capabilities while they activate, which
+ * the guard would refuse. Fiber tracking starts at once either way.
+ */
+export function deferRootCapabilityGuard(root) {
+    deferredGuardRoots.add(root);
+    return () => releaseDeferredGuard(root);
+}
+function releaseDeferredGuard(root) {
+    armedGuardRoots.delete(root);
+    if (!deferredGuardRoots.delete(root))
+        return;
+    if (trackedRoots.has(root))
+        guardRootCapabilities(root);
+}
+/** Deferred roots whose guard the first TUI row activation installs (below). */
+const armedGuardRoots = new WeakSet();
+/**
+ * The composition of a deferred root starts: the guard now arrives with the
+ * first TUI row's activation, as on the `dsh --profile` path, so every row
+ * after it (third-party ones included) is guarded. The release still installs
+ * it once the composition settles if no TUI row activated.
+ */
+export function armRootCapabilityGuard(root) {
+    if (deferredGuardRoots.has(root))
+        armedGuardRoots.add(root);
+}
+/** A plugin activation of `root` (not the root's own, not host code) is
+ * resolving its composition through the TUI's host code: a TUI row. */
+function noteTuiRowActivation(root) {
+    if (!armedGuardRoots.has(root))
+        return;
+    if (hostCapabilityStorage.getStore() === true)
+        return;
+    const token = activationStorage.getStore();
+    const rootFiber = rootFibers.get(root);
+    if (token === undefined || token.root !== root || rootFiber === token.fiber)
+        return;
+    releaseDeferredGuard(root);
 }
 function invalidateActivation(fiber) {
     activationGenerations.set(fiber, (activationGenerations.get(fiber) ?? 0) + 1);
@@ -464,8 +509,14 @@ export function activationContext(ctx) {
 }
 /** Resolve a service's composition root once.  Service methods are invoked
  * through caller-bound Cordis proxies; keeping this root in host state avoids
- * resolving sibling services through an attacker-provided caller shadow. */
+ * resolving sibling services through an attacker-provided caller shadow.
+ * Also the first TUI row's activation signal for an armed deferred guard. */
 export function compositionRoot(ctx) {
+    const root = resolveCompositionRoot(ctx);
+    noteTuiRowActivation(root);
+    return root;
+}
+function resolveCompositionRoot(ctx) {
     try {
         const knownFiber = contextFibers.get(ctx);
         const trustedRoot = knownFiber === undefined ? undefined : fiberRoots.get(knownFiber);

package/lib/types/dsh-adapter/host-contract.d.ts

@@ -0,0 +1,103 @@
+/**
+ * The host contract of this package's entry (ADAPTER.md): what the entry
+ * loads from the installed `dsh` and what it reproduces. Read by
+ * ./host-dsh.ts, ./contract.ts and scripts/verify-host-contract.ts.
+ * Pure data, no imports.
+ */
+/** The host CLI package whose installation the entry loads. */
+export declare const HOST_PACKAGE = "@deepseek-ai/dsh";
+/** The host line the reproduced pieces were checked against (host-replica.snapshot.json). */
+export declare const HOST_REPLICA_VERSION = "0.2.0-rc.2";
+/** Where the entry resolves a host module from. */
+export type HostModuleVia = 
+/** The host package's own `createRequire` (its nested node_modules). */
+'host'
+/** `@deepseek-ai/dsh-app-boot`'s `createRequire`: the instance app-boot itself uses. */
+ | 'app-boot';
+export interface HostModuleSpec {
+    /** The `HostDsh` field it fills. */
+    readonly key: string;
+    readonly specifier: string;
+    readonly via: HostModuleVia;
+    /** Every export the entry reads; the probe requires each to be defined. */
+    readonly exports: readonly string[];
+}
+/** The host modules the entry loads, all from one installation, in load order. */
+export declare const HOST_MODULES: readonly [{
+    readonly key: "cordis";
+    readonly specifier: "@deepseek-ai/cordis";
+    readonly via: "host";
+    readonly exports: readonly ["Context"];
+}, {
+    readonly key: "appBoot";
+    readonly specifier: "@deepseek-ai/dsh-app-boot";
+    readonly via: "host";
+    readonly exports: readonly ["loadLayeredEnv", "createRuntimeResolution", "PluginPackages", "installFailLoud", "readProfilePatches", "mountRootInclude", "auditStartupEntries", "StartupError", "getDshRuntimeVersion"];
+}, {
+    readonly key: "loader";
+    readonly specifier: "@deepseek-ai/cordis-plugin-loader";
+    readonly via: "app-boot";
+    readonly exports: readonly ["default"];
+}, {
+    readonly key: "homePaths";
+    readonly specifier: "@deepseek-ai/dsh-home-paths";
+    readonly via: "app-boot";
+    readonly exports: readonly ["dshHomePath", "resolveDshHome"];
+}, {
+    readonly key: "launchEnvironment";
+    readonly specifier: "@deepseek-ai/dsh-launch-environment";
+    readonly via: "host";
+    readonly exports: readonly ["DSH_LAUNCH_ENVIRONMENT_KEY"];
+}, {
+    readonly key: "cmdline";
+    readonly specifier: "@deepseek-ai/dsh-cmdline";
+    readonly via: "host";
+    readonly exports: readonly ["provideCmdline"];
+}, {
+    readonly key: "profileBoot";
+    readonly specifier: "@deepseek-ai/dsh/profile-boot";
+    readonly via: "host";
+    readonly exports: readonly ["prepareProfile", "INSTALL_ANCHOR", "PROFILE_ROOT_FILENAME"];
+}, {
+    readonly key: "httpProxy";
+    readonly specifier: "@deepseek-ai/dsh-http-proxy";
+    readonly via: "host";
+    readonly exports: readonly ["installProxyFromEnvironment"];
+}];
+/**
+ * The packages ./host-dsh.ts takes types from (`import type` only); each is
+ * an optional peer + dev dependency and blessed. Not the host package itself
+ * (its dependency tree is the whole CLI).
+ */
+export declare const HOST_TYPE_PACKAGES: readonly ["@deepseek-ai/dsh-app-boot", "@deepseek-ai/dsh-cmdline", "@deepseek-ai/dsh-home-paths", "@deepseek-ai/dsh-http-proxy", "@deepseek-ai/dsh-launch-environment"];
+/**
+ * The packages the adapter takes types from for host services it reaches
+ * through `ctx` rather than through the entry's host boot; each is an
+ * optional peer + dev dependency and blessed. Unlike {@link HOST_TYPE_PACKAGES}
+ * these are read by the running profile's own composition, and the host CLI
+ * supplies the package (a profile has no copy) — so absence at run time is
+ * valid and the consumer degrades instead of failing.
+ */
+export declare const ADAPTER_TYPE_PACKAGES: readonly ["@deepseek-ai/dsh-plugin-manager"];
+/** One upstream body the entry reproduces (fingerprinted by verify:contract). */
+export interface HostReplica {
+    readonly id: string;
+    /** The package holding the upstream body; its `lib/*.js` are searched. */
+    readonly package: string;
+    /** A top-level `function` (sync or async) or `const` in that package's lib. */
+    readonly symbol: string;
+    readonly kind: 'function' | 'const';
+    /** What in ./host-dsh.ts reproduces it, and how far. */
+    readonly local: string;
+}
+/**
+ * The reproduced upstream pieces. A changed fingerprint means: re-read the
+ * upstream body against `local`, carry the change over, regenerate the snapshot.
+ */
+export declare const HOST_REPLICAS: readonly HostReplica[];
+/** Where the entry deliberately differs from `dsh --profile`. Documentation only; ADAPTER.md points here. */
+export declare const HOST_DEVIATIONS: readonly {
+    readonly id: string;
+    readonly what: string;
+}[];
+//# sourceMappingURL=host-contract.d.ts.map

package/lib/types/dsh-adapter/host-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-contract.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/host-contract.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,+DAA+D;AAC/D,eAAO,MAAM,YAAY,qBAAqB,CAAA;AAE9C,6FAA6F;AAC7F,eAAO,MAAM,oBAAoB,eAAe,CAAA;AAEhD,mDAAmD;AACnD,MAAM,MAAM,aAAa;AACvB,wEAAwE;AACtE,MAAM;AACR,wFAAwF;GACtF,UAAU,CAAA;AAEd,MAAM,WAAW,cAAc;IAC7B,oCAAoC;IACpC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAA;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAED,kFAAkF;AAClF,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAeqB,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yKAMrB,CAAA;AAEV;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,8CAExB,CAAA;AAEV,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAA;IACnC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,WAAW,EAS/C,CAAA;AAED,6GAA6G;AAC7G,eAAO,MAAM,eAAe,EAAE,SAAS;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAUpF,CAAA"}

package/lib/types/dsh-adapter/host-contract.js

@@ -0,0 +1,76 @@
+/**
+ * The host contract of this package's entry (ADAPTER.md): what the entry
+ * loads from the installed `dsh` and what it reproduces. Read by
+ * ./host-dsh.ts, ./contract.ts and scripts/verify-host-contract.ts.
+ * Pure data, no imports.
+ */
+/** The host CLI package whose installation the entry loads. */
+export const HOST_PACKAGE = '@deepseek-ai/dsh';
+/** The host line the reproduced pieces were checked against (host-replica.snapshot.json). */
+export const HOST_REPLICA_VERSION = '0.2.0-rc.2';
+/** The host modules the entry loads, all from one installation, in load order. */
+export const HOST_MODULES = [
+    { key: 'cordis', specifier: '@deepseek-ai/cordis', via: 'host', exports: ['Context'] },
+    {
+        key: 'appBoot',
+        specifier: '@deepseek-ai/dsh-app-boot',
+        via: 'host',
+        exports: ['loadLayeredEnv', 'createRuntimeResolution', 'PluginPackages', 'installFailLoud', 'readProfilePatches', 'mountRootInclude', 'auditStartupEntries', 'StartupError', 'getDshRuntimeVersion'],
+    },
+    // The Loader's builtins must be the instance app-boot mounts includes with.
+    { key: 'loader', specifier: '@deepseek-ai/cordis-plugin-loader', via: 'app-boot', exports: ['default'] },
+    { key: 'homePaths', specifier: '@deepseek-ai/dsh-home-paths', via: 'app-boot', exports: ['dshHomePath', 'resolveDshHome'] },
+    { key: 'launchEnvironment', specifier: '@deepseek-ai/dsh-launch-environment', via: 'host', exports: ['DSH_LAUNCH_ENVIRONMENT_KEY'] },
+    { key: 'cmdline', specifier: '@deepseek-ai/dsh-cmdline', via: 'host', exports: ['provideCmdline'] },
+    { key: 'profileBoot', specifier: '@deepseek-ai/dsh/profile-boot', via: 'host', exports: ['prepareProfile', 'INSTALL_ANCHOR', 'PROFILE_ROOT_FILENAME'] },
+    { key: 'httpProxy', specifier: '@deepseek-ai/dsh-http-proxy', via: 'host', exports: ['installProxyFromEnvironment'] },
+];
+/**
+ * The packages ./host-dsh.ts takes types from (`import type` only); each is
+ * an optional peer + dev dependency and blessed. Not the host package itself
+ * (its dependency tree is the whole CLI).
+ */
+export const HOST_TYPE_PACKAGES = [
+    '@deepseek-ai/dsh-app-boot',
+    '@deepseek-ai/dsh-cmdline',
+    '@deepseek-ai/dsh-home-paths',
+    '@deepseek-ai/dsh-http-proxy',
+    '@deepseek-ai/dsh-launch-environment',
+];
+/**
+ * The packages the adapter takes types from for host services it reaches
+ * through `ctx` rather than through the entry's host boot; each is an
+ * optional peer + dev dependency and blessed. Unlike {@link HOST_TYPE_PACKAGES}
+ * these are read by the running profile's own composition, and the host CLI
+ * supplies the package (a profile has no copy) — so absence at run time is
+ * valid and the consumer degrades instead of failing.
+ */
+export const ADAPTER_TYPE_PACKAGES = [
+    '@deepseek-ai/dsh-plugin-manager',
+];
+/**
+ * The reproduced upstream pieces. A changed fingerprint means: re-read the
+ * upstream body against `local`, carry the change over, regenerate the snapshot.
+ */
+export const HOST_REPLICAS = [
+    { id: 'process-shutdown', package: HOST_PACKAGE, symbol: 'createProcessShutdown', kind: 'function', local: 'createProcessShutdown: the `shutdown` half only (`interrupt` is replaced by process-exit.ts, see HOST_DEVIATIONS)' },
+    { id: 'process-shutdown-timeout', package: HOST_PACKAGE, symbol: 'PROCESS_SHUTDOWN_TIMEOUT_MS', kind: 'const', local: 'process-exit.ts PROCESS_SHUTDOWN_TIMEOUT_MS' },
+    { id: 'app-ready', package: HOST_PACKAGE, symbol: 'createAppReady', kind: 'function', local: 'createAppReady' },
+    { id: 'compose-profile', package: HOST_PACKAGE, symbol: 'composeProfile', kind: 'function', local: 'prepareHostRoot steps 1–2 (no overlays, no resolvedProfile)' },
+    { id: 'run-profile', package: HOST_PACKAGE, symbol: 'runProfile', kind: 'function', local: 'prepareHostRoot steps 3, 5–7 (proxy, fail-loud, profileContext, launch environment, PluginPackages, provideCmdline) and HostRoot.compose\'s appReady.commit' },
+    { id: 'boot', package: '@deepseek-ai/dsh-app-boot', symbol: 'boot', kind: 'function', local: 'prepareHostRoot step 4 (baseUrl, dshHomePath, internal/update, Loader) and HostRoot.compose (startup-log exporter, mountRootInclude, loader.await, auditStartupEntries, StartupError.startup)' },
+    { id: 'startup-report', package: HOST_PACKAGE, symbol: 'reportStartupFailure', kind: 'function', local: 'writeStartupReport: the file half' },
+    { id: 'run-cli', package: HOST_PACKAGE, symbol: 'runCli', kind: 'function', local: 'prepareHostRoot\'s loadLayeredEnv call before the profile; the StartupError-only report' },
+];
+/** Where the entry deliberately differs from `dsh --profile`. Documentation only; ADAPTER.md points here. */
+export const HOST_DEVIATIONS = [
+    { id: 'no-interrupt', what: 'runProfile\'s SIGTERM/SIGINT handlers and createProcessShutdown().interrupt are not reproduced: the entry owns SIGTERM/SIGHUP/SIGINT (process-exit.ts installEntrySignals) and ends by the signal after the TUI\'s exit funnel, where interrupt exits 0 (TERM) / 130 (INT) — the launcher reads a numeric 130 as a crash (verify-entry-process-exit)' },
+    { id: 'exit-seam', what: 'ctx.appExit (provideCmdline exit) goes to the TUI\'s exit funnel through ProcessExitSeam first, and to the reproduced shutdown only when the funnel refuses (prepareHostRoot exitSeam)' },
+    { id: 'fail-loud-removable', what: 'installFailLoud\'s uninstaller is kept and called once apply() returned and processGuardActive() (host-entry.ts): from then on the TUI\'s process guard is the single owner of a fatal error; DSH_TUI_NO_185_PROCESS_GUARD=1 keeps fail-loud (verify-entry-process-exit)' },
+    { id: 'startup-report-always', what: 'bin.js saves a report for a StartupError only and lets other startup errors crash; the entry saves one for every composition failure (HostComposeError carries the path) because the screen stays up' },
+    { id: 'startup-report-no-terminal', what: 'reportStartupFailure\'s terminal half is not reproduced: the screen is up, the failure row names the report' },
+    { id: 'no-overlays', what: '--patch overlays, --from-default-profile and resolvedProfile are not reproduced (the launcher passes none)' },
+    { id: 'defer-root-guard', what: 'deferRootCapabilityGuard(root) (host-access.ts) keeps the TUI\'s root-capability guard off while the screen mounts; armRootCapabilityGuard then lets the first TUI row activation install it, as on the profile path, and the composition\'s settling installs it if no TUI row activated' },
+    { id: 'report-exclude-network', what: 'host-entry.ts sets process.report.excludeNetwork = true for the process: DSH\'s flock libc probe (process.report.getReport) otherwise blocked ~10s on reverse lookups of sockets the mounted screen already opened' },
+    { id: 'hijack-before-tui', what: 'the host\'s PluginPackages resolution is installed before any TUI module loads, for both kernels; runProfile installs it inside boot()\'s prepare' },
+];

package/lib/types/dsh-adapter/host-dsh.d.ts

@@ -0,0 +1,106 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type * as AppBoot from '@deepseek-ai/dsh-app-boot';
+import type * as HomePaths from '@deepseek-ai/dsh-home-paths';
+import type * as Cmdline from '@deepseek-ai/dsh-cmdline';
+import type * as HttpProxy from '@deepseek-ai/dsh-http-proxy';
+import { HOST_MODULES } from './host-contract.js';
+import { type ProcessExitSeam } from './process-exit.js';
+type Warn = (line: string) => void;
+/** Picking from the real module type fails the build when the contract names an undeclared export. */
+type ContractExports<K extends (typeof HOST_MODULES)[number]['key']> = Extract<(typeof HOST_MODULES)[number], {
+    key: K;
+}>['exports'][number];
+type AppBootModule = Pick<typeof AppBoot, ContractExports<'appBoot'>>;
+/** `@deepseek-ai/dsh/profile-boot`, declared locally: the host CLI is not a dependency. */
+interface ProfileBootModule {
+    prepareProfile(name: string, userLayer?: boolean, fromDefaultProfile?: string): AppBoot.Profile;
+    readonly INSTALL_ANCHOR: string;
+    readonly PROFILE_ROOT_FILENAME: 'cordis.yml';
+}
+type HomePathsModule = Pick<typeof HomePaths, ContractExports<'homePaths'>>;
+type CmdlineModule = Pick<typeof Cmdline, ContractExports<'cmdline'>>;
+type HttpProxyModule = Pick<typeof HttpProxy, ContractExports<'httpProxy'>>;
+export interface HostDsh {
+    readonly packageDir: string;
+    /** Reported, not gated on: the exports are. */
+    readonly version: string;
+    readonly Context: new () => Context;
+    readonly appBoot: AppBootModule;
+    readonly Loader: unknown;
+    readonly homePaths: HomePathsModule;
+    readonly launchEnvironmentKey: string;
+    readonly cmdline: CmdlineModule;
+    readonly profileBoot: ProfileBootModule;
+    readonly httpProxy: HttpProxyModule;
+}
+/** Where the host came from, or why there is none (shown to the user). */
+export type HostDshLocation = {
+    readonly packageDir: string;
+    readonly via: 'link' | 'shim' | 'beside' | 'volta';
+} | {
+    readonly reason: string;
+};
+/** `findHostDsh`'s reason when PATH has no `dsh` at all. */
+export declare const NO_DSH_ON_PATH = "no dsh on PATH";
+/**
+ * Find the installed host package from the first `dsh` on PATH, following
+ * what a launch would run: a link (npm on Unix) by its realpath, an npm /
+ * pnpm / yarn launcher script (sh, `.cmd`, `.ps1`) by the script path it
+ * starts, a volta shim through volta's package image. A launcher that
+ * cannot be followed is no host: the reason says what was found.
+ */
+export declare function findHostDsh(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): HostDshLocation;
+/**
+ * The script paths a launcher starts: quoted or bare tokens ending in
+ * `.js` / `.mjs` / `.cjs` (npm and pnpm cmd-shim, `.cmd` and `.ps1` shims,
+ * a hand-written `exec node …/bin.js` wrapper).
+ */
+export declare function launcherScriptPaths(text: string): string[];
+/** Expand a launcher's own-directory variables and resolve with `platform`'s path rules. */
+export declare function resolveLauncherPath(script: string, base: string, platform: NodeJS.Platform): string | undefined;
+/**
+ * The capability probe: throws naming what is missing (no host, a module that
+ * does not import, an export the entry needs); the caller falls back.
+ */
+export declare function loadHostDsh(packageDir?: string | undefined): Promise<HostDsh>;
+export interface HostRoot {
+    readonly ctx: Context;
+    /**
+     * The dsh-tui profile (DSH kernel) or the light profile (./lite-profile.ts).
+     * Rejects with the Loader's or the audit's error; the tree stays up.
+     * `stopping`: a root dispose is waiting, so skip audit and readiness.
+     */
+    compose(warn: Warn, stopping?: () => boolean): Promise<void>;
+    /**
+     * Remove the fail-loud handlers (DSH kernel; a no-op otherwise) once the
+     * TUI's process guard is up: it alone owns a fatal error, and fail-loud
+     * would exit before the funnel restored the terminal.
+     */
+    readonly uninstallFailLoud: () => void;
+}
+export interface PrepareHostRootOptions {
+    readonly profile: string;
+    /** `ctx.cmdlineArgs`. */
+    readonly args: readonly string[];
+    /** Compose the profile later (the DSH kernel); else only the resolution. */
+    readonly dsh: boolean;
+    /** Routes `ctx.appExit(code)` to the TUI's exit funnel; the bounded `shutdown` when unfilled or refused. */
+    readonly exitSeam?: ProcessExitSeam;
+}
+/**
+ * Build the entry's root from the host's `cordis` and install the host's
+ * module resolution on it before any TUI module is imported, so the TUI and
+ * the DSH plugins resolve shared packages (react, schemastery, the
+ * `@deepseek-ai/*` peers) the same way. Both kernels: otherwise the peers
+ * resolve only through `$DSH_HOME/profiles/node_modules`, which a fresh
+ * install may not have. The DSH kernel also gets the rest of `runProfile`'s prepare.
+ */
+export declare function prepareHostRoot(host: HostDsh, options: PrepareHostRootOptions): Promise<HostRoot>;
+/** A composition failure, with the startup report saved for it. */
+export declare class HostComposeError extends Error {
+    readonly original: unknown;
+    readonly logPath: string | undefined;
+    constructor(original: unknown, logPath: string | undefined);
+}
+export {};
+//# sourceMappingURL=host-dsh.d.ts.map

package/lib/types/dsh-adapter/host-dsh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-dsh.d.ts","sourceRoot":"","sources":["../../../src/dsh-adapter/host-dsh.ts"],"names":[],"mappings":"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"}