@tianshu-ai/tianshu 0.3.0

package/plugins/files/dist/tools/list-dir.js

@@ -0,0 +1,104 @@
+// list_dir — agent tool that lists directory contents.
+//
+// Visibility scope is the per-user home (per-user-tools rule, see
+// path-helper.ts). Returns a JSON-friendly tool-result; the agent
+// then decides how to render or chain calls.
+import fs from "node:fs";
+import path from "node:path";
+import { Type } from "typebox";
+import { resolveInUserHome, toWorkspaceUri, PathOutsideRootError, } from "./path-helper.js";
+const MAX_ENTRIES = 5000;
+/** Build the tool definition (Type schema) and a separate executor.
+ *  Keeping these separate lets the chat handler register the schema
+ *  with pi-ai while invoking the executor inside its own loop with
+ *  the per-request user home. */
+export function listDirSchema() {
+    return {
+        name: "list_dir",
+        description: "List the entries in a directory inside the workspace. Use this to discover " +
+            "what files exist. Paths are interpreted relative to the workspace root; " +
+            "prefer relative paths (`notes`, `src/foo`) over leading-slash forms. " +
+            "Use `.` (or omit `path`) for the workspace root itself. " +
+            "NOTE: a leading-slash path here means \"workspace root\", NOT the sandbox " +
+            "OS root \u2014 inside `exec`, the same `/foo` would resolve to the sandbox " +
+            "filesystem root. Stick to relative paths to keep both worlds aligned. " +
+            "Returns at most 5000 entries; if truncated the response says so.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: 'Directory path relative to the workspace root, e.g. ".", "notes", or "src/foo". Default "." (workspace root).',
+            }),
+        }),
+    };
+}
+export function executeListDir(userHome, args) {
+    const requested = args.path ?? "/";
+    let resolved;
+    try {
+        resolved = resolveInUserHome(userHome, requested);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { ok: false, text: `path is outside the workspace: ${requested}` };
+        }
+        throw err;
+    }
+    // Auto-create the user home on first read. Sub-paths are NOT auto-
+    // created — that's a 404 the agent should observe.
+    if (resolved === path.resolve(userHome) && !fs.existsSync(resolved)) {
+        fs.mkdirSync(resolved, { recursive: true });
+    }
+    if (!fs.existsSync(resolved)) {
+        return { ok: false, text: `not found: ${requested}` };
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+        return { ok: false, text: `not a directory: ${requested}` };
+    }
+    const dirents = fs.readdirSync(resolved, { withFileTypes: true });
+    const truncated = dirents.length > MAX_ENTRIES;
+    const slice = dirents.slice(0, MAX_ENTRIES);
+    const entries = slice.map((d) => {
+        const full = path.join(resolved, d.name);
+        let size = 0;
+        let modifiedMs = 0;
+        try {
+            const s = fs.statSync(full);
+            size = s.size;
+            modifiedMs = s.mtimeMs;
+        }
+        catch {
+            /* swallow — broken symlinks etc. */
+        }
+        const type = d.isDirectory()
+            ? "directory"
+            : d.isFile()
+                ? "file"
+                : "other";
+        return {
+            name: d.name,
+            path: toWorkspaceUri(userHome, full),
+            type,
+            size,
+            modifiedMs,
+        };
+    });
+    // Directories first, then files alphabetically.
+    entries.sort((a, b) => {
+        if (a.type !== b.type) {
+            if (a.type === "directory")
+                return -1;
+            if (b.type === "directory")
+                return 1;
+        }
+        return a.name.localeCompare(b.name);
+    });
+    const lines = entries.map((e) => e.type === "directory" ? `${e.path}/` : `${e.path}  (${e.size} bytes)`);
+    const header = `Directory ${toWorkspaceUri(userHome, resolved)} (${entries.length} ${entries.length === 1 ? "entry" : "entries"}${truncated ? ", truncated" : ""}):`;
+    return {
+        ok: true,
+        text: [header, ...lines].join("\n"),
+        entries,
+        truncated,
+    };
+}
+//# sourceMappingURL=list-dir.js.map

package/plugins/files/dist/tools/list-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-dir.js","sourceRoot":"","sources":["../../src/tools/list-dir.ts"],"names":[],"mappings":"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"}

package/plugins/files/dist/tools/load-prompt.d.ts

@@ -0,0 +1,5 @@
+/** Loads a prompt file from the same directory as the compiled
+ *  caller (dist/tools/<name>.prompt.md). The argument is the
+ *  filename only, no path separators. */
+export declare function loadPrompt(name: string): string;
+//# sourceMappingURL=load-prompt.d.ts.map

package/plugins/files/dist/tools/load-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-prompt.d.ts","sourceRoot":"","sources":["../../src/tools/load-prompt.ts"],"names":[],"mappings":"AAsBA;;yCAEyC;AACzC,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAe/C"}

package/plugins/files/dist/tools/load-prompt.js

@@ -0,0 +1,39 @@
+// Tiny helper that loads a `*.prompt.md` sibling file at module-
+// load time and returns its UTF-8 contents.
+//
+// Why a helper instead of inlining `readFileSync` at every call
+// site: each tool has its own prompt and we want the tool file to
+// just say `description: loadPrompt("edit-file.prompt.md")`. The
+// helper resolves relative to the calling file's compiled
+// location (dist/tools/), where copy-prompts.mjs has placed the
+// markdown sibling — see scripts/copy-prompts.mjs for the build-
+// time half of this contract.
+//
+// Loaded lazily and memoised: same prompt name only hits the
+// disk once per process even if the schema function gets called
+// many times (currently it's called once at activate(), but
+// memoisation keeps the helper safe for hot paths too).
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const cache = new Map();
+/** Loads a prompt file from the same directory as the compiled
+ *  caller (dist/tools/<name>.prompt.md). The argument is the
+ *  filename only, no path separators. */
+export function loadPrompt(name) {
+    if (name.includes("/") || name.includes("\\") || !name.endsWith(".prompt.md")) {
+        throw new Error(`loadPrompt: bad prompt name ${JSON.stringify(name)}`);
+    }
+    const hit = cache.get(name);
+    if (hit !== undefined)
+        return hit;
+    // dist/tools/<name>.prompt.md, resolved relative to this file's
+    // compiled location. import.meta.url points at dist/tools/load-prompt.js
+    // at runtime, so dirname() gives us dist/tools/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const path = join(here, name);
+    const text = readFileSync(path, "utf8");
+    cache.set(name, text);
+    return text;
+}
+//# sourceMappingURL=load-prompt.js.map

package/plugins/files/dist/tools/load-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-prompt.js","sourceRoot":"","sources":["../../src/tools/load-prompt.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,4CAA4C;AAC5C,EAAE;AACF,gEAAgE;AAChE,kEAAkE;AAClE,iEAAiE;AACjE,0DAA0D;AAC1D,gEAAgE;AAChE,iEAAiE;AACjE,8BAA8B;AAC9B,EAAE;AACF,6DAA6D;AAC7D,gEAAgE;AAChE,4DAA4D;AAC5D,wDAAwD;AAExD,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAkB,CAAC;AAExC;;yCAEyC;AACzC,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC9E,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5B,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,GAAG,CAAC;IAElC,gEAAgE;IAChE,yEAAyE;IACzE,iDAAiD;IACjD,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IAC9B,MAAM,IAAI,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACxC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;IACtB,OAAO,IAAI,CAAC;AACd,CAAC"}

package/plugins/files/dist/tools/path-helper.d.ts

@@ -0,0 +1,32 @@
+export declare class PathOutsideRootError extends Error {
+    readonly requested: string;
+    readonly code: "PATH_OUTSIDE_ROOT";
+    constructor(requested: string);
+}
+/**
+ * Resolve a tool-supplied path against the per-user root.
+ * Throws `PathOutsideRootError` if the result would escape the root.
+ */
+export declare function resolveInUserHome(userHome: string, requested: string): string;
+/** Convert an absolute path back to a `/foo/bar` style display path
+ *  rooted at user home. Used for tool result text so the LLM doesn't
+ *  see the host filesystem prefix. */
+export declare function toDisplayPath(userHome: string, abs: string): string;
+/**
+ * Convert an absolute path back to a `workspace:///foo/bar` URI
+ * rooted at the user home. This is the canonical, single-source-of-
+ * truth shape every fs tool returns in its result text and entry
+ * fields, so the chat UI can recognise file references with one
+ * regex (no need to reverse-engineer the host filesystem prefix or
+ * decide whether a relative `./x` should be rewritten).
+ *
+ * The empty authority (`workspace:///foo`, three slashes) is
+ * intentional: by RFC 3986 a `file:` URL also uses an empty
+ * authority before the path. Keeping the same shape means the LLM
+ * can think of it as a file URL with a workspace scheme.
+ *
+ * Throws if `abs` is outside the user home; callers should
+ * guarantee that by going through `resolveInUserHome` first.
+ */
+export declare function toWorkspaceUri(userHome: string, abs: string): string;
+//# sourceMappingURL=path-helper.d.ts.map

package/plugins/files/dist/tools/path-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helper.d.ts","sourceRoot":"","sources":["../../src/tools/path-helper.ts"],"names":[],"mappings":"AAyBA,qBAAa,oBAAqB,SAAQ,KAAK;aAEjB,SAAS,EAAE,MAAM;IAD7C,QAAQ,CAAC,IAAI,EAAG,mBAAmB,CAAU;gBACjB,SAAS,EAAE,MAAM;CAI9C;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAqC7E;AAED;;sCAEsC;AACtC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpE"}

package/plugins/files/dist/tools/path-helper.js

@@ -0,0 +1,113 @@
+// Path helper shared by every fs tool.
+//
+// Every agent-tool root is the **current user's home** under the
+// tenant workspace, i.e. `<tenant>/workspace/users/<userId>/`. This
+// matches the `files` plugin's UI scope (PR #40) and ADR-0001 §2:
+//   - one user's tools cannot reach another user's files
+//   - the shared `_tenant/` directory is intentionally invisible to
+//     tools (host injects its contents into the system prompt instead)
+//   - host filesystem outside the user home is rejected
+//
+// Path inputs are accepted in four shapes for ergonomics:
+//   - "workspace:///foo/bar"  → user home + foo/bar  (canonical — the
+//                                                     shape this
+//                                                     module emits)
+//   - "/foo/bar"              → user home + foo/bar
+//   - "foo/bar"               → user home + foo/bar  (relative is the same)
+//   - "/workspace/foo"        → user home + foo      (alias kept so existing
+//                                                     LLM training data
+//                                                     with `/workspace/...`
+//                                                     still resolves)
+// Anything containing a literal `..` segment is rejected up front so a
+// trick like "/workspace/../etc/passwd" cannot squeeze past resolve().
+import path from "node:path";
+export class PathOutsideRootError extends Error {
+    requested;
+    code = "PATH_OUTSIDE_ROOT";
+    constructor(requested) {
+        super(`path "${requested}" is outside the user workspace`);
+        this.requested = requested;
+        this.name = "PathOutsideRootError";
+    }
+}
+/**
+ * Resolve a tool-supplied path against the per-user root.
+ * Throws `PathOutsideRootError` if the result would escape the root.
+ */
+export function resolveInUserHome(userHome, requested) {
+    if (typeof requested !== "string" || requested.length === 0) {
+        throw new PathOutsideRootError(requested);
+    }
+    let rel = requested.replace(/\\/g, "/");
+    // Strip the canonical workspace:// scheme. Two authority shapes
+    // are accepted: "workspace:///foo" (empty authority — what we
+    // emit) and "workspace://foo" (non-empty authority — a tolerated
+    // alias since LLMs sometimes drop the third slash).
+    if (rel.startsWith("workspace:///")) {
+        rel = rel.slice("workspace:///".length);
+    }
+    else if (rel.startsWith("workspace://")) {
+        rel = rel.slice("workspace://".length);
+    }
+    else if (rel === "workspace:") {
+        rel = "";
+    }
+    // Strip the optional /workspace/ prefix; agents trained on the old
+    // tianshu schema use it.
+    if (rel.startsWith("/workspace/"))
+        rel = rel.slice("/workspace/".length);
+    else if (rel === "/workspace")
+        rel = "";
+    // Strip a leading slash; "/" → root.
+    if (rel.startsWith("/"))
+        rel = rel.slice(1);
+    const segments = rel.split("/").filter((s) => s.length > 0);
+    if (segments.some((s) => s === ".." || s === ".")) {
+        // Refuse `.` too — it's harmless but gives a normalised "/" alias
+        // and we don't want LLM-confused paths sneaking in.
+        if (segments.some((s) => s === "..")) {
+            throw new PathOutsideRootError(requested);
+        }
+    }
+    const resolved = path.resolve(userHome, ...segments);
+    const rootAbs = path.resolve(userHome);
+    if (resolved !== rootAbs && !resolved.startsWith(rootAbs + path.sep)) {
+        throw new PathOutsideRootError(requested);
+    }
+    return resolved;
+}
+/** Convert an absolute path back to a `/foo/bar` style display path
+ *  rooted at user home. Used for tool result text so the LLM doesn't
+ *  see the host filesystem prefix. */
+export function toDisplayPath(userHome, abs) {
+    const rel = path.relative(userHome, abs).replace(/\\/g, "/");
+    if (rel === "" || rel === ".")
+        return "/";
+    return "/" + rel;
+}
+/**
+ * Convert an absolute path back to a `workspace:///foo/bar` URI
+ * rooted at the user home. This is the canonical, single-source-of-
+ * truth shape every fs tool returns in its result text and entry
+ * fields, so the chat UI can recognise file references with one
+ * regex (no need to reverse-engineer the host filesystem prefix or
+ * decide whether a relative `./x` should be rewritten).
+ *
+ * The empty authority (`workspace:///foo`, three slashes) is
+ * intentional: by RFC 3986 a `file:` URL also uses an empty
+ * authority before the path. Keeping the same shape means the LLM
+ * can think of it as a file URL with a workspace scheme.
+ *
+ * Throws if `abs` is outside the user home; callers should
+ * guarantee that by going through `resolveInUserHome` first.
+ */
+export function toWorkspaceUri(userHome, abs) {
+    const rel = path.relative(userHome, abs).replace(/\\/g, "/");
+    if (rel.startsWith("..")) {
+        throw new PathOutsideRootError(abs);
+    }
+    if (rel === "" || rel === ".")
+        return "workspace:///";
+    return "workspace:///" + rel;
+}
+//# sourceMappingURL=path-helper.js.map

package/plugins/files/dist/tools/path-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helper.js","sourceRoot":"","sources":["../../src/tools/path-helper.ts"],"names":[],"mappings":"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"}

package/plugins/files/dist/tools/read-file.d.ts

@@ -0,0 +1,17 @@
+import type { Tool } from "@earendil-works/pi-ai";
+export declare const MAX_TEXT_BYTES = 500000;
+export interface ReadFileToolResult {
+    ok: boolean;
+    text: string;
+    binary?: boolean;
+    size?: number;
+    bytesReturned?: number;
+    nextOffset?: number;
+}
+export declare function readFileSchema(): Tool;
+export declare function executeReadFile(userHome: string, args: {
+    path: string;
+    offset?: number;
+    limit?: number;
+}, sessionId?: string): ReadFileToolResult;
+//# sourceMappingURL=read-file.d.ts.map

package/plugins/files/dist/tools/read-file.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-file.d.ts","sourceRoot":"","sources":["../../src/tools/read-file.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAQlD,eAAO,MAAM,cAAc,SAAU,CAAC;AAEtC,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,cAAc,IAAI,IAAI,CAgCrC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACvD,SAAS,CAAC,EAAE,MAAM,GACjB,kBAAkB,CAyEpB"}

package/plugins/files/dist/tools/read-file.js

@@ -0,0 +1,109 @@
+// read_file — agent tool that returns the contents of a small text file.
+//
+// Hard cap of 500 KB per call. For larger files the agent must page
+// through with `offset` and `limit` (the response includes the next
+// args you should pass).
+//
+// Binary files are detected heuristically (NUL byte in first 4 KB)
+// and returned as a stub message rather than raw bytes — preserving
+// the LLM's context window.
+import fs from "node:fs";
+import { Type } from "typebox";
+import { markChunk } from "./read-tracker.js";
+import { resolveInUserHome, toWorkspaceUri, PathOutsideRootError, } from "./path-helper.js";
+export const MAX_TEXT_BYTES = 500_000;
+export function readFileSchema() {
+    return {
+        name: "read_file",
+        description: `Read a text file from the workspace. Returns up to ${MAX_TEXT_BYTES / 1000} KB per call. \
+For larger files, pass \`offset\` (byte offset to start at) and \`limit\` (max bytes); the \
+response will tell you the file's full size and the next offset to use.
+
+Paths are interpreted relative to the workspace root; prefer relative paths \
+(\`notes/today.md\`) over leading-slash forms. A leading slash here resolves \
+to the workspace root — NOT the sandbox OS root — so to avoid confusion when \
+\`exec\` is also in play, write paths without a leading slash.
+
+Binary files (image, archive, etc.) return a short stub instead of bytes — extract them \
+to text first via another tool if you need their contents.`,
+        parameters: Type.Object({
+            path: Type.String({
+                description: 'Path relative to the workspace root, e.g. "notes/today.md".',
+            }),
+            offset: Type.Optional(Type.Integer({
+                minimum: 0,
+                description: "Byte offset to start reading from. Default 0.",
+            })),
+            limit: Type.Optional(Type.Integer({
+                minimum: 1,
+                description: `Max bytes to return. Capped at ${MAX_TEXT_BYTES}.`,
+            })),
+        }),
+    };
+}
+export function executeReadFile(userHome, args, sessionId) {
+    let resolved;
+    try {
+        resolved = resolveInUserHome(userHome, args.path);
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { ok: false, text: `path is outside the workspace: ${args.path}` };
+        }
+        throw err;
+    }
+    if (!fs.existsSync(resolved)) {
+        return { ok: false, text: `not found: ${args.path}` };
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        return { ok: false, text: `is a directory, not a file: ${args.path}` };
+    }
+    const offset = Math.max(0, Math.floor(args.offset ?? 0));
+    const limit = Math.max(1, Math.min(args.limit ?? MAX_TEXT_BYTES, MAX_TEXT_BYTES));
+    const fd = fs.openSync(resolved, "r");
+    try {
+        const buf = Buffer.alloc(limit);
+        const bytesRead = fs.readSync(fd, buf, 0, limit, offset);
+        const slice = buf.subarray(0, bytesRead);
+        // Binary check — first 4 KB of the slice.
+        const probe = slice.subarray(0, Math.min(slice.length, 4096));
+        if (probe.includes(0)) {
+            return {
+                ok: true,
+                text: `(binary file: ${stat.size} bytes; not shown)`,
+                binary: true,
+                size: stat.size,
+            };
+        }
+        const content = slice.toString("utf8");
+        const nextOffset = offset + bytesRead;
+        const more = nextOffset < stat.size;
+        // Track which chunk this call covered. The session-level read
+        // tracker accumulates start/end coverage across multiple
+        // `read_file` calls so that a paged read sequence (offset=0 +
+        // ... + final !more) ends up satisfying the read-required
+        // precondition just like a single one-shot read does. A purely
+        // mid-file partial read (offset>0 AND more=true) is a no-op
+        // — the agent paged a region without seeing either endpoint.
+        markChunk(sessionId, resolved, offset === 0, !more);
+        const uri = toWorkspaceUri(userHome, resolved);
+        const header = stat.size <= MAX_TEXT_BYTES
+            ? `// ${uri} (${stat.size} bytes)`
+            : `// ${uri} bytes ${offset}–${nextOffset} of ${stat.size}` +
+                (more
+                    ? ` — call read_file again with offset=${nextOffset} for the next chunk`
+                    : " (final chunk)");
+        return {
+            ok: true,
+            text: `${header}\n${content}`,
+            size: stat.size,
+            bytesReturned: bytesRead,
+            nextOffset: more ? nextOffset : undefined,
+        };
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=read-file.js.map

package/plugins/files/dist/tools/read-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-file.js","sourceRoot":"","sources":["../../src/tools/read-file.ts"],"names":[],"mappings":"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"}

package/plugins/files/dist/tools/read-tracker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Mark a path as fully read. Used by `read_file` for one-shot
+ * reads (offset=0 and final chunk in the same call) and by
+ * `write_file` after a successful write (the agent now "knows"
+ * the contents because it just authored them).
+ */
+export declare function markRead(sessionId: string | undefined, resolvedPath: string): void;
+/**
+ * Mark a single chunk of a paged read. The host calls this for
+ * every successful `read_file` regardless of size. `isStart` is
+ * true when the chunk began at offset 0; `isEnd` is true when the
+ * server reported no more chunks left (`!more`). A path becomes
+ * `hasRead`-true only after both flags have been seen — individually
+ * or in the same call — which makes paged "read 0..N until !more"
+ * count as a complete read without forcing the agent to do a second
+ * full one-shot pass.
+ */
+export declare function markChunk(sessionId: string | undefined, resolvedPath: string, isStart: boolean, isEnd: boolean): void;
+/** Returns true if `sessionId` has fully read `resolvedPath`.
+ *  "Fully" means the start (offset=0) and the end (final chunk)
+ *  have both been observed in this session. Returns true when
+ *  sessionId is missing — tools invoked outside an agent loop
+ *  (route handlers, scheduled jobs) shouldn't be blocked by the
+ *  read-required check. */
+export declare function hasRead(sessionId: string | undefined, resolvedPath: string): boolean;
+/** Test helper: clear all session state. */
+export declare function _resetForTests(): void;
+//# sourceMappingURL=read-tracker.d.ts.map

package/plugins/files/dist/tools/read-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracker.d.ts","sourceRoot":"","sources":["../../src/tools/read-tracker.ts"],"names":[],"mappings":"AAwFA;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,YAAY,EAAE,MAAM,GACnB,IAAI,CAON;AAED;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CACvB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,GACb,IAAI,CAgBN;AAED;;;;;2BAK2B;AAC3B,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAMpF;AAED,4CAA4C;AAC5C,wBAAgB,cAAc,IAAI,IAAI,CAGrC"}

package/plugins/files/dist/tools/read-tracker.js

@@ -0,0 +1,135 @@
+// Tracks which workspace paths each chat/worker session has loaded
+// via `read_file` in the current process lifetime.
+//
+// Used by `edit_file` and `write_file` (when target exists) to
+// refuse blind edits — if the agent never read a file, it has no
+// business overwriting or string-replacing into it. The error
+// surface tells the agent exactly what to do: "use read_file to
+// load <path> first".
+//
+// Why per-session and not per-tenant: two parallel chats by the
+// same user shouldn't share read state — chat A reading a file
+// doesn't authorise chat B to edit it sight-unseen. Sessions are
+// the natural granularity for "what the agent has seen so far".
+//
+// Why in-process and not persisted: the contract we want is
+// "agent has the file's contents in this conversation's context",
+// which is itself in-memory in the LLM provider and lives only as
+// long as the host process anyway. Persisting readSet across
+// restarts would create a false sense that the agent "knows" a
+// file when in reality the model has no token of it.
+//
+// Memory bound: each entry is a path string (~100 bytes typical),
+// session caps via LRU at 4096 paths per session, and we evict
+// idle sessions after 30 min. A tenant pegging this would need
+// ~30 MB for 1000 idle sessions — fine for our scale.
+//
+// Pagination semantics: a single one-shot read (offset=0 && !more)
+// counts as fully read. Files larger than 500 KB force the agent
+// to page through, in which case the path is fully "seen" only
+// after both the first chunk (offset=0) AND the final chunk
+// (!more) have been observed. We track those two flags per path
+// rather than full byte-range coverage — the simpler model covers
+// the realistic cases (read 0..N until !more) without the
+// bookkeeping cost of arbitrary-range merges.
+const SESSION_PATH_CAP = 4096;
+const SESSION_IDLE_MS = 30 * 60 * 1000;
+const sessions = new Map();
+let lastSweepMs = 0;
+function sweepIdle(now) {
+    if (now - lastSweepMs < 60_000)
+        return; // at most once a minute
+    lastSweepMs = now;
+    for (const [sid, entry] of sessions) {
+        if (now - entry.lastTouchedMs > SESSION_IDLE_MS) {
+            sessions.delete(sid);
+        }
+    }
+}
+function getOrCreate(sessionId, now) {
+    let entry = sessions.get(sessionId);
+    if (!entry) {
+        entry = { paths: new Map(), order: [], lastTouchedMs: now };
+        sessions.set(sessionId, entry);
+    }
+    else {
+        entry.lastTouchedMs = now;
+    }
+    return entry;
+}
+function touchOrder(entry, resolvedPath) {
+    const idx = entry.order.indexOf(resolvedPath);
+    if (idx >= 0)
+        entry.order.splice(idx, 1);
+    entry.order.push(resolvedPath);
+    while (entry.order.length > SESSION_PATH_CAP) {
+        const evicted = entry.order.shift();
+        if (evicted !== undefined)
+            entry.paths.delete(evicted);
+    }
+}
+/**
+ * Mark a path as fully read. Used by `read_file` for one-shot
+ * reads (offset=0 and final chunk in the same call) and by
+ * `write_file` after a successful write (the agent now "knows"
+ * the contents because it just authored them).
+ */
+export function markRead(sessionId, resolvedPath) {
+    if (!sessionId)
+        return;
+    const now = Date.now();
+    sweepIdle(now);
+    const entry = getOrCreate(sessionId, now);
+    entry.paths.set(resolvedPath, { sawStart: true, sawEnd: true });
+    touchOrder(entry, resolvedPath);
+}
+/**
+ * Mark a single chunk of a paged read. The host calls this for
+ * every successful `read_file` regardless of size. `isStart` is
+ * true when the chunk began at offset 0; `isEnd` is true when the
+ * server reported no more chunks left (`!more`). A path becomes
+ * `hasRead`-true only after both flags have been seen — individually
+ * or in the same call — which makes paged "read 0..N until !more"
+ * count as a complete read without forcing the agent to do a second
+ * full one-shot pass.
+ */
+export function markChunk(sessionId, resolvedPath, isStart, isEnd) {
+    if (!sessionId)
+        return;
+    if (!isStart && !isEnd)
+        return; // mid-file chunk; nothing to flag
+    const now = Date.now();
+    sweepIdle(now);
+    const entry = getOrCreate(sessionId, now);
+    const prev = entry.paths.get(resolvedPath) ?? {
+        sawStart: false,
+        sawEnd: false,
+    };
+    const next = {
+        sawStart: prev.sawStart || isStart,
+        sawEnd: prev.sawEnd || isEnd,
+    };
+    entry.paths.set(resolvedPath, next);
+    touchOrder(entry, resolvedPath);
+}
+/** Returns true if `sessionId` has fully read `resolvedPath`.
+ *  "Fully" means the start (offset=0) and the end (final chunk)
+ *  have both been observed in this session. Returns true when
+ *  sessionId is missing — tools invoked outside an agent loop
+ *  (route handlers, scheduled jobs) shouldn't be blocked by the
+ *  read-required check. */
+export function hasRead(sessionId, resolvedPath) {
+    if (!sessionId)
+        return true;
+    const entry = sessions.get(sessionId);
+    if (!entry)
+        return false;
+    const state = entry.paths.get(resolvedPath);
+    return Boolean(state && state.sawStart && state.sawEnd);
+}
+/** Test helper: clear all session state. */
+export function _resetForTests() {
+    sessions.clear();
+    lastSweepMs = 0;
+}
+//# sourceMappingURL=read-tracker.js.map

package/plugins/files/dist/tools/read-tracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tracker.js","sourceRoot":"","sources":["../../src/tools/read-tracker.ts"],"names":[],"mappings":"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"}