@swoop111/dsh-tool-fs 0.0.0-stage → 0.2.0-rc.2

package/lib/types/sandbox.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The sandbox-escalation API shared by the `write` and `edit` tools: the
+ * per-call policy resolution, the advertised escalation fields, and the denial-marker
+ * mapping — all delegating the vocabulary and the fail-closed approval
+ * sequence to `@deepseek-ai/dsh-sandbox` (the same pieces `@deepseek-ai/dsh-tool-bash`
+ * uses), so bash and fs escalate identically. Built ONCE per plugin from
+ * `ctx.fs.sandboxMode` (the capability fact — is a confining backend mounted?)
+ * and shared by both mutating tools.
+ *
+ * @module @deepseek-ai/dsh-tool-fs/sandbox
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+import type { SandboxExecutionPolicy, SandboxMode } from '@deepseek-ai/dsh-sandbox';
+/** The two escalation arguments a mutating tool may carry (advertised only under a confining backend). */
+export interface FsEscalationArgs {
+    sandbox_permissions?: string;
+    justification?: string;
+}
+/** The schema fields for the escalation arguments, spread into a tool's `parameters` when a confining backend is mounted. */
+export interface EscalationSchemaFields {
+    sandbox_permissions: {
+        type: 'string';
+        enum: string[];
+        description: string;
+    };
+    justification: {
+        type: 'string';
+        description: string;
+    };
+}
+/**
+ * The filesystem escalation API: advertisement gating, per-call policy
+ * resolution, the one-approved wider retry, and denial-marker mapping. A pure
+ * product of `ctx` at plugin apply time.
+ */
+export declare class FsSandboxController {
+    private readonly ctx;
+    /** The escalation targets this composition advertises (`[]` when no confining backend is mounted). */
+    readonly escalationModes: readonly SandboxMode[];
+    /** Shared per-session policy resolver, required by a confining backend. */
+    private readonly policy;
+    constructor(ctx: Context);
+    /**
+     * The escalation schema fields for a mutating tool's `parameters`. Call it
+     * only under a confining backend (guard on {@link escalationModes}); the
+     * enum pins the closed target vocabulary, the strict-wider check happens per
+     * call at execution.
+     * @returns the two escalation parameter specs.
+     */
+    schemaFields(): EscalationSchemaFields;
+    /**
+     * The policy to stamp onto this mutation: an approved escalation grant (a
+     * strictly wider retry resolved through `ctx.approval` before anything
+     * executes), else the session's standing mode. Repeating the standing mode
+     * requires no approval. The calling session's cwd is
+     * always carried as the workspace root. Validates the escalation argument
+     * pairing first.
+     * @param toolName - the mutating tool's name, for the approval audit trail.
+     * @param args - the call's escalation arguments.
+     * @param exec - the tool-execution context (agent, callId, signal).
+     * @returns the policy to pass to the mutation, or undefined for an
+     *   unsandboxed backend.
+     */
+    resolvePolicy(toolName: string, args: FsEscalationArgs, exec: ToolExecution): Promise<SandboxExecutionPolicy | undefined>;
+    /**
+     * Map a thrown provider error for the model: a `FS_SANDBOX_DENIED` becomes a
+     * `FsError` whose text is the shared `[sandbox: …]` denial marker plus the
+     * same-turn escalation hint, so a policy denial reads identically to bash's
+     * WHILE keeping the structured `FS_SANDBOX_DENIED` code — `ToolRuntime`
+     * populates `result.error` only for `HarnessError` instances, so a plain
+     * `Error` would strip the code retry/observers key off. Any other error
+     * passes through unchanged. A `FS_SANDBOX_DENIED` only arises under a
+     * confining backend, which always advertises the escalation fields, so the
+     * hint always applies here.
+     * @param error - the error thrown by the mutation.
+     * @param policy - the policy stamped onto the call (names the mode in the marker).
+     * @returns the error to throw — the marker `FsError` for a sandbox denial, else the original.
+     */
+    mapError(error: unknown, policy: SandboxExecutionPolicy | undefined): unknown;
+}
+//# sourceMappingURL=sandbox.d.ts.map

package/lib/types/session-cwd.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Derive the working directory a filesystem tool resolves relative paths against: the calling
+ * agent's per-session workspace (`exec.agent.session.header.cwd`), so each session's
+ * `read`/`write`/`edit` act on its workspace, not the server's launch directory.
+ * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
+ * `process.cwd()` at the tool boundary.
+ * @module @deepseek-ai/dsh-tool-fs/session-cwd
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools';
+/**
+ * The session workspace cwd for this call, or `undefined` when none applies.
+ * @param exec - the tool-execution context; only its optional `agent` is read.
+ * @returns the calling agent's session cwd, or undefined for a non-agent caller (the backend then applies its own default).
+ */
+export declare function sessionCwd(exec: ToolExecution): string | undefined;
+/**
+ * Resolution options shared by all model-facing filesystem tools.
+ * @param exec - the tool-execution context supplying session cwd and cancellation.
+ * @param policyWorkspaceRoot - resolved per-call root, when a mutation carries sandbox policy.
+ * @returns provider resolution options for the current tool call.
+ */
+export declare function sessionResolveOptions(exec: ToolExecution, policyWorkspaceRoot?: string): {
+    cwd?: string;
+    signal?: AbortSignal;
+};
+//# sourceMappingURL=session-cwd.d.ts.map

package/lib/types/structure.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Structural analysis of file text for read-window completion: markdown
+ * fences, bracket nesting, and indentation blocks. The analyzers are pure
+ * functions over already-delivered text; they decide which construct a window
+ * boundary falls inside, and how many neighbouring lines close an open one.
+ *
+ * Precision is traded for never touching delivered content: a wrong verdict
+ * only costs a few appended real lines, or a silent non-completion. String
+ * literals are scanned per line (an unterminated quote never carries into the
+ * next line), line comments and C-style block comments are skipped, and
+ * brackets inside an open fence are content, so prose and code samples do not
+ * fabricate unbalanced constructs.
+ * @module @deepseek-ai/dsh-tool-fs/structure
+ */
+/** Which structural rule produced a completion. */
+export type CompletionRule = 'fence' | 'brace' | 'indent';
+/** An unbalanced construct at a window boundary. */
+export type OpenConstruct = {
+    kind: 'fence';
+    /** The opening fence marker, e.g. ` ``` ` or `~~~~`. */
+    marker: string;
+    /** Index of the line that opened the construct, within the scanned lines. */
+    lineIndex: number;
+} | {
+    kind: 'brace';
+    /** Bracket levels still open at the boundary. */
+    depth: number;
+    /** Index of the innermost opening line, within the scanned lines. */
+    lineIndex: number;
+} | {
+    kind: 'indent';
+    /** Indent width of the open block's body. */
+    width: number;
+    /** Index of the block header line, within the scanned lines. */
+    lineIndex: number;
+};
+/** The construct a window starts inside, and the line that opened it. */
+export interface HeadContext {
+    /** Which rule found the construct. */
+    kind: CompletionRule;
+    /** Index into the preceding lines of the line that opened the construct. */
+    startIndex: number;
+}
+/**
+ * The construct a window ends inside.
+ * @param lines - the delivered window lines, in file order.
+ * @returns the construct to close, or `undefined` when the tail is balanced.
+ */
+export declare function detectOpenTail(lines: readonly string[]): OpenConstruct | undefined;
+/**
+ * The construct a window starts inside, resolved from the lines that precede it.
+ * A fence outranks a bracket block, which outranks an indented block. A
+ * construct opened before the supplied preceding lines is not provable and
+ * reports nothing, so the completion stays silent rather than guessing.
+ * @param window - the delivered window lines, in file order.
+ * @param preceding - the lines immediately before the window, in file order; the last entry is the line that precedes the window.
+ * @returns the leading context, or `undefined` when the window starts at a construct boundary.
+ */
+export declare function detectOpenHead(window: readonly string[], preceding: readonly string[]): HeadContext | undefined;
+/**
+ * How many of the following lines close an open construct.
+ * @param construct - the construct {@link detectOpenTail} found.
+ * @param appended - the lines following the window, in file order.
+ * @returns the count of lines to append, or `0` when the sequence closes nothing.
+ */
+export declare function closureLength(construct: OpenConstruct, appended: readonly string[]): number;
+//# sourceMappingURL=structure.d.ts.map

package/lib/types/write.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Model-facing full-file write. It obtains an optional intent from the single policy slot, calls
+ * `ctx.fs.writeText` without a stat, then records the resulting version; no policy means an
+ * unconditional atomic create-or-overwrite.
+ * @module @deepseek-ai/dsh-tool-fs/src/write
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { FsWriteOutcome } from '@deepseek-ai/dsh-fs';
+import type { Session } from '@deepseek-ai/dsh-session';
+import type { FsSandboxController } from './sandbox.ts';
+/**
+ * Tuning for the drifted-path hint: on a create, a verified high-similarity
+ * existing path is disclosed as a note — never rewritten.
+ */
+export interface WriteHintTuning {
+    /** Master switch for the drifted-path hint. */
+    pathHint: boolean;
+    /**
+     * Absolute path arguments of the session's prior successful tool calls, most
+     * recent first — the similarity matcher's history source.
+     */
+    priorPaths(session: Session | undefined, limit?: number): string[];
+}
+/** Plugin-config shape for the write hint tuning. */
+export interface WriteRepairConfig {
+    /** Disable the drifted-path hint so creates stay silent (default enabled). */
+    pathHint?: boolean;
+}
+/**
+ * Validate value constraints the schema DSL can't express: only a non-blank
+ * `file_path` — an empty `content` is legitimate (it writes an empty file).
+ * @param args - the schema-validated raw tool arguments.
+ * @returns the camelCased input; `content` passes through untouched.
+ */
+export declare function parseWriteArgs(args: {
+    file_path: string;
+    content: string;
+}): {
+    filePath: string;
+    content: string;
+};
+/**
+ * Format a write outcome as one model-facing text block body.
+ * @param displayPath - the backend-resolved path rendered in the envelope's `<path>` element.
+ * @param outcome - the write outcome; its `operation` selects the Created/Updated wording.
+ * @param hint - the drifted-path disclosure appended inside the content block, or undefined.
+ * @returns the model-facing confirmation envelope (no file content is echoed back).
+ */
+export declare function formatWriteOutput(displayPath: string, outcome: Pick<FsWriteOutcome, 'operation'>, hint?: string): string;
+/**
+ * Register the `write` tool and its scope-aware system-prompt guidance.
+ * @param ctx - the plugin context; registrations are effects scoped to it, and execution uses its `fs` service.
+ * @param sandbox - the shared sandbox-escalation API (advertisement, mode stamping, denial mapping).
+ * @param hints - the drifted-path hint tuning; disabled keeps creates silent.
+ */
+export declare function applyWriteTool(ctx: Context, sandbox: FsSandboxController, hints: WriteHintTuning): void;
+//# sourceMappingURL=write.d.ts.map

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@swoop111/dsh-tool-fs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Model-facing filesystem tools (read, write, edit) over the DeepSeek Harness filesystem seam (ctx.fs)",
+  "version": "0.2.0-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/fs/tool-fs"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "diff": "^9.0.0",
+    "@deepseek-ai/schemastery": "~3.18.4",
+    "@deepseek-ai/dsh-util-code-language": "0.2.0-rc.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-arg-repair": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs-edit-repair": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-agent-loop": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-arg-repair": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-attachment": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs-local": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs-edit-repair": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-fs-observation-policy": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm-deepseek-api-key": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session": "0.2.0-rc.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-scope": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-session-projection": "0.2.0-rc.2"
+  }
+}