dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,316 +0,0 @@
-/**
- * Background jobs on the remote host: `remote_exec_background` plus the four job controls.
- *
- * The transport could already do every one of these things — `AgentTransport.procStart` / `procStatus` /
- * `procOutput` / `procKill` / `procList` — and **nothing called them**: a long remote build had to be
- * hand-rolled as `nohup … &` plus manual polling, with no exit code, no job identity and no way to cancel.
- * These five tools close that gap and mirror the platform's local `job_output` / `job_list` / `job_kill`
- * semantics, which is what the caller already knows.
- *
- * Four facts the wording is built on, each verified in the agent's own source rather than assumed:
- *
- *  - **Jobs die with the connection** (`dsh-over-ssh-agent/internal/proc/jobs.go` module notes: the agent kills
- *    every job when the ssh channel closes). "Background job" here means "background within this connection",
- *    never a durable queue, so each description says so instead of letting the caller assume durability.
- *  - **Nothing is pushed.** Protocol v1's frame discipline has no server-initiated frames, so progress is
- *    polled. The `wait` parameter below is a bounded poll loop inside the plugin, not a subscription.
- *  - **A job's output is a bounded ring that drops the OLDEST bytes** (`proc.start`), unlike `proc.exec`,
- *    which keeps head+tail and spills the rest to a file. There is **no spill file** for a job, so
- *    `droppedBytes` is the only signal that output has a hole, and `proc.output` adds `lost: true` when the
- *    requested span itself was already dropped. A renderer that hid either would let a caller read a torn
- *    log as a complete one — the exact failure the user reported.
- *  - **`proc.*` needs a Tier 2 agent.** {@link isAgentJobCapable} decides by method presence (the agent's
- *    capability frame has no `proc` bit), and a transport that fails the check is refused with
- *    `REMOTE_UNSUPPORTED` instead of silently degrading to a foreground command.
- *
- * @module dsh-over-ssh/integration/remote-job-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import { type SessionRootOutcome } from '../../domain/roots/session-roots.ts';
-import type { Transport } from '../../infra/transport/transport.ts';
-import type { AgentJobKill, AgentJobOutput, AgentJobStatus, AgentProcStartRequest } from '../../infra/transport/agent/agent-transport.ts';
-/** Default wait applied when `wait: true` is set without `timeoutMs`. */
-export declare const DEFAULT_JOB_WAIT_MS = 30000;
-/** Hard cap on one wait, so a poll loop cannot hold a tool call open indefinitely. */
-export declare const MAX_JOB_WAIT_MS = 600000;
-/** Poll interval of the wait loop. */
-export declare const DEFAULT_JOB_POLL_MS = 500;
-/**
- * Server-side wait requested per long-poll slice.
- *
- * 5 s is chosen against the transport's request budget: the slice plus `waitBudget`'s 5 s margin stays
- * inside the 15 s default, so a normal wait can never trip the per-request deadline (which is fatal to
- * the connection). A finished job returns from the slice immediately, so this only bounds the idle case.
- */
-export declare const WAIT_SLICE_MS = 5000;
-/** Retained-output cap the tool applies when the caller does not ask for one. */
-export declare const DEFAULT_JOB_OUTPUT_BYTES: number;
-/**
- * Largest retained-output cap the tool will pass on.
- *
- * Pinned to the agent's own `MaxJobOutputBytes` (`dsh-over-ssh-agent/internal/proc/jobs.go`): the agent refuses a
- * larger value with `E_TOO_LARGE`, so clamping here keeps the caller inside the contract and lets the echoed
- * `maxOutputBytes` in the result be the truth about what was actually applied.
- */
-export declare const MAX_JOB_OUTPUT_BYTES: number;
-/** The remote root one job call targets. */
-export interface RemoteJobTarget {
-    readonly connectionId: string;
-    readonly root: string;
-}
-/** One job's state, as the tools expose it. */
-export interface RemoteJobView {
-    readonly id: string;
-    /** `running` / `exited` / `killed` / `failed`. */
-    readonly state: string;
-    readonly command: string;
-    readonly pid?: number | undefined;
-    readonly exitCode: number;
-    readonly signal?: string | undefined;
-    readonly timedOut: boolean;
-    readonly startedMs: number;
-    readonly durationMs: number;
-    readonly outputBytes: number;
-    /** Bytes dropped from the **oldest** end of the ring; non-zero means the output has a hole. */
-    readonly droppedBytes: number;
-}
-/** One job's output window, as the tools expose it. */
-export interface RemoteJobOutputView {
-    readonly id: string;
-    readonly state: string;
-    readonly data: string;
-    /** Pass this as the next `offset` to get only what is new. */
-    readonly nextOffset: number;
-    readonly droppedBytes: number;
-    readonly totalBytes: number;
-    /** The requested span was already dropped: `data` is **not** continuous output. */
-    readonly lost: boolean;
-    readonly exitCode: number;
-    readonly signal?: string | undefined;
-    readonly timedOut: boolean;
-}
-/** One `remote_exec_background` request, after validation. */
-export interface JobStartRequest {
-    readonly command: string;
-    /** Root-absolute working directory. */
-    readonly cwd: string;
-    readonly env: Readonly<Record<string, string>> | undefined;
-    /** `undefined` means **no limit** (the agent's `proc.start` treats 0/absent as unlimited). */
-    readonly timeoutMs: number | undefined;
-    readonly maxOutputBytes: number;
-    /** Text written to stdin at start (one-shot). */
-    readonly stdin?: string;
-    /** Keep stdin open so `remote_job_stdin` can append later (审计 0030). */
-    readonly interactive?: boolean;
-}
-/** What the job tools need, injected so the definitions stay testable without a transport. */
-export interface RemoteJobBackend {
-    /** Resolve an agent working directory to a remote root. */
-    resolve(cwd: string): RemoteJobTarget | undefined;
-    /**
-     * The remote directory this session added with 「添加目录」, when the cwd itself names no remote root.
-     *
-     * Same hook as the other tool backends (audit 0086 added it to `remote_exec`/`remote_grep`/`remote_glob` and
-     * left the job tools behind). Optional so every existing composition and test keeps working.
-     *
-     * @param cwd - the agent's session cwd, used as the workspace identity the add action wrote.
-     * @returns the single added remote root, a refusal naming several, or `none`.
-     */
-    resolveSessionRoot?(cwd: string, sessionId?: string): SessionRootOutcome;
-    /** Start a job and return immediately. */
-    start(target: RemoteJobTarget, request: JobStartRequest, signal: AbortSignal): Promise<RemoteJobView>;
-    /**
-     * One job's state.
-     *
-     * `waitMs` asks the agent to block (server-side) up to that long before answering — the v1
-     * long-poll that turns "60 round trips per wait" into one. Omitted means "answer immediately",
-     * which is what an agent that predates the field does anyway.
-     */
-    status(target: RemoteJobTarget, jobId: string, signal: AbortSignal, waitMs?: number): Promise<RemoteJobView>;
-    /** One job's output from `offset`; `waitMs` as in {@link status}. */
-    output(target: RemoteJobTarget, jobId: string, offset: number, signal: AbortSignal, waitMs?: number): Promise<RemoteJobOutputView>;
-    /** Request termination. */
-    kill(target: RemoteJobTarget, jobId: string, signal: AbortSignal): Promise<AgentJobKill>;
-    /**
-     * Feed a running interactive job's stdin (审计 0030).
-     *
-     * Throws `REMOTE_UNSUPPORTED` when the agent predates `proc.stdin` **or** the job was not started with
-     * `interactive` — both are capability facts the caller can only report, not work around.
-     */
-    stdin(target: RemoteJobTarget, jobId: string, request: {
-        readonly data?: string;
-        readonly dataBase64?: string;
-        readonly close?: boolean;
-    }, signal: AbortSignal): Promise<{
-        readonly id: string;
-        readonly bytes: number;
-        readonly closed: boolean;
-    }>;
-    /** Every job this connection has started. */
-    list(target: RemoteJobTarget, signal: AbortSignal): Promise<readonly RemoteJobView[]>;
-    /**
-     * Drop a settled job from the connection's list.
-     *
-     * A running job is refused by the agent: forgetting it would lose track of a live process.
-     */
-    forget(target: RemoteJobTarget, jobId: string, signal: AbortSignal): Promise<void>;
-    /** Bounded poll until the job settles; reports how long it waited. */
-    waitFor(target: RemoteJobTarget, jobId: string, timeoutMs: number, signal: AbortSignal): Promise<{
-        readonly status: RemoteJobView;
-        readonly waitedMs: number;
-    }>;
-}
-/** The slice of an agent-capable transport the job tools use. */
-export interface AgentJobCapable {
-    procStart(request: AgentProcStartRequest, signal?: AbortSignal): Promise<AgentJobStatus>;
-    /** `waitMs` is the v1 long-poll budget (server blocks up to that long); omitted = immediate. */
-    procStatus(id: string, signal?: AbortSignal, waitMs?: number): Promise<AgentJobStatus>;
-    procOutput(id: string, offset?: number, signal?: AbortSignal, waitMs?: number): Promise<AgentJobOutput>;
-    procKill(id: string, signal?: AbortSignal): Promise<AgentJobKill>;
-    procList(signal?: AbortSignal): Promise<readonly AgentJobStatus[]>;
-    /** `proc.forget`: drop a settled job from the list. Optional — an older agent answers E_METHOD. */
-    procForget?(id: string, signal?: AbortSignal): Promise<void>;
-    /** `proc.stdin`: feed a running interactive job (审计 0030). */
-    procStdin?(id: string, data: string, close: boolean, signal?: AbortSignal): Promise<{
-        readonly id: string;
-        readonly bytes: number;
-        readonly closed: boolean;
-    }>;
-    /** `proc.stdin` with base64 support (the transport-level shape the backend forwards to). */
-    jobStdin?(request: {
-        readonly id: string;
-        readonly data?: string;
-        readonly dataBase64?: string;
-        readonly close?: boolean;
-    }, signal?: AbortSignal): Promise<{
-        readonly id: string;
-        readonly bytes: number;
-        readonly closed: boolean;
-    }>;
-    /** `proc.stdin` (审计 0030): optional, because an older agent answers E_METHOD for it. */
-    procStdin?(id: string, data: string, close: boolean, signal?: AbortSignal): Promise<{
-        readonly id: string;
-        readonly bytes: number;
-        readonly closed: boolean;
-    }>;
-}
-/** What the backend needs from its owner. All injected, so it is testable without a real host. */
-export interface RemoteJobBackendDeps {
-    /** Resolve a caller's working directory to a remote root. */
-    readonly resolveRoot: (cwd: string) => RemoteJobTarget | undefined;
-    /** See {@link RemoteJobBackend.resolveSessionRoot}. */
-    readonly resolveSessionRoot?: ((cwd: string, sessionId?: string) => SessionRootOutcome) | undefined;
-    /** Acquire the connection's transport. */
-    readonly acquire: (connectionId: string) => Promise<Transport>;
-    /** Poll interval of the wait loop. */
-    readonly pollIntervalMs?: number;
-    /** Injectable clock, so a wait's deadline can be tested without sleeping. */
-    readonly now?: () => number;
-    /** Injectable sleep, so the wait loop can be tested without waiting. */
-    readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
-}
-/**
- * Whether a transport can answer the `proc.*` family.
- *
- * Structural on purpose, and for the same reason `isAgentSearchCapable` is: the agent's capability frame
- * carries no `proc` bit (`AgentCapabilities` in `agent-transport.ts`), so the honest question is "does this
- * transport implement the methods", not "does it claim a flag". A wrapper or a future transport that speaks
- * the same protocol still passes, and a test can supply one.
- *
- * Method presence is a **necessary** condition, not a sufficient one: an agent older than `proc.start`
- * implements none of them, and an agent that implements them but cannot build the Landlock fence answers
- * `E_METHOD` / `E_UNSUPPORTED`, which the transport already translates into `REMOTE_UNSUPPORTED`.
- *
- * @param transport - candidate transport.
- * @returns whether every `proc.*` method is present.
- */
-export declare function isAgentJobCapable(transport: unknown): transport is AgentJobCapable;
-/**
- * Build the job backend the entry registers.
- *
- * @param deps - injected host wiring.
- * @returns the backend consumed by {@link registerRemoteJobTools}.
- */
-export declare function createRemoteJobBackend(deps: RemoteJobBackendDeps): RemoteJobBackend;
-/** One job rendered as a single line, for the list. */
-export declare function formatJobLine(job: RemoteJobView): string;
-/** The fields the one-line job status needs; a status and an output window both carry them. */
-export interface JobStatusFields {
-    readonly id: string;
-    readonly state: string;
-    readonly exitCode: number;
-    readonly signal?: string | undefined;
-    readonly timedOut: boolean;
-    /** Absent for an output window, which does not report a duration. */
-    readonly durationMs?: number | undefined;
-    readonly outputBytes: number;
-    readonly droppedBytes: number;
-}
-/** The status line shared by the job tools' renderings. */
-export declare function formatJobStatusLine(job: JobStatusFields): string;
-/** Model-facing rendering of a started job. */
-export declare function formatJobStarted(job: RemoteJobView, cwd: string, maxOutputBytes: number): string;
-/** Model-facing rendering of one job's status. */
-export declare function formatJobStatus(job: RemoteJobView): string;
-/**
- * The job-output value as rendered: the window plus what the wait loop learned.
- *
- * Deliberately the schema's own shape (including `jobId`, and including `running`), so the renderer reads
- * exactly what the tool returned rather than a re-projection that could drift from it.
- */
-export interface JobOutputView {
-    readonly jobId: string;
-    readonly state: string;
-    readonly data: string;
-    readonly nextOffset: number;
-    readonly droppedBytes: number;
-    readonly totalBytes: number;
-    readonly lost: boolean;
-    readonly exitCode: number;
-    readonly signal?: string | undefined;
-    readonly timedOut: boolean;
-    readonly running: boolean;
-    /** Milliseconds the bounded wait actually spent; `0` when the caller did not wait. */
-    readonly waitedMs: number;
-    /** Whether the caller asked to wait. */
-    readonly waited: boolean;
-}
-/** Model-facing rendering of one job's output window. */
-export declare function formatJobOutput(view: JobOutputView): string;
-/** Model-facing rendering of a kill request. */
-export declare function formatJobKill(result: AgentJobKill): string;
-/** Model-facing rendering of the job list. */
-export declare function formatJobList(jobs: readonly RemoteJobView[]): string;
-/**
- * Validate an `env` argument.
- *
- * The rule is the one `infra/transport/shell-quote.ts` and `domain/tool-requests.ts` already enforce for
- * `remote_exec`; the third copy is deliberate only because the two existing ones are private to their
- * modules, and it is pinned by a test. Refusing by name beats the alternative the transport used to have,
- * where an unusable key was silently dropped.
- *
- * @param value - the model's `env` argument, however malformed.
- * @returns the validated map, or an error naming the offending key.
- */
-export declare function readJobEnv(value: unknown): {
-    readonly env: Readonly<Record<string, string>> | undefined;
-} | {
-    readonly error: string;
-};
-/**
- * Build the five job definitions.
- *
- * @param backend - injected implementations.
- * @returns the definitions, ready for `ctx.tools.register`.
- */
-export declare function remoteJobToolDefinitions(backend: RemoteJobBackend): ToolDefinition[];
-/**
- * Register the job tools on one context.
- *
- * @param ctx - host context with the `tools` service.
- * @param backend - injected implementations.
- * @returns a disposer removing every registration (idempotent).
- */
-export declare function registerRemoteJobTools(ctx: Context, backend: RemoteJobBackend): () => void;
-//# sourceMappingURL=remote-job-tools.d.ts.map

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

@@ -1,43 +0,0 @@
-/**
- * `remote_lsp`: ask a language server on the remote host what it knows.
- *
- * Before this, the only way to learn "is this file broken" was to run the compiler and parse its text
- * output. That works, but the parsing is where the mistakes are, and a compiler reports the whole project
- * when you changed one file. A language server answers about one document, in structured form.
- *
- * The server runs **on the remote host**, because that is where the project and its dependencies are. The
- * agent spawns it and moves bytes; the framing and JSON-RPC live in `../lsp/`.
- *
- * @module dsh-over-ssh/host/integration/tools/remote-lsp-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import { defaultServerFor, type LspRegistry } from '../lsp/lsp-registry.ts';
-import { type RemoteFileBackend } from '../fs/remote-file-tools.ts';
-/** What the LSP tool needs from its owner. */
-export interface RemoteLspToolDeps {
-    readonly backend: RemoteFileBackend;
-    readonly registry: LspRegistry;
-}
-/** One diagnostic as the tool reports it (1-based, like every line number a caller sees). */
-export interface DiagnosticView {
-    readonly line: number;
-    readonly column: number;
-    readonly endLine: number;
-    readonly endColumn: number;
-    readonly severity: string;
-    readonly message: string;
-    readonly source?: string;
-}
-/** Render a diagnostic list for the model. */
-export declare function formatDiagnostics(path: string, diagnostics: readonly DiagnosticView[]): string;
-export declare function remoteLspToolDefinitions(deps: RemoteLspToolDeps): readonly ToolDefinition[];
-/** Flatten `Hover.contents` (string | MarkupContent | MarkedString[]) to plain text. */
-export declare function hoverText(result: unknown): string;
-/** Flatten `Definition` (`Location | Location[] | LocationLink[]`) to `path:line:column` strings. */
-export declare function definitionLocations(result: unknown): string[];
-/** Register `remote_lsp` on the plugin context. */
-export declare function registerRemoteLspTools(ctx: Context, deps: RemoteLspToolDeps): () => void;
-/** Re-exported for the wiring, which needs to build the registry without importing the lsp module. */
-export { defaultServerFor };
-//# sourceMappingURL=remote-lsp-tools.d.ts.map

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

@@ -1,236 +0,0 @@
-/**
- * The agent-facing tool surface: `remote_grep`, `remote_glob`, `remote_exec`.
- *
- * Before this module the plugin could do everything *for the user* (files, terminal, completion) but exposed
- * nothing *to the model*: a turn could not search or run anything on the remote host. These three tools close
- * that hole, and every one of them is bounded and reports its truncation.
- *
- * Targeting: a tool call runs on behalf of one agent, so the agent's session cwd decides which registered root
- * answers — the same rule the file-reference provider uses. A cwd outside every root is an error, not a
- * silent fallback to the local machine.
- *
- * **Path spelling is one rule for every tool** (audit 0052 P1/P2): `cwd` / `path` accept an absolute path
- * inside the root *or* a root-relative one, resolved by `resolveUnderRoot`. An absolute path outside the root
- * is refused by name instead of being silently re-rooted, and `..` folds without leaving the root. All three
- * tools say so in their parameter descriptions, because the previous wording ("relative to the workspace
- * root") described one contract while the host enforced another.
- *
- * **Remote calls are serial within a session** (audit 0052 P5): `Promise.all` over several remote calls
- * produces no overlap. That is deliberate for a shared build server (concurrent `make` invocations trample
- * each other), and every tool says so instead of leaving the caller to discover it by timing three sleeps.
- *
- * @module dsh-over-ssh/integration/remote-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import { type SessionRootOutcome } from '../../domain/roots/session-roots.ts';
-import { type ExecRequest, type GlobRequest, type GrepRequest, type GrepOutcome, type SearchTruncation } from '../../domain/tool-requests.ts';
-/** The remote root one call targets. */
-export interface RemoteToolTarget {
-    readonly connectionId: string;
-    readonly root: string;
-}
-/** Result of a glob/listing call. */
-export interface GlobOutcome {
-    readonly paths: readonly string[];
-    readonly truncated: boolean;
-    readonly strategy: string;
-}
-/**
- * Result of a command call.
- *
- * The per-stream fields are **optional on purpose**: they are what a current agent reports, and an older
- * agent (or the shell transports, which report one `truncated` for the whole result) simply omits them.
- * {@link readExecTruncation} normalizes both shapes, so nothing here has to guess.
- */
-export interface ExecOutcome {
-    readonly exitCode: number;
-    /**
-     * The signal that ended the command, or `null`/absent when it exited on its own.
-     *
-     * Together with {@link timedOut} this is what makes `exitCode = -1` readable: the code alone cannot say
-     * whether the deadline fired or the process was signalled (audit 0064 P4).
-     */
-    readonly signal?: string | null | undefined;
-    /**
-     * Whether the answering transport's own deadline ended the command.
-     *
-     * `true` does **not** claim the remote process is dead — only that this plugin stopped waiting, which is
-     * exactly what its `timeoutMs` description promises.
-     */
-    readonly timedOut?: boolean | undefined;
-    /**
-     * Tier 1 only: the command was stopped locally (deadline or cancellation) but the host has no agent, so
-     * nothing can confirm the remote process group died. Protocol D3's `cancel` frame has no Tier 1 equivalent;
-     * this is the honest report of that limitation. The error/exit code is untouched.
-     */
-    readonly remoteMayStillRun?: boolean | undefined;
-    /** Human-readable explanation accompanying {@link remoteMayStillRun}. */
-    readonly hint?: string | undefined;
-    readonly stdout: string;
-    readonly stderr: string;
-    readonly durationMs: number;
-    /** Deprecated single flag: at least one stream was cut. */
-    readonly truncated: boolean;
-    /** Whether **stdout** was cut (agent `proc.exec` `stdoutTruncated`). */
-    readonly stdoutTruncated?: boolean | undefined;
-    /** Whether **stderr** was cut (agent `proc.exec` `stderrTruncated`). */
-    readonly stderrTruncated?: boolean | undefined;
-    /** Remote path holding the full stdout; present only when stdout was cut. */
-    readonly stdoutSpillPath?: string | undefined;
-    /** Remote path holding the full stderr; present only when stderr was cut. */
-    readonly stderrSpillPath?: string | undefined;
-}
-/** Everything the tools need, injected so the definitions stay testable without transports. */
-export interface RemoteToolBackend {
-    /**
-     * Resolve an agent working directory to a remote root.
-     *
-     * @param cwd - the agent's session cwd.
-     * @returns the target, or `undefined` when the cwd is outside every remote root.
-     */
-    resolve(cwd: string): RemoteToolTarget | undefined;
-    /**
-     * The remote directories **this session** added with 「添加目录」, as a fallback target.
-     *
-     * A session opened on a local folder has no cwd inside any remote root, so `resolve` answers `undefined`
-     * for it even after the user added a remote directory to that very session. This hook is how that
-     * directory becomes usable: the rule itself lives in `domain/roots/session-roots.ts` (pure, offline-tested),
-     * and this seam only supplies the persisted entries.
-     *
-     * Optional so every existing composition and test keeps working: absent means "no session fallback",
-     * which is exactly the pre-existing behaviour.
-     *
-     * @param cwd - the agent's session cwd, used as the workspace identity the add action wrote.
-     * @returns the single added remote root, a refusal naming several, or `none`.
-     */
-    resolveSessionRoot?(cwd: string, sessionId?: string): SessionRootOutcome;
-    /** Search one remote root. */
-    grep(target: RemoteToolTarget, request: GrepRequest, signal: AbortSignal): Promise<GrepOutcome>;
-    /** Enumerate one remote root and match paths. */
-    glob(target: RemoteToolTarget, request: GlobRequest, signal: AbortSignal): Promise<GlobOutcome>;
-    /** Run one command on the remote host. */
-    exec(target: RemoteToolTarget, request: ExecRequest, signal: AbortSignal): Promise<ExecOutcome>;
-}
-/**
- * Build the tool definitions.
- *
- * @param backend - injected implementations.
- * @returns the three definitions, ready for `ctx.tools.register`.
- */
-export declare function remoteToolDefinitions(backend: RemoteToolBackend): ToolDefinition[];
-/** The grep value as rendered: the outcome plus the echo fields the schema also carries. */
-export interface GrepView extends GrepOutcome {
-    /** Filters the search was built with (empty when none). */
-    readonly include?: readonly string[] | undefined;
-    /** The root-absolute directory that was searched. */
-    readonly path?: string | undefined;
-    /**
-     * Which bounds stopped the search (agent `truncatedReasons`), flattened onto the value because that is the
-     * shape the output schema exposes. Empty/absent means the answering tier could not say.
-     */
-    readonly truncatedReasons?: readonly string[] | undefined;
-    /** Candidate files the `include` filters removed, when the agent reported it. */
-    readonly filesFiltered?: number | undefined;
-    /** The structured report, when a caller has one in hand (the backend's own outcome). */
-    readonly truncation?: SearchTruncation | undefined;
-    /** Whether the search distinguished case; echoed because it changes what "no matches" means. */
-    readonly caseSensitive?: boolean | undefined;
-    /** Whether the search dropped the ignore rules it could apply. */
-    readonly noIgnore?: boolean | undefined;
-}
-/** The glob value as rendered: the outcome plus the semantics echo and the hint. */
-export interface GlobView extends GlobOutcome {
-    /** The pattern as the caller wrote it. */
-    readonly pattern?: string | undefined;
-    /** The root-absolute directory that was enumerated. */
-    readonly path?: string | undefined;
-    /** How the pattern was interpreted (`glob`). */
-    readonly matchSemantics?: string | undefined;
-    /** Actionable note when zero paths came back. */
-    readonly hint?: string | undefined;
-}
-/**
- * The note a zero-result glob gets.
- *
- * The rules that surprise callers are the anchoring ones, so an empty answer names them instead of leaving the
- * reader to guess whether the pattern was wrong or the files are absent:
- *
- *  - a pattern without `/` matches the **file name** at any depth, not a substring of the whole path;
- *  - a pattern with `/` is anchored at the enumerated directory, and `*` does not cross `/`;
- *  - paths are relative to the enumerated directory, so a leading `/` in the pattern matches nothing.
- *
- * A non-empty result gets no note: a glob pattern matching like a glob is not worth a sentence.
- *
- * @param pattern - the pattern as the caller wrote it.
- * @param matchCount - how many paths came back.
- * @returns the hint, or `undefined` when there is nothing worth saying.
- */
-export declare function globHint(pattern: string, matchCount: number): string | undefined;
-/**
- * Explain a failure that is really about the working directory.
- *
- * The user-visible symptom this addresses (audit 0052 P1): an unusable `cwd` surfaced as
- * `E_IO：无法启动进程：fork/exec /bin/sh: no such file or directory`, which reads as "the remote host has no
- * shell" and sends the reader off to debug the SSH environment instead of the path they passed. The message
- * below names the directory instead.
- *
- * **Why this is a message and not a pre-flight `stat`.** Two reasons, both deliberate:
- *
- *  1. A stat costs a full round trip on every single command, including the overwhelming majority that use a
- *     valid cwd; and it would still race (the directory can vanish between the check and the `chdir`).
- *  2. The signature is unambiguous: `fork/exec` failing on the shell binary is what Go's `exec.Cmd` produces
- *     when `Dir` cannot be entered, and the shell transports emit `cd: … No such file or directory` from the
- *     `cd` prefix `scriptPrefixes` builds. Both are matched below.
- *
- * It is worded as a **likely** cause rather than a diagnosis, because the plugin has not stat'd the path.
- *
- * @param cwd - the root-absolute directory the command was asked to run in.
- * @param text - the failure text: the agent error's message, or the command's stderr.
- * @param failed - whether the command actually failed (a thrown error counts).
- * @param requested - whether the caller named a `cwd` at all; without one there is nothing to explain.
- * @returns a model-facing explanation, or `undefined` when the failure is not cwd-shaped.
- */
-export declare function cwdFailureHint(cwd: string, text: string, failed: boolean, requested: boolean): string | undefined;
-/** Model-facing rendering of a search outcome. */
-export declare function formatGrep(outcome: GrepView): string;
-/**
- * The truncation paragraph: which bound was hit, and what to change.
- *
- * Exported for the same reason as the renderers: the wording is the contract. Note what it deliberately does
- * **not** say — there is no offset, cursor or page parameter, because the agent keeps no server-side state
- * between calls, so "continue from where you stopped" is not an option and must not be implied.
- *
- * @param truncation - the normalized report, when the answering tier could provide one.
- * @returns zero or more model-facing lines.
- */
-export declare function truncationLines(truncation: SearchTruncation | undefined): string[];
-/** Model-facing rendering of a glob outcome. */
-export declare function formatGlob(outcome: GlobView): string;
-/**
- * The exec value as rendered: the outcome plus the cwd diagnosis the tool adds.
- *
- * `cwdFailure` lives on the **rendered value**, not on {@link ExecOutcome}: the outcome is what the backend
- * reported, while this is the tool layer's own explanation of it.
- */
-export interface ExecView extends ExecOutcome {
-    /** Set when the command failed with the signature of an unusable `cwd`. */
-    readonly cwdFailure?: string | undefined;
-}
-/**
- * Model-facing rendering of a command outcome.
- *
- * Truncation is reported **per stream** (audit 0052 P4): "output was cut" left the reader unable to tell
- * whether the compiler's diagnostics in stderr were complete. When the agent spilled a stream, the message
- * names the remote path holding the full text so the model can go read it instead of re-running a build.
- */
-export declare function formatExec(outcome: ExecView): string;
-/**
- * Register the tools on one context.
- *
- * @param ctx - host context with the `tools` service.
- * @param backend - injected implementations.
- * @returns a disposer removing every registration (idempotent).
- */
-export declare function registerRemoteTools(ctx: Context, backend: RemoteToolBackend): () => void;
-//# sourceMappingURL=remote-tools.d.ts.map

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

@@ -1,52 +0,0 @@
-/**
- * Which remote root one tool call targets — the rule, in one place.
- *
- * Four tool modules (`remote-tools`, `remote-job-tools`, `management-tools`, `fs/remote-file-tools`) ask the
- * same two questions in the same order, and each used to carry its own copy of the answer. The copies were
- * still in sync, which is exactly the state that makes a divergence invisible: the next fix to one of them
- * (a new refusal, a new identity rule) would silently apply to one tool family and not the others. The
- * messages are model-facing, so a divergence is a behaviour change, not a cosmetic one.
- *
- * The rule itself (ADR-0012/0013):
- *
- *  1. **The session cwd decides** when it names a remote root. A session that lives on a remote workspace keeps
- *     targeting that workspace; nothing about the pre-existing behaviour moves.
- *  2. **Otherwise, the remote directories this session added with 「添加目录」** are the candidates: exactly one
- *     is used, several are refused by name rather than guessed. This is what makes a session opened on a local
- *     folder able to reach the remote directory the user explicitly added to it.
- *
- * The caller supplies the two seams because each tool family has its own backend type; the ordering, the
- * refusals and their wording are owned here.
- *
- * @module dsh-over-ssh/integration/tools/session-target
- */
-import type { ToolRunContext } from '@deepseek-ai/dsh-tools';
-import { type SessionRootOutcome, type SessionRootTarget } from '../../domain/roots/session-roots.ts';
-/** What the resolver needs from one tool family's backend. */
-export interface SessionTargetSeams<T> {
-    /** Resolve a session cwd to a target when the cwd itself names a remote root. */
-    readonly resolve: (cwd: string) => T | undefined;
-    /** The 「添加目录」 fallback; absent means "no session fallback", the pre-ADR-0013 behaviour. */
-    readonly resolveSessionRoot?: ((cwd: string, sessionId?: string) => SessionRootOutcome) | undefined;
-    /**
-     * Turn a session-added root into the family's own target shape.
-     *
-     * Needed because a session root carries no `writable` flag (the domain rule deliberately ignores it) while
-     * the file tools require one; a family without extra fields omits this and gets the target as-is.
-     */
-    readonly adapt?: ((target: SessionRootTarget) => T) | undefined;
-}
-/** The refusal when the call has no session cwd at all. */
-export declare const NO_SESSION_CWD = "\u65E0\u6CD5\u786E\u5B9A\u8C03\u7528\u65B9\u7684\u8FDC\u7AEF\u6839\uFF1A\u8BE5\u5DE5\u5177\u9700\u8981 agent \u7684\u4F1A\u8BDD\u5DE5\u4F5C\u76EE\u5F55";
-/** The refusal when the cwd names no root and the session added none (or several). */
-export declare function noRemoteRootMessage(cwd: string): string;
-/**
- * Resolve the caller's target, or fail loudly.
- *
- * @param exec - tool run context (carries the calling agent and therefore the session).
- * @param seams - the family's `resolve` / `resolveSessionRoot` / `adapt`.
- * @returns the target the call must use.
- * @throws Error naming why no single remote root could be chosen.
- */
-export declare function resolveSessionTarget<T>(exec: ToolRunContext, seams: SessionTargetSeams<T>): T;
-//# sourceMappingURL=session-target.d.ts.map