better-dsh 0.3.0 → 0.3.1

package/lib/remote/plugin.d.ts

@@ -1,8 +1,461 @@
-import { t as Schema } from "../index-DTDXUe6m.js";
 import { Context } from "@deepseek-ai/cordis";
+import { ToolRunContext } from "@deepseek-ai/dsh-tools";
+import { Readable, Writable } from "node:stream";
+import { NativeConfigSchema } from "@deepseek-ai/dsh-app-boot";
+import { StandardSchemaV1 } from "../../third_party/schemastery/node_modules/@standard-schema/spec/dist/index.js";
+import { JobId, JobRegistry } from "@deepseek-ai/dsh-jobs";
 
+//#region src/remote/ssh-targets.d.ts
+interface SshConnection {
+  readonly host: string;
+  readonly user?: string;
+  readonly port?: number;
+  readonly key?: string;
+  readonly proxyJump?: string;
+}
+/** One instance per Agent-owned driver; destroyed with its Agent/plugin owners. */
+declare class SshTargets {
+  private readonly targets;
+  register(label: string, connection: SshConnection): SshConnection;
+  get(label: string): SshConnection | undefined;
+  entries(): ReadonlyArray<readonly [string, SshConnection]>;
+  clear(): void;
+}
+/** Shared by execution, probes and file/relay consumers. extraArgs is trusted
+ * internal SSH argv (e.g. forwarding), never a model-provided shell string. */
+declare function sshArgv(connection: SshConnection, options?: {
+  tty?: boolean;
+  extraArgs?: readonly string[];
+  command?: string;
+}): string[];
+//#endregion
+//#region src/remote/copy.d.ts
+interface CopyRequest {
+  src: string;
+  dst: string;
+  verify?: boolean;
+  mkdir?: boolean;
+}
+interface TransferReceipt {
+  action: 'copy';
+  src: string;
+  dst: string;
+  verified: boolean;
+  sourceDigest?: string;
+  destinationDigest?: string;
+  bytes: number;
+  entries: number;
+  scratch?: string;
+  scope: 'transferred entries';
+  error?: string;
+}
+//#endregion
+//#region src/remote/target.d.ts
+/** 解析后的传输计划：三种 CLI 传输之一。 */
+type TargetPlan = {
+  kind: 'ssh';
+  host: string;
+  connection?: SshConnection;
+} | {
+  kind: 'docker';
+  container: string;
+} | {
+  kind: 'incus';
+  container: string;
+};
+//#endregion
+//#region src/remote/native-copy.d.ts
+interface NativeCopyReceipt {
+  action: 'copy';
+  src: string;
+  dst: string;
+  /** Native route actually used, stated as a fact (two-command routes never masquerade as one CLI). */
+  route: string;
+  /** Native argv actually executed per command, one token per element, no shell joining. */
+  argv: string[][];
+  exits: (number | null)[];
+  stdout: string[];
+  stderr: string[];
+  outputTruncated: boolean;
+  /** Native CLI success only — no independent digest was computed for this path. */
+  verified: false;
+  /** Tool-owned staging/config release: released on normal/observed exit, unknown when a channel was lost. */
+  cleanup: 'released' | 'unknown' | 'none-required';
+}
+interface RunResult {
+  exit: number | null;
+  stdout: string;
+  stderr: string;
+  outputTruncated: boolean;
+}
+//#endregion
+//#region src/remote/ssh-rsync-native-relay.d.ts
+interface RelayRsyncOptions {
+  /** Test seam: wraps every spawned SSH/daemon argv (fixture isolation). */
+  wrapArgv?: (argv: string[]) => string[];
+  /** Test seam: fixed daemon port instead of ephemeral allocation. */
+  ports?: {
+    daemon: number;
+  };
+  /** Test seam: skip route A (simulate denied forwarding). */
+  forceStdioRoute?: boolean;
+}
+//#endregion
+//#region src/remote/rsync.d.ts
+interface RsyncRequest {
+  src: string;
+  dst: string;
+  argv?: string[];
+}
+interface RsyncEndpoint {
+  path: string;
+  connection?: SshConnection;
+}
+interface RsyncReceipt extends RunResult {
+  action: 'rsync';
+  src: string;
+  dst: string;
+  argv: string[];
+  command: string;
+  /** Populated only when the CLI actually printed --stats output. */
+  itemizedChanges?: string[];
+  literalBytes?: number;
+  matchedBytes?: number;
+  sentBytes?: number;
+  receivedBytes?: number;
+  transferredBytes?: number;
+  /** Two-SSH route actually used, when applicable. */
+  route?: 'local-ssh' | 'ssh-ssh-forward' | 'ssh-ssh-stdio';
+}
+/**
+ * Native rsync with ordered caller options. Local↔SSH runs rsync directly with
+ * the endpoint's SSH identity wired as RSYNC_RSH; explicit -e/--rsh in argv
+ * overrides that wiring per rsync's own rules (the receipt shows the argv).
+ * SSH↔SSH delegates to the native relay routes (forwarding first, stdio second).
+ * No option is injected: no archive, no timeout, no dry-run, no remote owner.
+ */
+declare function runRsync(request: RsyncRequest, source: RsyncEndpoint, destination: RsyncEndpoint, signal: AbortSignal, options?: RelayRsyncOptions): Promise<RsyncReceipt>;
+//#endregion
+//#region src/remote/process.d.ts
+declare const PROCESS_CLEANUP_BOUND_MS: number;
+interface ProcessOptions {
+  stdin?: string;
+  timeoutSec?: number;
+  cwd?: string;
+  /** Hub retains raw bytes; native transports retain decoded UTF16 units. */
+  unit?: 'bytes' | 'utf16';
+  onOutput?: () => void;
+  /** Overlay on process.env (tool-built values only, e.g. RSYNC_RSH). */
+  env?: NodeJS.ProcessEnv;
+}
+/** Real detached process. Completion includes group cleanup, even after its leader closes. */
+declare function startBinaryProcess(argv: string[], options?: Pick<ProcessOptions, 'cwd' | 'timeoutSec' | 'env'>): {
+  stdout: Readable;
+  stderr: Readable;
+  stdin: Writable;
+  cancel(): void;
+  done: RemoteProcess['done'];
+  diagnostic(): string | undefined;
+};
+/** Text adapter over the same owned process-group lifecycle as binary pipelines. */
+declare function startOneShot(argv: string[], options?: ProcessOptions): RemoteProcess;
+//#endregion
+//#region src/remote/oneshot.d.ts
+interface OneShotOptions {
+  stdin?: string;
+  timeoutSec?: number;
+}
+interface OneShotResult {
+  exit: number | null;
+  timedOut: boolean;
+  stdout: string;
+  stderr: string;
+  durationMs: number;
+  outputStats?: StreamOutputStats;
+}
+//#endregion
+//#region src/remote/status.d.ts
+interface ProbeOptions {
+  connectTimeoutSec?: number;
+  hardTimeoutSec?: number;
+  runner?: (argv: string[], opts?: OneShotOptions) => Promise<OneShotResult>;
+}
+//#endregion
+//#region src/remote/roster.d.ts
+interface RosterOptions {
+  byosshLabels?: readonly string[];
+  /** 测试缝：替代 runOneShot 的容器扫描执行器。 */
+  runner?: (argv: string[], opts?: OneShotOptions) => Promise<OneShotResult>;
+  /** 测试缝：替代 ~/.ssh/config 读取。 */
+  readSshConfig?: () => Promise<string>;
+  hardTimeoutSec?: number;
+}
+//#endregion
+//#region src/remote/driver.d.ts
+type RemoteCallParams = RemoteInput;
+interface RemoteCallResult {
+  mode: 'oneshot' | 'pty';
+  target: string;
+  exit: number | null;
+  cwd: string | null;
+  timedOut: boolean;
+  reconnected: boolean;
+  stdout: string;
+  stderr?: string;
+  durationMs: number;
+  truncated?: number;
+  outputStats?: StreamOutputStats;
+  outputStatsUnavailable?: boolean;
+  /** `byop:<label>` 调用面：本会话的 label（模型自选、即复用入口）。transport target 会话不带。 */
+  session?: string;
+  /** 引导/教学行（同 label 重复给 spawn 时的「可省略 spawn」提示等）；无则省略。 */
+  notice?: string;
+}
+interface RemoteAuditRecord {
+  target: string;
+  cmd: string;
+  cwd?: string;
+  exit?: number | null;
+  durationMs?: number;
+  error?: string;
+}
+interface RemoteDriverOptions {
+  /** Fixture transport seam; normal consumers use the canonical native SSH builder. */
+  /** Fixture transport seam for native copy CLIs (scp/docker/incus argv isolation). */
+  nativeArgvFor?: (argv: string[]) => string[];
+  getHub?: () => HubRemoteTransport | undefined;
+  execTimeoutSec?: number;
+  idleTtlSec?: number;
+  maxOutputChars?: number;
+  onAudit?: (r: RemoteAuditRecord) => void;
+  oneshotArgvFor?: (plan: TargetPlan, cmd: string, options: {
+    cleanupTag?: string;
+  }) => string[];
+  ptyArgvFor?: (plan: TargetPlan) => string[];
+  spawnArgvFor?: (spawnCommand: string) => string[];
+  probeRunner?: ProbeOptions['runner'];
+  /** 测试缝：roster 扫描执行器（bare-name 解析复用）。 */
+  rosterRunner?: RosterOptions['runner'];
+  /** 测试缝：ssh config 读取（bare-name 解析复用）。 */
+  sshConfigReader?: () => Promise<string>;
+}
+/** 双轨调度器（spec §七 Phase 2）：参数校验 → 路由 → oneshot 子进程 / pty 会话池。 */
+declare class RemoteDriver {
+  private readonly opts;
+  private readonly sshTargets;
+  private readonly pool;
+  private readonly hubOwner;
+  private readonly hubProviders;
+  private readonly processes;
+  private readonly starting;
+  private readonly fileAbort;
+  private disposed;
+  private disposal;
+  constructor(opts?: RemoteDriverOptions);
+  call(params: RemoteCallParams, callCtx?: {
+    sessionKey?: string;
+  }): Promise<RemoteCallResult>;
+  /** Native-first copy routing (spec: remote-native-shortcut): CLI peers run
+   * their native CLI verbatim; only Hub↔local↔local stays on the staged tree
+   * lane with verify/mkdir. Mixed pairs (Hub↔CLI peer) are refused: Hub has no
+   * native CLI and the tree lane has no CLI options. */
+  copy(request: CopyRequest & {
+    argv?: unknown;
+    pullArgv?: unknown;
+    pushArgv?: unknown;
+  }, signal: AbortSignal, callCtx?: {
+    sessionKey?: string;
+  }): Promise<TransferReceipt | NativeCopyReceipt>;
+  rsync(request: RsyncRequest, signal: AbortSignal, callCtx?: {
+    sessionKey?: string;
+  }): Promise<RsyncReceipt>;
+  /** Only called from JobSpec.run: admission precedes local file reads and discovery. */
+  start(input: RemoteInput, signal: AbortSignal): Promise<RemoteProcess>;
+  private startPrepared;
+  private nativeProcess;
+  private own;
+  /** Ruling 16/17：on-demand 探测 + 会话层，两行如实陈述。 */
+  /**
+   * Ruling P20 + PTY 候选表末位：裸名按名匹配——ssh config 字面 host → docker → incus（本地廉价扫描，
+   * 撞名 ssh 优先），三段全不中再看池内活 PTY label，最后才是默认 ssh（交原生错误）。
+   * 位置即优先级：现有三段一位不挪。选择器前缀的 target 不经此路径。
+   */
+  private resolveBareName;
+  /** Ruling P19：roster = 注意力入口——本地廉价扫描（ssh config/docker ps/incus list + 池内活会话），零拨号。
+   *  活的 pty 会话按调用方 agent session 过滤（2026-10-03 裁决）：ssh/docker/incus 是**公共静态配置**，
+   *  而活会话是**操作环境**——复用别的 agent 留下的 shell 等于继承未知状态，且两个 agent 各开一条线
+   *  的代价可忽略。BYO-PTY 天然是活的，于是自然落进这个 scope，无需另立规则。 */
+  roster(callCtx?: {
+    sessionKey?: string;
+  }): Promise<string>;
+  status(target: string, callCtx?: {
+    sessionKey?: string;
+  }): Promise<string>;
+  /** PTY 状态行：纯池内读取，零拨号（label 从来不是可拨目标）。 */
+  private ptyStatus;
+  /** Ruling 13：审计 best-effort——钩子抛错不得影响命令路径（成功被毒化成失败+双重审计）。 */
+  private audit;
+  /** Registration never dials; response reveals labels only, not credentials. */
+  registerSsh(target: string, connection: SshConnection): string;
+  private byosshPlan;
+  /** Single target resolver for later copy/rsync; BYO identities cannot be
+   * independently re-resolved through the origin's alias table. */
+  resolveConnectionTarget(target: string, callCtx?: {
+    sessionKey?: string;
+  }): Promise<TargetPlan>;
+  private route;
+  private execute;
+  /** BYO-PTY 通道：label 即池键（agent 前缀之外），spawn 只在 label 尚不存在时被接受。
+   * 三分支 —— 建（无会话）/ 复用（无 spawn，或有 spawn 且与创建来源相同）/ **冲突（有 spawn 且来源不同：不执行任何命令）**。 */
+  private ptyCall;
+  hasHub(): boolean;
+  private requireHub;
+  private assertOpen;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/remote/hub-contract.d.ts
+interface RemoteInput {
+  target?: string;
+  spawn?: string;
+  ssh?: SshConnection;
+  cmd?: string;
+  script?: string;
+  stdin?: string;
+  mode?: 'oneshot' | 'pty';
+  timeout?: number;
+}
+interface PreparedRemoteInput {
+  target: string;
+  spawn?: string;
+  ssh?: SshConnection;
+  cmd: string;
+  stdin?: string;
+  mode?: 'oneshot' | 'pty';
+  timeout?: number;
+}
+/** Counters exclude diagnostic banners. dropped is ring eviction; total-returned is all omitted output. */
+type OutputStats = {
+  unit: 'utf16' | 'bytes';
+  total: number;
+  retained: number;
+  dropped: number;
+  returned: number;
+  retentionLimit: number;
+};
+type StreamOutputStats = {
+  stdout: OutputStats;
+  stderr?: OutputStats;
+};
+interface RemoteProcess {
+  cancel(reason?: string): void;
+  done: Promise<{
+    exit: number | null;
+    timedOut: boolean;
+    durationMs: number;
+    cancelled?: boolean;
+  }>;
+  /** diagnostic is executor-generated text, not process output; excluded from byte cursor and counters. */
+  read(channel: 'stdout' | 'stderr', fromByte: number): {
+    text: string;
+    nextOffset: number;
+    lossy: boolean;
+    stats?: OutputStats;
+    diagnostic?: string;
+  };
+}
+interface BinaryFileEndpoint {
+  exportTree(path: string, signal: AbortSignal): Promise<NodeJS.ReadableStream>;
+  importTree(path: string, source: NodeJS.ReadableStream, options: {
+    mkdir: boolean;
+    signal: AbortSignal;
+  }): Promise<void>;
+  digest(path: string, signal: AbortSignal, selection?: readonly string[]): Promise<{
+    sha256: string;
+    bytes: number;
+    entries: number;
+  }>;
+}
+interface HubTarget {
+  id: string;
+  label: string;
+  execEnabled: boolean;
+}
+interface HubRemoteTransport {
+  protocol: 1;
+  listTargets(): readonly HubTarget[];
+  start(machine: string, input: PreparedRemoteInput, owner: string): Promise<RemoteProcess>;
+  pty(machine: string, cmd: string, owner: string, options: {
+    stdin?: string;
+    timeout?: number;
+  }): Promise<RemoteCallResult>;
+  fileEndpoint(machine: string): BinaryFileEndpoint;
+  releaseOwner(owner: string): Promise<void>;
+}
+//#endregion
+//#region src/remote/output-ring.d.ts
+/** Byte-addressed decoded output: mid-codepoint cursors skip forward and explicitly report loss. */
+declare function readUtf8Tail(bytes: Buffer, totalBytes: number, fromByte: number): {
+  text: string;
+  nextOffset: number;
+  lossy: boolean;
+};
+/** Native/PTY retention is UTF16 units; cursor offsets remain real UTF8 bytes. Input is decoded text. */
+declare class Utf16TailRing {
+  readonly capacity: number;
+  text: string;
+  total: number;
+  private totalBytes;
+  constructor(capacity?: number);
+  push(text: string): void;
+  stats(returned?: number): OutputStats;
+  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
+}
+/** Raw byte retention for Hub oneshot. Tail/read starts skip partial UTF8 prefixes, never invent replacement characters. */
+declare class ByteTailRing {
+  readonly capacity: number;
+  total: number;
+  private chunks;
+  private retained;
+  constructor(capacity?: number);
+  push(chunk: Buffer): void;
+  tail(maxBytes?: number): Buffer;
+  stats(returned?: number): OutputStats;
+  read(fromByte: number): ReturnType<typeof readUtf8Tail>;
+}
+//#endregion
+//#region src/remote/jobs.d.ts
+declare module '@deepseek-ai/dsh-jobs' {
+  interface JobKindMap {
+    remote: 'remote';
+  }
+}
+/** No preparation or discovery before the official registry's admission. */
+declare function startRemoteJob(registry: JobRegistry, input: RemoteInput, exec: ToolRunContext, driver: RemoteDriver): JobId;
+//#endregion
+//#region src/remote/archive.d.ts
+declare const FILE_FRAME_BYTES: number;
+declare const FILE_MAX_ENTRIES = 10000;
+declare const FILE_MAX_METADATA: number;
+declare function checkAbsolute(p: string): void;
+declare function checkSelection(selection: readonly string[]): void;
+/** Internal worker ownership hooks, not a second endpoint contract. */
+interface LocalFileResources {
+  receiveRoot?: string;
+  temporary?(path: string, active: boolean): Promise<void>;
+}
+declare function localFileEndpoint(resources?: LocalFileResources): BinaryFileEndpoint;
+//#endregion
+//#region src/remote/file-worker.d.ts
+declare function runFileWorker(request: {
+  action: 'export' | 'import' | 'digest';
+  path: string;
+  mkdir: boolean;
+  root: string;
+  selected: boolean;
+}): Promise<void>;
+//#endregion
 //#region src/remote/plugin.d.ts
-
 declare const name = "dashr-remote";
 declare const inject: string[];
 /** 运行参数旋钮（Ruling P18）：无别名表面——容器一律显式 'docker:' / 'incus:' 前缀。 */
@@ -11,14 +464,15 @@ interface RemoteRowConfig {
   idleTtlSec: number;
   maxOutputChars: number;
 }
-declare const Config: Schema<RemoteRowConfig>;
+type RemoteConfigValidator = ((value?: unknown) => RemoteRowConfig) & StandardSchemaV1<unknown, RemoteRowConfig> & NativeConfigSchema;
+declare const Config: RemoteConfigValidator;
 /** MUST stay an arrow（RM0 plugin.ts 同注：function 声明会被 cordis 当构造器 new 掉，返回的 disposer 丢失）。 */
 declare const apply: (ctx: Context, config: RemoteRowConfig) => (() => void);
 declare const _default: {
   name: string;
   inject: string[];
-  Config: Schema<RemoteRowConfig>;
+  Config: RemoteConfigValidator;
   apply: (ctx: Context, config: RemoteRowConfig) => (() => void);
 };
 //#endregion
-export { Config, RemoteRowConfig, apply, _default as default, inject, name };
+export { type BinaryFileEndpoint, ByteTailRing, Config, FILE_FRAME_BYTES, FILE_MAX_ENTRIES, FILE_MAX_METADATA, type HubRemoteTransport, type HubTarget, type OutputStats, PROCESS_CLEANUP_BOUND_MS, type PreparedRemoteInput, RemoteConfigValidator, type RemoteInput, type RemoteProcess, RemoteRowConfig, type RsyncEndpoint, type RsyncReceipt, type RsyncRequest, type SshConnection, SshTargets, type StreamOutputStats, Utf16TailRing, apply, checkAbsolute, checkSelection, _default as default, inject, localFileEndpoint, name, readUtf8Tail, runFileWorker, runRsync, sshArgv, startBinaryProcess, startOneShot, startRemoteJob };