dsh-over-ssh 0.0.0-stage → 0.1.0

package/lib/types/src/host/integration/session-api.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The session-administration HTTP route: `/api/remote-workspace/sessions`.
+ *
+ * The route is the client half's only way to reach the session store. It reuses the roots route's
+ * **same-origin trust check** ({@link trustVerdict}) rather than inventing a second policy: a request that may
+ * edit roots may also delete sessions, and one that may not, may not.
+ *
+ * ## Two rules that shape the wire
+ *
+ *  1. **`GET` never mutates.** It answers the inventory and the bin. Deletion and restore are `POST` actions,
+ *     so a prefetch, a link preview or an over-eager browser cannot destroy anything.
+ *  2. **Irreversible actions are refused here unless the caller says it means it.** `purge` and
+ *     `mode: 'permanent'` require `confirm: true` in the body. The UI already asks; this is the second lock, so
+ *     a bug in the client cannot turn a recycle into an irreversible delete.
+ *
+ * @module dsh-remote-workspace/integration/session-api
+ */
+import { type RootsApiRequest, type RootsApiResponse } from '../app/roots-api.ts';
+import type { SessionAdminService } from '../app/session-admin-service.ts';
+import type { SessionRecord, SessionTrashEntry } from '../domain/session-admin.ts';
+/** The one path this plugin claims for session administration. */
+export declare const SESSION_API_PATH = "/api/remote-workspace/sessions";
+/** Largest accepted request body. An id list is a few hundred bytes. */
+export declare const SESSION_API_MAX_BODY_BYTES: number;
+/** One accepted `POST` action; anything else is refused with the list. */
+export declare const SESSION_API_ACTIONS: readonly ["delete", "delete-workspace", "restore", "purge", "sweep", "preview"];
+/** One accepted action. */
+export type SessionApiAction = (typeof SESSION_API_ACTIONS)[number];
+/** One inventory row as the wire carries it (a field-by-field projection, never the record itself). */
+export interface SessionRow {
+    readonly id: string;
+    readonly classification: 'normal' | 'subsession' | 'unreadable';
+    readonly parentSessionId?: string;
+    readonly title?: string;
+    readonly cwd?: string;
+    /** Display title of the workspace owning `cwd`; absent when no registered workspace owns it. */
+    readonly workspaceTitle?: string;
+    readonly bytes: number;
+    readonly updatedAtMs: number;
+    readonly live: boolean;
+}
+/** One bin row as the wire carries it. */
+export interface SessionBinRow {
+    readonly entryId: string;
+    readonly sessionId: string;
+    readonly title?: string;
+    readonly bytes: number;
+    readonly deletedAtMs: number;
+    readonly movedBy: 'rename' | 'copy';
+    readonly confirmedBy?: string;
+}
+/** The seams the route needs. */
+export interface SessionApiDeps {
+    /** The session administration service (or a getter, since services can appear after activation). */
+    readonly service: () => SessionAdminService | undefined;
+    /** Retention limits used by `sweep`, from configuration. */
+    readonly policy: () => {
+        readonly maxEntries: number;
+        readonly maxBytes: number;
+        readonly maxAgeMs: number;
+    };
+    /** Injected clock, so a test can pin `sweep`'s "now". */
+    readonly now?: () => number;
+}
+/** The handler pair the entry registers. */
+export interface SessionApi {
+    readonly handle: (req: RootsApiRequest, res: RootsApiResponse) => Promise<void>;
+    dispose(): void;
+}
+/** Project one inventory record to the wire shape. */
+export declare function toSessionRow(record: SessionRecord): SessionRow;
+/** Project one bin entry to the wire shape. */
+export declare function toSessionBinRow(entry: SessionTrashEntry): SessionBinRow;
+/**
+ * Build the handler pair.
+ *
+ * @param deps - injected seams.
+ * @returns `handle` plus a no-op `dispose`.
+ */
+export declare function createSessionApi(deps: SessionApiDeps): SessionApi;
+//# sourceMappingURL=session-api.d.ts.map

package/lib/types/src/host/integration/session-bin-lock.d.ts

@@ -0,0 +1,80 @@
+/**
+ * A cross-process advisory lock for the session recycle-bin index.
+ *
+ * Why this exists: the in-process promise chain in `session-admin-service.ts` cannot see **another DSH
+ * process**. Two processes deleting a session at the same time can each read the old index and then each
+ * write back their own version, so one entry is lost — and a lost entry is not a cosmetic problem: the
+ * moved bytes stay on disk while the index does not mention them, making them invisible *and* unrestorable.
+ *
+ * ## Design
+ *
+ * A lock file created with `wx` (exclusive create) is the mutual exclusion primitive: the filesystem
+ * guarantees exactly one creator wins, on local and network filesystems alike, without any dependency.
+ * The file records `{ pid, host, acquiredAtMs }` so a human can see who holds it.
+ *
+ * **Stale locks are reclaimed by age.** A process that dies while holding the lock leaves the file behind;
+ * without reclamation every later deletion would fail forever. The threshold is deliberately generous
+ * (see {@link DEFAULT_STALE_LOCK_MS}) because reclaiming a *live* holder's lock is worse than waiting: it
+ * reintroduces exactly the race this module prevents.
+ *
+ * This is advisory, not a guarantee: it coordinates cooperating processes of this plugin, and does not
+ * protect the bin from a process that ignores the protocol.
+ *
+ * @module dsh-remote-workspace/integration/session-bin-lock
+ */
+/** How long a lock may sit before another process may reclaim it. */
+export declare const DEFAULT_STALE_LOCK_MS = 60000;
+/** How long to wait between acquisition attempts. */
+export declare const DEFAULT_LOCK_RETRY_MS = 25;
+/** How long to keep trying before giving up and reporting contention. */
+export declare const DEFAULT_LOCK_TIMEOUT_MS = 30000;
+/** Options for {@link createSessionBinLock}. */
+export interface SessionBinLockOptions {
+    /** Lock file path. */
+    readonly path: string;
+    /** Stale threshold; non-positive disables reclamation (waiting forever is then the caller's risk). */
+    readonly staleMs?: number;
+    readonly retryMs?: number;
+    readonly timeoutMs?: number;
+    /** Injected sleep so tests need no real waiting. */
+    readonly sleep?: (ms: number) => Promise<void>;
+    /** Injected clock. */
+    readonly now?: () => number;
+    /** Identity recorded in the lock file (defaults to pid/host). */
+    readonly owner?: string;
+    /** Called when a stale lock is reclaimed, so the event is observable instead of silent. */
+    readonly onReclaim?: (event: {
+        readonly path: string;
+        readonly ageMs: number;
+        readonly holder: Partial<SessionBinLockRecord>;
+    }) => void;
+}
+/** What one lock file records. */
+export interface SessionBinLockRecord {
+    readonly pid: number;
+    readonly host: string;
+    readonly acquiredAtMs: number;
+    /** Human-readable holder, for diagnosis (see `onReclaim`). **Not** used for ownership checks. */
+    readonly owner?: string;
+    /**
+     * Per-acquisition ownership token, compared before release.
+     *
+     * Separate from `owner` on purpose: `owner` is documented as a **diagnostic** field and is asserted as
+     * such by `tests/session-bin-lock.test.ts`; overloading it with a token would change what a reader of
+     * the lock file sees. This field exists only so a holder whose lock was reclaimed cannot delete its
+     * successor's lock.
+     */
+    readonly token?: string;
+}
+/**
+ * Run one operation under the cross-process lock.
+ *
+ * @param options - lock file path plus timing knobs.
+ * @returns a `withLock(key, operation)` function; `key` is accepted for interface compatibility and is not
+ *   used to derive the path (there is exactly one session-bin index).
+ */
+export declare function createSessionBinLock(options: SessionBinLockOptions): {
+    withLock: <T>(_key: string, operation: () => Promise<T>) => Promise<T>;
+    lockPath: string;
+};
+//# sourceMappingURL=session-bin-lock.d.ts.map

package/lib/types/src/host/integration/session-header.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Read a session log's header line, with a **bounded** memory footprint.
+ *
+ * Why this is its own module: the reader used to live in the composition root (`src/index.ts`), where no
+ * test can reach it (审计 0046 记录了同款教训). A file-system reader is exactly the kind of code that needs a
+ * test to pin its *bounds*, and the bound is the whole point here.
+ *
+ * ## What went wrong before
+ *
+ * The old reader claimed to "decompress only the head" but read the **whole file** first:
+ *
+ * ```ts
+ * const handle = await readFile(path);                                    // 10.9 MiB for one real session
+ * text = zstdDecompressSync(handle.subarray(0, 256 * 1024)).toString();   // cap applies to the SLICE only
+ * } catch {
+ *   text = zstdDecompressSync(await readFile(path)).toString();           // and the fallback reads it AGAIN
+ * }
+ * ```
+ *
+ * `readFile` has no `maxBytes`, so the 256 KiB constant bounded the decompressor's *input*, never the read.
+ * Measured on the reference machine's real store (73 sessions): **105.3 MiB** read into memory to extract
+ * 73 first lines (19 KiB of output), worst single session **10.9 MiB**, and 51 of 73 logs exceeded the
+ * "cap" that was supposedly in force. See `doc/06-audits/0050`.
+ *
+ * ## The contract this module implements
+ *
+ *  1. **Never read more than `cap` bytes of any one file.** The read is a positioned `read(2)` off a
+ *     descriptor, so the file's size is irrelevant to peak memory.
+ *  2. **The fallback is bounded too.** A slice that ends inside a zstd frame can be rejected by the
+ *     decoder; the retry asks for a larger head (`retryBytes`), never for the whole file.
+ *  3. **Failure is `undefined`, never a throw.** A directory with no log, a corrupt frame, or an
+ *     unparsable first line all yield `undefined`, so the inventory classifies the session as
+ *     `unreadable` instead of guessing from the lossy directory name (ADR-0009).
+ *
+ * @module dsh-remote-workspace/integration/session-header
+ */
+import type { SessionHeader } from '../app/session-admin-service.ts';
+/**
+ * Bytes read from the head of a session log on the first attempt.
+ *
+ * Chosen from measurement, not taste. On the reference machine's real store (73 sessions, `0050`):
+ *
+ *  - the largest **header line** is **309 B** of UTF-8 (p50 279 B);
+ *  - the largest compressed frame carrying a lone header is **253 B**;
+ *  - the smallest head that recovered **all 73** headers is **4 KiB**.
+ *
+ * 64 KiB is therefore **16x** the empirically sufficient head and **212x** the largest header line, while
+ * being 4x smaller than the previous (and, as it turned out, entirely non-binding) 256 KiB constant.
+ */
+export declare const SESSION_HEADER_READ_BYTES: number;
+/**
+ * Bytes read on the retry, when the first slice ended inside the frame.
+ *
+ * Still bounded, and still independent of the file's real size — that is the property the old fallback
+ * broke. A log whose header genuinely cannot be recovered from 1 MiB is reported `unreadable`.
+ */
+export declare const SESSION_HEADER_RETRY_BYTES: number;
+/** The I/O this reader needs; injected so a test can pin the byte bounds exactly (AGENTS.md 红线 3). */
+export interface SessionHeaderIo {
+    /** List one directory's entry names. */
+    readonly listDir: (dir: string) => Promise<readonly string[]>;
+    /**
+     * Read at most `maxBytes` from the **head** of one file.
+     *
+     * An implementation must not read the whole file and slice: that is precisely the defect this module
+     * exists to prevent. It may return fewer bytes (a short file, or a short read).
+     */
+    readonly readHead: (path: string, maxBytes: number) => Promise<Uint8Array>;
+    /** Decompress one zstd frame (or frame prefix) to UTF-8 text. */
+    readonly decompress: (bytes: Uint8Array) => string;
+    /** Head caps to try, in order. Defaults to `[SESSION_HEADER_READ_BYTES, SESSION_HEADER_RETRY_BYTES]`. */
+    readonly caps?: readonly number[];
+}
+/**
+ * Parse the first JSONL line into the header fields this feature needs.
+ *
+ * @param text - decompressed log text (only the head is present).
+ * @returns the header, or `undefined` when the first line is absent or not a session record.
+ */
+export declare function parseSessionHeaderLine(text: string): SessionHeader | undefined;
+/**
+ * Build the header reader.
+ *
+ * Every failure is reported as `undefined` rather than thrown: an inventory must survive one unreadable
+ * session.
+ *
+ * @param io - directory listing, bounded head read and decompressor.
+ * @returns a reader from one session directory to its header, or `undefined` when unreadable.
+ */
+export declare function createSessionHeaderReader(io: SessionHeaderIo): (dir: string) => Promise<SessionHeader | undefined>;
+/**
+ * Read at most `maxBytes` from the head of a file, off a descriptor.
+ *
+ * A positioned read is what makes the bound real: `readFile` would materialise the entire log first.
+ *
+ * @param path - file to read.
+ * @param maxBytes - hard ceiling on the bytes returned.
+ * @returns the bytes actually read (possibly fewer, possibly none).
+ */
+export declare function readHeadFromDisk(path: string, maxBytes: number): Promise<Uint8Array>;
+/**
+ * The production I/O: real `readdir`, a **bounded** head read and the real zstd decoder.
+ *
+ * Exported so a test can pin the one property the reader's whole contract rests on — that the production
+ * `readHead` respects its cap. Exercising the assembled reader through an *injected* fake cannot catch a
+ * regression in this wiring, because the fake stays bounded either way; a mutation experiment during
+ * audit 0050 exposed exactly that gap.
+ *
+ * @returns the production I/O bundle.
+ */
+export declare function createDiskSessionHeaderIo(): SessionHeaderIo;
+/**
+ * The production reader: real `readdir`, a bounded head read and the real zstd decoder.
+ *
+ * @returns a reader from one session directory to its header, or `undefined` when unreadable.
+ */
+export declare function createDiskSessionHeaderReader(): (dir: string) => Promise<SessionHeader | undefined>;
+//# sourceMappingURL=session-header.d.ts.map

package/lib/types/src/host/integration/session-labels.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Resolve the two human labels a session listing needs: the session's own title and the display name of the
+ * workspace that owns its directory.
+ *
+ * Both live in **optional platform services**, and both are read through a structural context shape rather
+ * than a Cordis import, so this module is unit-testable with a plain object and the domain layer keeps its
+ * no-`@deepseek-ai/*` rule.
+ *
+ * Why this is its own module: these are the only two places where the session feature reaches into the
+ * platform, and the composition root that calls them cannot be exercised by a test. Anything decision-like
+ * that lands there is untested by construction (审计 0046 记录了同款教训), so the decisions live here.
+ *
+ * @module dsh-remote-workspace/integration/session-labels
+ */
+import type { SessionHeader } from '../app/session-admin-service.ts';
+/** The one context method these resolvers need, kept structural so no Cordis import is required. */
+export interface OptionalServiceLookup {
+    get(name: string): unknown;
+}
+/**
+ * Resolve a session's generated title through the platform's projection cache.
+ *
+ * The title is a **projection**, never header metadata: the header's own `title` field is always absent (all
+ * 88 sessions on the reference machine had none), which is why the panel could only ever show a uuid. The
+ * cache is the sanctioned zero-I/O listing read — `cachedSnapshot` validates the stored row against the
+ * header's lifecycle identity (`formatVersion`, `createdAt`, `cwd`, `isSeeded`), so a title from a different
+ * lifecycle that reused the same id can never be served.
+ *
+ * Every failure is benign and yields `undefined`: a session persisted before the cache was composed has no
+ * row until it is opened once, and the row's unit version must match the live title projection. The caller
+ * then falls back to the workspace, and finally to the id.
+ *
+ * The service is looked up **per call**, not once at activation: on this runtime an optional service can
+ * still be absent while a plugin entry activates (`session-route-wiring.ts` documents the same trap for
+ * `webServer`), and a one-time check would then disable titles for the whole process lifetime.
+ *
+ * @param ctx - anything with cordis's `get`; usually the plugin context.
+ * @returns a resolver from header to title; it yields `undefined` whenever the service or the row is absent.
+ */
+export declare function createSessionTitleResolver(ctx: OptionalServiceLookup): (header: SessionHeader) => string | undefined;
+/**
+ * Resolve a `cwd` to its registered workspace's display title.
+ *
+ * The registry is the platform's own durable mapping from directory to a human name (`libaw_vep`,
+ * `a733_android13`), which is exactly the label a session list needs and the one the sidebar shows. A
+ * directory no workspace owns yields `undefined`; the client then uses the path's leaf name, so a session
+ * outside a workspace is still identifiable.
+ *
+ * Like {@link createSessionTitleResolver}, the service is looked up **per call** so a late-arriving registry
+ * still works.
+ *
+ * @param ctx - anything with cordis's `get`; usually the plugin context.
+ * @returns a resolver from `cwd` to workspace title; it yields `undefined` whenever none applies.
+ */
+export declare function createWorkspaceTitleResolver(ctx: OptionalServiceLookup): (cwd: string | undefined) => string | undefined;
+//# sourceMappingURL=session-labels.d.ts.map

package/lib/types/src/host/integration/session-route-wiring.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Own the session-administration route (`/api/remote-workspace/sessions`) on the browser carrier.
+ *
+ * This is the same **deferred carrier** dance as `roots-wiring.ts`, and for the same measured reason: on the
+ * packaged 0.2.0-rc.2 runtime `ctx.get('webServer')` is `undefined` while a plugin entry activates (the
+ * carrier row is constructed later), so a `ctx.get` lookup silently skips registration and every request
+ * answers `http-404` from the SPA fallback while the plugin looks perfectly healthy.
+ * `ctx.inject(['webServer'], ...)` resolves the service when it appears.
+ *
+ * A profile without a carrier (headless) is **not** an error: the plugin works, the panel simply has no
+ * session data channel. The reason is collected as a warning the entry logs once `ctx.logger` resolves.
+ *
+ * @module dsh-remote-workspace/integration/session-route-wiring
+ */
+import { type SessionApi, type SessionApiDeps } from './session-api.ts';
+/** The browser HTTP carrier, narrowed to the one method this wiring calls. */
+export interface SessionRouteHost {
+    register(route: {
+        readonly kind: 'exact';
+        readonly path: string;
+        readonly handler: (req: never, res: never) => Promise<void>;
+    }): () => void;
+}
+/** The provider that hands out the carrier once it exists. */
+export interface SessionRouteHostProvider {
+    inject(names: readonly string[], callback: (scoped: {
+        get(name: string): unknown;
+    }) => void | (() => void)): unknown;
+}
+/** Everything the wiring needs from the entry. */
+export interface SessionRouteWiringDeps extends SessionApiDeps {
+    readonly webServerProvider?: SessionRouteHostProvider | undefined;
+}
+/** What the entry holds on to. */
+export interface SessionRouteWiring {
+    readonly api: SessionApi;
+    /** Human-readable reasons the route may not be live; logged after activation. */
+    readonly routeWarnings: () => readonly string[];
+    /** Whether the deferred carrier callback ever ran. */
+    readonly injectRan: () => boolean;
+    readonly dispose: () => void;
+}
+/**
+ * Register the route as soon as the carrier exists, and again if it ever comes back.
+ *
+ * @param deps - the API seams plus the carrier provider.
+ * @returns the wiring handle.
+ */
+export declare function createSessionRouteWiring(deps: SessionRouteWiringDeps): SessionRouteWiring;
+//# sourceMappingURL=session-route-wiring.d.ts.map

package/lib/types/src/host/integration/session-scope.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Which session is asking — the identity channel the platform does not hand to `ctx.fs`.
+ *
+ * Why this exists. 「添加目录」 roots belong to **one conversation** (ADR-0013). The route table already refuses
+ * a root to another *workspace* (ADR-0012) by comparing the caller's cwd, but two conversations can run in the
+ * same workspace directory, and `FsProvider`'s methods receive only `{ cwd?, signal? }`
+ * (`@deepseek-ai/dsh-fs` 0.2.1-rc.2, `lib/types/index.d.ts`) — at that seam those two conversations are
+ * indistinguishable, so a directory one of them added stays reachable by the other.
+ *
+ * The identity is available one level up. Every tool execution carries its agent, and the session id is
+ * `exec.agent.session.header.id` — the platform itself reads exactly that field (`dsh-tool-fs-search`:
+ * `const sessionId = exec.agent?.session.header.id`) and hands the session to the sandbox policy
+ * (`dsh-tools`: `policy.resolve({ session: exec.agent.session })`). This module carries it **down** to the
+ * filesystem seam: the dispatcher resolves the tool definition once per call
+ * (`ctx.tools.resolveExecution(name, agent, …)`) and then invokes that definition's `execute`, so wrapping the
+ * resolver lets the body run inside an `AsyncLocalStorage` context. Every `ctx.fs.resolve` / `lstat` issued
+ * from the body — directly or after any number of awaits — reads it back through {@link currentSessionId}.
+ *
+ * Why the store lives on `globalThis`. The host half is built as several independent ESM bundles
+ * (`lib/index.js`, `lib/fs.js`, `lib/file-references.js`, …; see `tools/build-host.mjs`), so a module-level
+ * `AsyncLocalStorage` would be **one instance per bundle**: the wrapper installed by `index.js` would write into
+ * a store that `fs.js` never reads. A `Symbol.for` slot is the only thing the bundles provably share.
+ *
+ * Degradation. Everything here is best-effort by construction: when the tools service does not expose
+ * `resolveExecution` (a future core renames it), {@link installToolSessionScope} returns `false` and the plugin
+ * keeps working with the workspace-level gate alone — narrower isolation, never a broken filesystem.
+ *
+ * @module dsh-over-ssh/integration/session-scope
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionIdentity } from '../domain/roots/session-roots.ts';
+/** The per-call context carried across the filesystem seam. */
+export interface SessionScope {
+    /** The calling session, or `undefined` for an agentless call (a CLI, a replay). */
+    readonly sessionId: string | undefined;
+}
+/**
+ * The session the current call is running for.
+ *
+ * @returns the session id, or `undefined` when the call is not inside a session's tool execution.
+ */
+export declare function currentSessionId(): string | undefined;
+/**
+ * Run one call inside a session's scope.
+ *
+ * Exported for tests and for callers that already know the identity (the plugin's own `remote_*` tools get it
+ * from their execution context directly and do not need this).
+ *
+ * @param sessionId - the session the call belongs to, or `undefined` for an agentless call.
+ * @param run - the work to run inside the scope.
+ * @returns whatever `run` returns.
+ */
+export declare function runInSession<T>(sessionId: string | undefined, run: () => T): T;
+/**
+ * Fork lineage of one session, nearest first, read from the platform's session service.
+ *
+ * A fork inherits its parent's 「添加目录」 entries (ADR-0013): the durable header carries `parentSession`, so the
+ * chain is walked here rather than copied into the roots file at fork time — a copy would have to be kept in
+ * sync with every later add and remove on either side, and would go stale the moment either session acts.
+ *
+ * Bounded and cycle-safe: the walk stops after {@link MAX_FORK_DEPTH} hops or when it revisits an id, so a
+ * corrupt header cannot spin. Degrades to `[]` on any doubt — the caller then behaves exactly as before
+ * ADR-0013 (no inheritance), which is the safe direction.
+ *
+ * @param ctx - a context that may carry the session service.
+ * @param sessionId - the asking session.
+ * @returns the ancestor ids, nearest first.
+ */
+export declare function readSessionAncestors(ctx: Context, sessionId: string): readonly string[];
+/**
+ * The identity to hand the domain rule for one session.
+ *
+ * @param ctx - a context that may carry the session service.
+ * @param sessionId - the asking session, or `undefined` for an agentless call.
+ * @returns the identity, or `{}` when there is no session.
+ */
+export declare function sessionIdentityOf(ctx: Context, sessionId: string | undefined): SessionIdentity;
+/** The slice of a tool execution this module reads; structural, so no platform type is imported. */
+export interface ToolExecutionLike {
+    readonly agent?: {
+        readonly session?: {
+            readonly header?: {
+                readonly id?: string;
+            };
+        };
+    } | undefined;
+}
+/** The slice of a tool definition this module wraps. */
+export interface ToolDefinitionLike {
+    readonly execute?: ((args: unknown, exec: ToolExecutionLike) => unknown) | undefined;
+}
+/** The slice of the platform's tools service this module patches. */
+export interface ToolsServiceLike {
+    resolveExecution?: ((name: string, agent: unknown, parent: boolean) => ToolDefinitionLike | undefined) | undefined;
+}
+/**
+ * The session id one tool execution belongs to.
+ *
+ * @param exec - the execution context handed to `execute`.
+ * @returns the session id, or `undefined` when the call has no agent.
+ */
+export declare function sessionIdOf(exec: ToolExecutionLike | undefined): string | undefined;
+/**
+ * Install the session scope on the platform's tools service.
+ *
+ * Idempotent, and safe to call before or after other plugins register tools: the patch is on the **resolver**,
+ * not on `register`, so tools registered earlier are covered too.
+ *
+ * @param tools - the `tools` service, or anything else when the platform did not provide one.
+ * @returns whether the scope is installed (`false` means the plugin runs with workspace-level isolation only).
+ */
+export declare function installToolSessionScope(tools: unknown): boolean;
+//# sourceMappingURL=session-scope.d.ts.map

package/lib/types/src/host/integration/session-tools.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The session-administration tool surface: `remote_session_list`, `remote_session_delete`, `remote_session_restore`.
+ *
+ * These operate on the **platform's session store**, not on a remote root, so they take no connection or root:
+ * a session is identified by its id, and its location is derived from its own header (`cwd` → `projectKey`).
+ * That is also why they do not go through `ctx.fs` — the store is not a workspace file.
+ *
+ * **Irreversible calls are gated.** `mode: "permanent"` goes through the platform's pre-execute waterfall and is
+ * answered with `ask`; when the composition has no approval surface the registry turns that into a denial (fail
+ * closed). Recycle-mode deletion is an ordinary call: it is recoverable.
+ *
+ * @module dsh-remote-workspace/integration/session-tools
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
+import type { DeleteSessionResult, SessionAdminService } from '../app/session-admin-service.ts';
+import type { SessionTrashEntry } from '../domain/session-admin.ts';
+import type { SessionRecord } from '../domain/session-admin.ts';
+/** Format one inventory record as a human-readable line. */
+export declare function formatSession(record: SessionRecord): string;
+/** Human summary of a session deletion. */
+export declare function formatSessionDelete(result: DeleteSessionResult): string;
+/** Human summary of the bin. */
+export declare function formatSessionBin(entries: readonly SessionTrashEntry[]): string;
+/**
+ * Build the session-administration definitions.
+ *
+ * @param service - the session administration service.
+ * @returns definitions ready for `ctx.tools.register`.
+ */
+export declare function sessionToolDefinitions(service: SessionAdminService): ToolDefinition[];
+/**
+ * Gate irreversible session operations behind the platform's approval surface.
+ *
+ * Denial by default is deliberate: these calls destroy conversation history that cannot be regenerated, and a
+ * composition without an approval surface must refuse rather than proceed.
+ *
+ * @param ctx - host context with the `tools` service.
+ * @returns a disposer removing the gate.
+ */
+export declare function sessionDestructionGate(ctx: Context): () => void;
+/** Register the three tools and the gate. */
+export declare function registerSessionTools(ctx: Context, service: SessionAdminService): () => void;
+//# sourceMappingURL=session-tools.d.ts.map

package/lib/types/src/host/integration/strict-arguments.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Strict root-level argument validation for this plugin's tool surface.
+ *
+ * **Why this exists.** `defineTool` compiles the parameter map into an object-rooted JSON Schema that
+ * carries `properties` and `required` but **no `additionalProperties`**, and the core validator only
+ * reports an undeclared property when that keyword is explicitly `false`
+ * (`@deepseek-ai/dsh-tools` `json-schema.ts`, the `object` case). A model that writes `stdin`, `shell`,
+ * `waitMs`, `mode` or `executable` therefore gets a **successful** call in which the field was silently
+ * dropped — the most dangerous failure mode there is, because the caller believes the setting took effect.
+ *
+ * The plugin cannot close the core's implicit root, so it enforces closure itself on the documented
+ * pre-dispatch extension point (`tools/pre-execute`), the same hook `permanentDeleteGate` already uses.
+ *
+ * **One message, everything wrong at once.** The core reports missing/typed arguments from inside
+ * `execute`, but a pre-execute gate runs *before* that, so this gate can name every unknown field and every
+ * missing required field in a single refusal instead of sending the caller back one field at a time.
+ *
+ * @module dsh-remote-workspace/integration/strict-arguments
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * The name prefix every tool of this plugin uses.
+ *
+ * The gate is scoped by prefix rather than by a copied name list: a list would drift the moment a tool is
+ * added, and this plugin's namespace is `remote_*`. `tests/strict-arguments.test.ts` pins that every tool
+ * name this plugin registers starts with the prefix, so the assumption cannot rot silently.
+ */
+export declare const STRICT_TOOL_PREFIX = "remote_";
+/** Whether a tool name belongs to this plugin's surface. */
+export declare function isStrictTool(name: string): boolean;
+/** What one argument check found. */
+export interface ArgumentViolations {
+    /** Fields the caller sent that the tool does not declare. */
+    readonly unknown: readonly string[];
+    /** Fields the tool requires that the caller did not send. */
+    readonly missing: readonly string[];
+    /** Every field the tool does declare, in declaration order. */
+    readonly declared: readonly string[];
+}
+/** The parts of one registered parameter schema this gate reads. */
+export interface StrictParameterSchema {
+    readonly properties?: Readonly<Record<string, unknown>> | undefined;
+    readonly required?: readonly string[] | undefined;
+}
+/**
+ * Compare a call's arguments against the tool's own declared parameters.
+ *
+ * Only the **root** is checked: a nested open map (such as `remote_exec`'s `env`) keeps whatever openness it
+ * declared, because closing it would reject the very keys that field exists to carry.
+ *
+ * A non-object argument (or a missing schema) yields no violations here: the core's own validation owns
+ * those cases, and reporting them twice would produce two different messages for one mistake.
+ *
+ * @param schema - the registered parameter schema (`properties` / `required`).
+ * @param args - the model-supplied arguments, however malformed.
+ * @returns the unknown fields, the missing required fields, and the declared field list.
+ */
+export declare function argumentViolations(schema: StrictParameterSchema | undefined, args: unknown): ArgumentViolations;
+/** Whether anything was found worth refusing. */
+export declare function hasViolations(violations: ArgumentViolations): boolean;
+/**
+ * The model-facing refusal.
+ *
+ * It names what was rejected **and** what is accepted: the caller's next attempt should be a correction, not
+ * a guess. "Unknown field" alone would leave the model trying spellings one at a time.
+ *
+ * @param toolName - the tool that was called.
+ * @param violations - what the check found.
+ * @returns one actionable sentence.
+ */
+export declare function formatArgumentViolations(toolName: string, violations: ArgumentViolations): string;
+/**
+ * Register the gate.
+ *
+ * @param ctx - host context with the `tools` service.
+ * @returns a disposer removing the listener (idempotent).
+ */
+export declare function strictArgumentsGate(ctx: Context): () => void;
+//# sourceMappingURL=strict-arguments.d.ts.map