@tianshu-ai/tianshu 0.3.0

package/packages/server/dist/tools/edit-file.js

@@ -0,0 +1,90 @@
+// edit_file — exact text replacement (the agent's bread-and-butter
+// surgical edit tool, modelled on Anthropic's `str_replace_editor`).
+//
+// We require `oldText` to occur **exactly once** in the file so an
+// LLM can't accidentally clobber a similarly-named variable in three
+// places when it meant one. Multi-occurrence cases force the agent
+// to either pull a wider unique window or fall back to write_file.
+//
+// Atomic on disk via temp sibling + rename (same as write_file).
+import fs from "node:fs";
+import { Type } from "typebox";
+import { resolveInUserHome, PathOutsideRootError } from "./path-helper.js";
+export function editFileSchema() {
+    return {
+        name: "edit_file",
+        description: "Replace one exact substring with another inside an existing file. The " +
+            "`old_text` must appear EXACTLY ONCE in the file — if it appears multiple " +
+            "times the call fails and you should pull a wider unique window. Use this " +
+            "for surgical edits; for new files or full rewrites use `write_file`.",
+        parameters: Type.Object({
+            path: Type.String({
+                description: 'Path relative to the workspace root, e.g. "/notes/today.md".',
+            }),
+            old_text: Type.String({
+                description: "The exact text to find and replace. Must appear exactly once in the file.",
+            }),
+            new_text: Type.String({
+                description: "The replacement text.",
+            }),
+        }),
+    };
+}
+export function executeEditFile(userHome, args) {
+    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}` };
+    }
+    if (fs.statSync(resolved).isDirectory()) {
+        return { ok: false, text: `is a directory: ${args.path}` };
+    }
+    if (args.old_text.length === 0) {
+        return { ok: false, text: "old_text must be non-empty" };
+    }
+    if (args.old_text === args.new_text) {
+        return { ok: false, text: "old_text and new_text are identical" };
+    }
+    const original = fs.readFileSync(resolved, "utf8");
+    const occurrences = countOccurrences(original, args.old_text);
+    if (occurrences === 0) {
+        return { ok: false, text: `old_text not found in ${args.path}` };
+    }
+    if (occurrences > 1) {
+        return {
+            ok: false,
+            text: `old_text appears ${occurrences} times in ${args.path}; pull a wider unique window`,
+            occurrences,
+        };
+    }
+    const updated = original.replace(args.old_text, args.new_text);
+    const tmp = `${resolved}.tmp.${process.pid}.${Date.now()}`;
+    fs.writeFileSync(tmp, updated);
+    fs.renameSync(tmp, resolved);
+    return {
+        ok: true,
+        text: `edited ${args.path} (${args.old_text.length} → ${args.new_text.length} chars)`,
+        occurrences: 1,
+    };
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let from = 0;
+    while (true) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx < 0)
+            break;
+        count++;
+        from = idx + needle.length;
+    }
+    return count;
+}
+//# sourceMappingURL=edit-file.js.map

package/packages/server/dist/tools/edit-file.js.map

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

package/packages/server/dist/tools/glob.d.ts

@@ -0,0 +1,12 @@
+import type { Tool } from "@earendil-works/pi-ai";
+export interface GlobToolResult {
+    ok: boolean;
+    text: string;
+    matches?: string[];
+    truncated?: boolean;
+}
+export declare function globSchema(): Tool;
+export declare function executeGlob(userHome: string, args: {
+    pattern: string;
+}): Promise<GlobToolResult>;
+//# sourceMappingURL=glob.d.ts.map

package/packages/server/dist/tools/glob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"glob.d.ts","sourceRoot":"","sources":["../../src/tools/glob.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAKlD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,wBAAgB,UAAU,IAAI,IAAI,CAcjC;AAED,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,GACxB,OAAO,CAAC,cAAc,CAAC,CA0DzB"}

package/packages/server/dist/tools/glob.js

@@ -0,0 +1,82 @@
+// glob — match file paths against a shell-style pattern, scoped to
+// the per-user workspace home.
+//
+// Backed by fast-glob so brace expansion, alternation, double-star,
+// case sensitivity, and gitignore-shaped traversal all behave the way
+// the LLM expects from prior training data.
+import fs from "node:fs";
+import fg from "fast-glob";
+import { Type } from "typebox";
+import { resolveInUserHome, toDisplayPath, PathOutsideRootError } from "./path-helper.js";
+const MAX_RESULTS = 1000;
+export function globSchema() {
+    return {
+        name: "glob",
+        description: `Find files matching a shell-style glob pattern, rooted at the workspace.\n` +
+            `Supports the usual glob syntax: \`*\`, \`**\`, \`?\`, \`{a,b}\`, character classes.\n` +
+            `Returns up to ${MAX_RESULTS} matching paths, sorted alphabetically.`,
+        parameters: Type.Object({
+            pattern: Type.String({
+                description: 'Glob pattern relative to the workspace root, e.g. "**/*.md", "src/*.ts", "{notes,journal}/**/*.txt".',
+            }),
+        }),
+    };
+}
+export async function executeGlob(userHome, args) {
+    if (!args.pattern || typeof args.pattern !== "string") {
+        return { ok: false, text: "pattern is required" };
+    }
+    // Strip the optional `/workspace/` prefix or leading `/` so the
+    // pattern is fast-glob-relative to userHome. We forbid `..` outright
+    // to keep the search inside the user home regardless of any path
+    // tricks fast-glob might otherwise resolve.
+    let pat = args.pattern.replace(/\\/g, "/");
+    if (pat.startsWith("/workspace/"))
+        pat = pat.slice("/workspace/".length);
+    else if (pat === "/workspace")
+        pat = "";
+    if (pat.startsWith("/"))
+        pat = pat.slice(1);
+    if (pat.includes("..")) {
+        return { ok: false, text: `pattern cannot contain ".."` };
+    }
+    if (pat.length === 0) {
+        return { ok: false, text: "pattern is empty" };
+    }
+    // Resolve root and auto-create on first call so a fresh tenant
+    // doesn't blow up.
+    let root;
+    try {
+        root = resolveInUserHome(userHome, "/");
+    }
+    catch (err) {
+        if (err instanceof PathOutsideRootError) {
+            return { ok: false, text: "could not resolve workspace root" };
+        }
+        throw err;
+    }
+    if (!fs.existsSync(root))
+        fs.mkdirSync(root, { recursive: true });
+    // fast-glob honours `cwd`, returns paths relative to that cwd, and
+    // we ask it for files only. `dot: true` so dotfiles surface (the
+    // workspace deliberately uses .config/ etc.).
+    const found = await fg(pat, {
+        cwd: root,
+        onlyFiles: true,
+        dot: true,
+        suppressErrors: true,
+        followSymbolicLinks: false,
+    });
+    found.sort();
+    const truncated = found.length > MAX_RESULTS;
+    const slice = truncated ? found.slice(0, MAX_RESULTS) : found;
+    const matches = slice.map((rel) => toDisplayPath(root, `${root}/${rel}`));
+    const header = `${matches.length} match${matches.length === 1 ? "" : "es"}${truncated ? ` (truncated at ${MAX_RESULTS})` : ""}:`;
+    return {
+        ok: true,
+        text: [header, ...matches].join("\n"),
+        matches,
+        truncated,
+    };
+}
+//# sourceMappingURL=glob.js.map

package/packages/server/dist/tools/glob.js.map

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

package/packages/server/dist/tools/index.d.ts

@@ -0,0 +1,82 @@
+import type { Tool } from "@earendil-works/pi-ai";
+import type { AgentTool, PluginLogger } from "@tianshu/plugin-sdk";
+import type { HostCapabilityHandle } from "../core/plugins/registry.js";
+import type { LoadedSkill } from "../core/plugins/skills.js";
+export type ToolResult = unknown;
+export type ToolExecutor = (args: Record<string, unknown>) => Promise<ToolResult> | ToolResult;
+export interface Toolset {
+    /** pi-ai Tool schemas to pass to streamSimple/agent loop. */
+    schemas: Tool[];
+    /** Map of tool name → executor. */
+    executors: Record<string, ToolExecutor>;
+}
+export interface BuildToolsetOpts {
+    /** Plugin tools collected from `pluginRegistry.toolsForTenant`. */
+    pluginTools: Array<{
+        pluginId: string;
+        tool: AgentTool;
+    }>;
+    /** Context passed to each plugin tool's `available()` and
+     *  `execute()`. Required iff `pluginTools` is non-empty. */
+    toolContext: BuildToolContext;
+    /**
+     * Deprecated. Used to feed a `read_skill` meta-tool; the
+     * registry now mirrors host / plugin SKILL.md into the tenant
+     * config tree so `tenant_config_read` reaches every skill
+     * source via its <available_skills> URI. Kept on the type one
+     * release for back-compat with old callers.
+     *
+     * @deprecated
+     */
+    skills?: readonly LoadedSkill[];
+}
+/** Subset of `AgentToolContext` the host always knows. The handler
+ *  fills in `pluginId` per tool when it invokes one. */
+export interface BuildToolContext {
+    tenantId: string;
+    userId: string;
+    capabilities: HostCapabilityHandle;
+    userHomeDir: string;
+    tenantHomeDir: string;
+    /** See `AgentToolContext.agentScope`. Defaults to `{kind:"main"}`
+     *  inside `buildToolset` if the caller doesn't pass it. */
+    agentScope?: {
+        kind: "main";
+    } | {
+        kind: "worker";
+        workerKind: string;
+        slug?: string;
+    };
+    log: PluginLogger;
+    /**
+     * Session this toolset belongs to. Plumbed through to every
+     * tool's `AgentToolContext.sessionId` so plugins can attribute
+     * side-effects (e.g. workboard's task_create stamping
+     * `tasks.parent_session_id`) back to the asking session.
+     *
+     * Optional: tools instantiated outside any chat / worker
+     * context (e.g. unit tests) may skip it.
+     */
+    sessionId?: string;
+    /**
+     * Workboard task id this toolset is bound to. Forwarded into
+     * every tool's `AgentToolContext.taskId` so per-task tools
+     * (microsandbox `exec`) can scope resources to the task
+     * lifecycle. Absent for chat sessions.
+     */
+    taskId?: string;
+    /**
+     * Cancellation signal piped from the agent loop's inner abort
+     * controller. Forwarded into every tool's
+     * `AgentToolContext.signal` so long-running tools can bail
+     * early on watchdog timeout / external `task_abort`. Optional
+     * because unit tests instantiating a toolset don't need it.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Build a per-request toolset. Plugin tools are registered iff
+ * their `available()` hook (default: true) returns truthy.
+ */
+export declare function buildToolset(opts: BuildToolsetOpts): Promise<Toolset>;
+//# sourceMappingURL=index.d.ts.map

package/packages/server/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAElD,OAAO,KAAK,EAAE,SAAS,EAAoB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACrF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AAE7D,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC;AACjC,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,UAAU,CAAC,GAAG,UAAU,CAAC;AAE/F,MAAM,WAAW,OAAO;IACtB,6DAA6D;IAC7D,OAAO,EAAE,IAAI,EAAE,CAAC;IAChB,mCAAmC;IACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,mEAAmE;IACnE,WAAW,EAAE,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,SAAS,CAAA;KAAE,CAAC,CAAC;IAC1D;gEAC4D;IAC5D,WAAW,EAAE,gBAAgB,CAAC;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,SAAS,WAAW,EAAE,CAAC;CACjC;AAED;wDACwD;AACxD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,oBAAoB,CAAC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB;+DAC2D;IAC3D,UAAU,CAAC,EACP;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,GAChB;QAAE,IAAI,EAAE,QAAQ,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,GAAG,EAAE,YAAY,CAAC;IAClB;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CA2D3E"}

package/packages/server/dist/tools/index.js

@@ -0,0 +1,72 @@
+// Agent toolset assembler.
+//
+// All agent tools live in plugins now (ADR-0004 N+3): file ops in
+// the `files` plugin, sandbox ops in the `microsandbox` plugin,
+// future plugins (web search, knowledge base, …) in their own
+// plugins. The host's role here is to:
+//
+//   - collect every active plugin's tools from the registry
+//   - run each tool's `available()` gate (tools may be hidden when
+//     a backing capability is unhealthy)
+//   - assemble pi-ai schemas + name → executor map for the chat
+//     handler
+//
+// If no plugin contributes tools (e.g. fresh install with the
+// `files` plugin disabled and no microsandbox), the agent simply
+// gets an empty toolset \u2014 it can still answer questions, just
+// can't touch files or run commands.
+/**
+ * Build a per-request toolset. Plugin tools are registered iff
+ * their `available()` hook (default: true) returns truthy.
+ */
+export async function buildToolset(opts) {
+    const { pluginTools, toolContext } = opts;
+    const schemas = [];
+    const executors = {};
+    // No skill meta-tool. The registry mirrors host / plugin
+    // SKILL.md into `<tenant>/_tenant/config/skills/_host/<pid>/
+    // <id>/SKILL.md` at activation time, so the agent reads any
+    // skill (tenant-authored, plugin-shipped, or host-shipped)
+    // via `tenant_config_read` against the URI advertised in
+    // `<available_skills>`. One tool, one path shape, no
+    // special case. `opts.skills` is kept on the type one
+    // release for back-compat but is intentionally ignored here.
+    void opts.skills;
+    const agentScope = toolContext.agentScope ?? { kind: "main" };
+    for (const { pluginId, tool } of pluginTools) {
+        const ctx = {
+            pluginId,
+            tenantId: toolContext.tenantId,
+            userId: toolContext.userId,
+            capabilities: toolContext.capabilities,
+            userHomeDir: toolContext.userHomeDir,
+            tenantHomeDir: toolContext.tenantHomeDir,
+            agentScope,
+            log: toolContext.log,
+            sessionId: toolContext.sessionId,
+            taskId: toolContext.taskId,
+            signal: toolContext.signal,
+        };
+        let available = true;
+        if (tool.available) {
+            try {
+                available = (await tool.available(ctx)) === true;
+            }
+            catch (err) {
+                toolContext.log.warn(`[plugin:${pluginId}] tool "${tool.schema.name}" available() threw \u2014 hiding tool: ${err instanceof Error ? err.message : String(err)}`);
+                available = false;
+            }
+        }
+        if (!available)
+            continue;
+        const name = tool.schema.name;
+        if (executors[name]) {
+            toolContext.log.warn(`[plugin:${pluginId}] tool "${name}" collides with an existing tool name; skipping`);
+            continue;
+        }
+        schemas.push(tool.schema);
+        executors[name] = (args) => tool.execute(args, ctx);
+    }
+    return { schemas, executors };
+}
+//# sourceMappingURL=index.js.map

package/packages/server/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,2BAA2B;AAC3B,EAAE;AACF,kEAAkE;AAClE,gEAAgE;AAChE,8DAA8D;AAC9D,uCAAuC;AACvC,EAAE;AACF,4DAA4D;AAC5D,mEAAmE;AACnE,yCAAyC;AACzC,gEAAgE;AAChE,cAAc;AACd,EAAE;AACF,8DAA8D;AAC9D,iEAAiE;AACjE,mEAAmE;AACnE,qCAAqC;AA6ErC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAsB;IACvD,MAAM,EAAE,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI,CAAC;IAE1C,MAAM,OAAO,GAAW,EAAE,CAAC;IAC3B,MAAM,SAAS,GAAiC,EAAE,CAAC;IAEnD,yDAAyD;IACzD,6DAA6D;IAC7D,4DAA4D;IAC5D,2DAA2D;IAC3D,yDAAyD;IACzD,qDAAqD;IACrD,sDAAsD;IACtD,6DAA6D;IAC7D,KAAK,IAAI,CAAC,MAAM,CAAC;IAEjB,MAAM,UAAU,GAAG,WAAW,CAAC,UAAU,IAAI,EAAE,IAAI,EAAE,MAAe,EAAE,CAAC;IAEvE,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC;QAC7C,MAAM,GAAG,GAAqB;YAC5B,QAAQ;YACR,QAAQ,EAAE,WAAW,CAAC,QAAQ;YAC9B,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,YAAY,EAAE,WAAW,CAAC,YAAY;YACtC,WAAW,EAAE,WAAW,CAAC,WAAW;YACpC,aAAa,EAAE,WAAW,CAAC,aAAa;YACxC,UAAU;YACV,GAAG,EAAE,WAAW,CAAC,GAAG;YACpB,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,MAAM,EAAE,WAAW,CAAC,MAAM;YAC1B,MAAM,EAAE,WAAW,CAAC,MAAM;SAC3B,CAAC;QACF,IAAI,SAAS,GAAG,IAAI,CAAC;QACrB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,IAAI,CAAC;gBACH,SAAS,GAAG,CAAC,MAAM,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC;YACnD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,WAAW,CAAC,GAAG,CAAC,IAAI,CAClB,WAAW,QAAQ,WAAW,IAAI,CAAC,MAAM,CAAC,IAAI,2CAC5C,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,EAAE,CACH,CAAC;gBACF,SAAS,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,SAAS;YAAE,SAAS;QAEzB,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;QAC9B,IAAI,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,WAAW,CAAC,GAAG,CAAC,IAAI,CAClB,WAAW,QAAQ,WAAW,IAAI,iDAAiD,CACpF,CAAC;YACF,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1B,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACtD,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;AAChC,CAAC"}

package/packages/server/dist/tools/list-dir.d.ts

@@ -0,0 +1,24 @@
+import type { Tool } from "@earendil-works/pi-ai";
+interface ListEntry {
+    name: string;
+    path: string;
+    type: "directory" | "file" | "other";
+    size: number;
+    modifiedMs: number;
+}
+export interface ListDirToolResult {
+    ok: boolean;
+    text: string;
+    entries?: ListEntry[];
+    truncated?: boolean;
+}
+/** 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 declare function listDirSchema(): Tool;
+export declare function executeListDir(userHome: string, args: {
+    path?: string;
+}): ListDirToolResult;
+export {};
+//# sourceMappingURL=list-dir.d.ts.map

package/packages/server/dist/tools/list-dir.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-dir.d.ts","sourceRoot":"","sources":["../../src/tools/list-dir.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAKlD,UAAU,SAAS;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,SAAS,EAAE,CAAC;IACtB,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;iCAGiC;AACjC,wBAAgB,aAAa,IAAI,IAAI,CAcpC;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACtB,iBAAiB,CAwEnB"}

package/packages/server/dist/tools/list-dir.js

@@ -0,0 +1,99 @@
+// 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, toDisplayPath, 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 relative to the workspace root (\"/\" = root). " +
+            "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". Default "/".',
+            }),
+        }),
+    };
+}
+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: toDisplayPath(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 ${toDisplayPath(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/packages/server/dist/tools/list-dir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-dir.js","sourceRoot":"","sources":["../../src/tools/list-dir.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,EAAE;AACF,kEAAkE;AAClE,kEAAkE;AAClE,6CAA6C;AAE7C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAE1F,MAAM,WAAW,GAAG,IAAI,CAAC;AAiBzB;;;iCAGiC;AACjC,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,WAAW,EACT,6EAA6E;YAC7E,6EAA6E;YAC7E,kEAAkE;QACpE,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC;YACtB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC;gBAChB,WAAW,EACT,2FAA2F;aAC9F,CAAC;SACH,CAAC;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,cAAc,CAC5B,QAAgB,EAChB,IAAuB;IAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC;IACnC,IAAI,QAAgB,CAAC;IACrB,IAAI,CAAC;QACH,QAAQ,GAAG,iBAAiB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;IACpD,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,GAAG,YAAY,oBAAoB,EAAE,CAAC;YACxC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,kCAAkC,SAAS,EAAE,EAAE,CAAC;QAC5E,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;IAED,mEAAmE;IACnE,mDAAmD;IACnD,IAAI,QAAQ,KAAK,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACpE,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,cAAc,SAAS,EAAE,EAAE,CAAC;IACxD,CAAC;IACD,MAAM,IAAI,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;QACxB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,SAAS,EAAE,EAAE,CAAC;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IAClE,MAAM,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,WAAW,CAAC;IAC/C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAgB,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC5B,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC;YACd,UAAU,GAAG,CAAC,CAAC,OAAO,CAAC;QACzB,CAAC;QAAC,MAAM,CAAC;YACP,oCAAoC;QACtC,CAAC;QACD,MAAM,IAAI,GAAsB,CAAC,CAAC,WAAW,EAAE;YAC7C,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE;gBACV,CAAC,CAAC,MAAM;gBACR,CAAC,CAAC,OAAO,CAAC;QACd,OAAO;YACL,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,IAAI,EAAE,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC;YACnC,IAAI;YACJ,IAAI;YACJ,UAAU;SACX,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,gDAAgD;IAChD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACpB,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO,CAAC,CAAC,CAAC;YACtC,IAAI,CAAC,CAAC,IAAI,KAAK,WAAW;gBAAE,OAAO,CAAC,CAAC;QACvC,CAAC;QACD,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAC9B,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,MAAM,CAAC,CAAC,IAAI,SAAS,CACvE,CAAC;IACF,MAAM,MAAM,GAAG,aAAa,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,KAAK,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,GAAG,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC;IACpK,OAAO;QACL,EAAE,EAAE,IAAI;QACR,IAAI,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QACnC,OAAO;QACP,SAAS;KACV,CAAC;AACJ,CAAC"}

package/packages/server/dist/tools/path-helper.d.ts

@@ -0,0 +1,15 @@
+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;
+//# sourceMappingURL=path-helper.d.ts.map

package/packages/server/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":"AAsBA,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,CA0B7E;AAED;;sCAEsC;AACtC,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAInE"}

package/packages/server/dist/tools/path-helper.js

@@ -0,0 +1,72 @@
+// 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 three shapes for ergonomics:
+//   - "/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);
+    }
+    // Strip the optional /workspace/ prefix; agents trained on the old
+    // tianshu schema use it.
+    let rel = requested.replace(/\\/g, "/");
+    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;
+}
+//# sourceMappingURL=path-helper.js.map

package/packages/server/dist/tools/path-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-helper.js","sourceRoot":"","sources":["../../src/tools/path-helper.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,iEAAiE;AACjE,oEAAoE;AACpE,kEAAkE;AAClE,yDAAyD;AACzD,oEAAoE;AACpE,uEAAuE;AACvE,wDAAwD;AACxD,EAAE;AACF,2DAA2D;AAC3D,8CAA8C;AAC9C,sEAAsE;AACtE,uEAAuE;AACvE,mEAAmE;AACnE,uEAAuE;AACvE,iEAAiE;AACjE,uEAAuE;AACvE,uEAAuE;AAEvE,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAEjB;IADnB,IAAI,GAAG,mBAA4B,CAAC;IAC7C,YAA4B,SAAiB;QAC3C,KAAK,CAAC,SAAS,SAAS,iCAAiC,CAAC,CAAC;QADjC,cAAS,GAAT,SAAS,CAAQ;QAE3C,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,SAAiB;IACnE,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IACD,mEAAmE;IACnE,yBAAyB;IACzB,IAAI,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IACxC,IAAI,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC;SACpE,IAAI,GAAG,KAAK,YAAY;QAAE,GAAG,GAAG,EAAE,CAAC;IACxC,qCAAqC;IACrC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAE5C,MAAM,QAAQ,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC5D,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QAClD,kEAAkE;QAClE,oDAAoD;QACpD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,QAAQ,CAAC,CAAC;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,QAAQ,KAAK,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,oBAAoB,CAAC,SAAS,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;sCAEsC;AACtC,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,GAAW;IACzD,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC7D,IAAI,GAAG,KAAK,EAAE,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,GAAG,CAAC;IAC1C,OAAO,GAAG,GAAG,GAAG,CAAC;AACnB,CAAC"}

package/packages/server/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;
+}): ReadFileToolResult;
+//# sourceMappingURL=read-file.d.ts.map

package/packages/server/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;AAGlD,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,CA2BrC;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,GACtD,kBAAkB,CA+DpB"}