dsh-over-ssh 0.1.0 → 0.1.1

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

@@ -1,295 +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-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-remote-workspace/integration/remote-job-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-import type { Transport } from '../infra/transport/transport.ts';
-import type { AgentJobKill, AgentJobOutput, AgentJobStatus, AgentProcStartRequest } from '../infra/transport/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-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;
-    /** 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[]>;
-    /** 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.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;
-    /** 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 five 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/remote-tool-backend.d.ts

@@ -1,97 +0,0 @@
-/**
- * The `remote_grep` / `remote_glob` / `remote_exec` backend.
- *
- * Extracted from the plugin entry for two reasons: the entry was growing a second responsibility, and the
- * Tier 2/Tier 1 decision below could not be exercised by any test while it lived inline (the tools'
- * end-to-end verification needs to build exactly this object against a real host).
- *
- * Two decisions worth naming:
- *
- *  - **Structural capability checks, not `instanceof`.** The agent path is chosen by asking the transport what
- *    it can do (`agentCapabilities.grep` + a `searchGrep` method), so a wrapper or a future transport that
- *    speaks the same protocol still gets Tier 2 — and a test can supply one.
- *  - **Tier 2 first, Tier 1 always available.** The agent measured ~0.16 ms/file for scans against ~635 ms per
- *    per-file round trip (审计 0009), so search prefers it; when it is absent or fails to answer the shell
- *    path takes over. Failing over is reported through `strategy`, never hidden.
- *
- * @module dsh-remote-workspace/integration/remote-tool-backend
- */
-import type { Transport } from '../infra/transport/transport.ts';
-import type { RemoteToolBackend } from './remote-tools.ts';
-/** One search hit as the agent transport reports it (only the fields this module reads). */
-export interface AgentSearchHit {
-    readonly path: string;
-    readonly line: number;
-    readonly text: string;
-}
-/** The agent search result shape this module consumes. */
-export interface AgentSearchOutcome {
-    readonly matches: readonly AgentSearchHit[];
-    readonly strategy: string;
-    readonly truncated: boolean;
-    /** Which bounds stopped the scan (agent `truncatedReasons`); empty when the agent did not say. */
-    readonly truncatedReasons?: readonly string[] | undefined;
-    /** Candidate files the `include` filters removed; `undefined` when the agent did not say. */
-    readonly filesFiltered?: number | undefined;
-}
-/** The slice of an agent-capable transport the backend uses. */
-export interface AgentSearchCapable {
-    readonly agentCapabilities: {
-        readonly grep?: boolean;
-    };
-    searchGrep(request: {
-        readonly paths: readonly string[];
-        readonly query: string;
-        readonly literal?: boolean;
-        /** Case-insensitive matching; the agent's own default is `true`. */
-        readonly ignoreCase?: boolean;
-        /** Drop VCS ignore rules and the agent's built-in noise directories (audit 0064 P3). */
-        readonly noIgnore?: boolean;
-        readonly maxResults?: number;
-        /** Filename patterns to keep, e.g. `*.cpp` (audit 0052 P10). */
-        readonly include?: readonly string[];
-    }, signal?: AbortSignal): Promise<AgentSearchOutcome>;
-}
-/** What the backend needs from its owner. All injected, so it is testable without a real host. */
-export interface RemoteToolBackendDeps {
-    /**
-     * Resolve a caller's working directory to a remote root.
-     *
-     * @param cwd - the agent's session cwd.
-     * @returns the target, or `undefined` when no remote root contains it.
-     */
-    readonly resolveRoot: (cwd: string) => {
-        readonly connectionId: string;
-        readonly root: string;
-    } | undefined;
-    /**
-     * Acquire the connection's transport.
-     *
-     * @param connectionId - configured connection id.
-     * @returns the transport (the caller owns its lifetime).
-     */
-    readonly acquire: (connectionId: string) => Promise<Transport>;
-    /**
-     * Enumerate a remote root (the shared index).
-     *
-     * @param connectionId - connection owning the root.
-     * @param root - backend-absolute root path.
-     * @param signal - caller cancellation.
-     * @returns enumerated paths, whether a cap was hit, and which strategy answered.
-     */
-    readonly enumerate: (connectionId: string, root: string, signal?: AbortSignal) => Promise<{
-        readonly paths: readonly string[];
-        readonly truncated: boolean;
-        readonly source: string;
-    }>;
-}
-/** Whether a transport can answer agent-side searches. */
-export declare function isAgentSearchCapable(transport: unknown): transport is AgentSearchCapable;
-/**
- * Build the tool backend the entry registers.
- *
- * @param deps - injected host wiring.
- * @returns the backend consumed by {@link registerRemoteTools}.
- */
-export declare function createRemoteToolBackend(deps: RemoteToolBackendDeps): RemoteToolBackend;
-//# sourceMappingURL=remote-tool-backend.d.ts.map

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

@@ -1,206 +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-remote-workspace/integration/remote-tools
- */
-import type { Context } from '@deepseek-ai/cordis';
-import { type ToolDefinition } from '@deepseek-ai/dsh-tools';
-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;
-    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;
-    /** 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 (`substring`). */
-    readonly matchSemantics?: string | undefined;
-    /** Actionable note when zero paths came back, or when the caller probably expected a glob. */
-    readonly hint?: string | undefined;
-}
-/**
- * Whether a pattern looks like a glob, and if so what to do instead.
- *
- * Exported because the wording is part of the tool's contract: the tool is named `remote_glob` but matches
- * substrings, so "0 results" has two very different meanings that must not look alike (audit 0052 P3).
- *
- * @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