@rubytech/taskmaster 1.2.1 → 1.4.0

package/dist/agents/auth-profiles/oauth.js

@@ -59,6 +59,30 @@ async function refreshOAuthTokenWithLock(params) {
             type: "oauth",
         };
         saveAuthProfileStore(store, params.agentDir);
+        // Propagate refreshed credentials to the main store so auth.status and other agents
+        // see the fresh token. Without this, the main store retains a stale refresh token
+        // that Anthropic has already rotated, causing auth.status to permanently report
+        // "Connection expired" even though the agent is working fine.
+        const mainAuthPath = resolveAuthStorePath();
+        if (authPath !== mainAuthPath) {
+            try {
+                const mainStore = ensureAuthProfileStore();
+                const mainCred = mainStore.profiles[params.profileId];
+                const mainExpiry = mainCred?.type === "oauth" ? mainCred.expires : 0;
+                const freshExpiry = result.newCredentials.expires ?? 0;
+                if (freshExpiry > mainExpiry) {
+                    mainStore.profiles[params.profileId] = {
+                        ...(mainCred ?? cred),
+                        ...result.newCredentials,
+                        type: "oauth",
+                    };
+                    saveAuthProfileStore(mainStore);
+                }
+            }
+            catch {
+                // Best-effort — don't fail the agent's own refresh if main store update fails
+            }
+        }
         // Sync refreshed credentials back to Claude Code CLI if this is the claude-cli profile
         // This ensures Claude Code continues to work after Taskmaster refreshes the token
         if (params.profileId === CLAUDE_CLI_PROFILE_ID && cred.provider === "anthropic") {

package/dist/agents/auth-profiles/profiles.js

@@ -33,6 +33,43 @@ export function upsertAuthProfile(params) {
     store.profiles[params.profileId] = params.credential;
     saveAuthProfileStore(store, params.agentDir);
 }
+/**
+ * Remove an auth profile and all associated state (lastGood, usageStats, order).
+ * Used when an API key is deleted via the UI so the stale credential is not
+ * picked up by provider resolution.
+ */
+export function removeAuthProfile(params) {
+    const store = ensureAuthProfileStore(params.agentDir);
+    if (!(params.profileId in store.profiles))
+        return;
+    const provider = store.profiles[params.profileId]?.provider;
+    delete store.profiles[params.profileId];
+    // Clean up lastGood if it pointed to this profile
+    if (provider && store.lastGood?.[provider] === params.profileId) {
+        delete store.lastGood[provider];
+        if (Object.keys(store.lastGood).length === 0) {
+            store.lastGood = undefined;
+        }
+    }
+    // Clean up usageStats
+    if (store.usageStats?.[params.profileId]) {
+        delete store.usageStats[params.profileId];
+        if (Object.keys(store.usageStats).length === 0) {
+            store.usageStats = undefined;
+        }
+    }
+    // Clean up order references
+    if (provider && store.order?.[provider]) {
+        store.order[provider] = store.order[provider].filter((id) => id !== params.profileId);
+        if (store.order[provider].length === 0) {
+            delete store.order[provider];
+        }
+        if (Object.keys(store.order).length === 0) {
+            store.order = undefined;
+        }
+    }
+    saveAuthProfileStore(store, params.agentDir);
+}
 export function listProfilesForProvider(store, provider) {
     const providerKey = normalizeProviderId(provider);
     return Object.entries(store.profiles)

package/dist/agents/auth-profiles.js

@@ -4,7 +4,7 @@ export { formatAuthDoctorHint } from "./auth-profiles/doctor.js";
 export { resolveApiKeyForProfile } from "./auth-profiles/oauth.js";
 export { resolveAuthProfileOrder } from "./auth-profiles/order.js";
 export { resolveAuthStorePathForDisplay } from "./auth-profiles/paths.js";
-export { listProfilesForProvider, markAuthProfileGood, setAuthProfileOrder, upsertAuthProfile, } from "./auth-profiles/profiles.js";
+export { listProfilesForProvider, markAuthProfileGood, removeAuthProfile, setAuthProfileOrder, upsertAuthProfile, } from "./auth-profiles/profiles.js";
 export { repairOAuthProfileIdMismatch, suggestOAuthProfileIdForLegacyDefault, } from "./auth-profiles/repair.js";
 export { ensureAuthProfileStore, loadAuthProfileStore, saveAuthProfileStore, } from "./auth-profiles/store.js";
 export { calculateAuthProfileCooldownMs, clearAuthProfileCooldown, isProfileInCooldown, markAuthProfileCooldown, markAuthProfileFailure, markAuthProfileUsed, resolveProfileUnusableUntilForDisplay, } from "./auth-profiles/usage.js";

package/dist/agents/pi-tools.policy.js

@@ -49,6 +49,10 @@ function makeToolPolicyMatcher(policy) {
             return true;
         if (normalized === "apply_patch" && matchesAny("exec", allow))
             return true;
+        if (normalized === "file_delete" && matchesAny("memory_write", allow))
+            return true;
+        if (normalized === "file_list" && matchesAny("memory_search", allow))
+            return true;
         return false;
     };
 }

package/dist/agents/taskmaster-tools.js

@@ -22,6 +22,10 @@ import { createTtsTool } from "./tools/tts-tool.js";
 import { createCurrentTimeTool } from "./tools/current-time.js";
 import { createAuthorizeAdminTool, createListAdminsTool, createRevokeAdminTool, } from "./tools/authorize-admin-tool.js";
 import { createLicenseGenerateTool } from "./tools/license-tool.js";
+import { createContactCreateTool } from "./tools/contact-create-tool.js";
+import { createContactDeleteTool } from "./tools/contact-delete-tool.js";
+import { createFileDeleteTool } from "./tools/file-delete-tool.js";
+import { createFileListTool } from "./tools/file-list-tool.js";
 import { createContactLookupTool } from "./tools/contact-lookup-tool.js";
 import { createContactUpdateTool } from "./tools/contact-update-tool.js";
 import { createRelayMessageTool } from "./tools/relay-message-tool.js";
@@ -138,10 +142,20 @@ export function createTaskmasterTools(options) {
         createRevokeAdminTool(),
         createListAdminsTool(),
         createLicenseGenerateTool(),
+        createContactCreateTool(),
+        createContactDeleteTool(),
         createContactLookupTool(),
         createContactUpdateTool(),
         createRelayMessageTool(),
         createApiKeysTool(),
+        createFileDeleteTool({
+            config: options?.config,
+            agentSessionKey: options?.agentSessionKey,
+        }),
+        createFileListTool({
+            config: options?.config,
+            agentSessionKey: options?.agentSessionKey,
+        }),
     ];
     // Add scoped skill_read tool when skill directories are provided
     const skillDirs = (options?.skillBaseDirs ?? []).filter(Boolean);

package/dist/agents/tool-policy.js

@@ -36,6 +36,8 @@ export const TOOL_GROUPS = {
     "group:messaging": ["message"],
     // Nodes + device tools
     "group:nodes": ["nodes"],
+    // Contact record management
+    "group:contacts": ["contact_create", "contact_delete", "contact_lookup", "contact_update"],
     // Admin management tools
     "group:admin": ["authorize_admin", "revoke_admin", "list_admins"],
     // All Taskmaster native tools (excludes provider plugins).
@@ -67,6 +69,8 @@ export const TOOL_GROUPS = {
         "revoke_admin",
         "list_admins",
         "api_keys",
+        "file_delete",
+        "file_list",
     ],
 };
 // Tools that are never granted by profiles — must be explicitly added to the
@@ -113,8 +117,7 @@ const TOOL_PROFILES = {
             "image",
             "tts",
             "license_generate",
-            "contact_lookup",
-            "contact_update",
+            "group:contacts",
             "relay_message",
             "memory_save_media",
             "image_generate",

package/dist/agents/tools/apikeys-tool.js

@@ -9,21 +9,24 @@ import { Type } from "@sinclair/typebox";
 import { jsonResult, readStringParam } from "./common.js";
 import { callGatewayTool } from "./gateway.js";
 const ApiKeysSchema = Type.Object({
-    action: Type.Union([Type.Literal("set"), Type.Literal("list"), Type.Literal("remove")], {
-        description: 'Action to perform: "set" stores a key, "list" shows which providers have keys configured, "remove" deletes a stored key.',
+    action: Type.Union([Type.Literal("set"), Type.Literal("list"), Type.Literal("remove"), Type.Literal("disable")], {
+        description: 'Action to perform: "set" stores a key, "list" shows which providers have keys configured, "remove" deletes a stored key, "disable" toggles a key on/off without deleting it.',
     }),
     provider: Type.Optional(Type.String({
-        description: "Provider ID (required for set/remove). Valid providers: anthropic, google, tavily, openai, replicate, hume, brave, elevenlabs.",
+        description: "Provider ID (required for set/remove/disable). Valid providers: anthropic, google, tavily, openai, replicate, hume, brave, elevenlabs.",
     })),
     apiKey: Type.Optional(Type.String({
         description: "The API key value (required for set).",
     })),
+    disabled: Type.Optional(Type.Boolean({
+        description: "Whether to disable (true) or enable (false) the key (required for disable).",
+    })),
 });
 export function createApiKeysTool() {
     return {
         label: "API Keys",
         name: "api_keys",
-        description: "Manage API keys for external providers. Use action 'set' to store a key (provider + apiKey required), 'list' to check which providers have keys configured, or 'remove' to delete a stored key. Valid providers: anthropic, google, tavily, openai, replicate, hume, brave, elevenlabs. Keys are applied immediately without restart.",
+        description: "Manage API keys for external providers. Use action 'set' to store a key (provider + apiKey required), 'list' to check which providers have keys configured, 'remove' to delete a stored key, or 'disable' to toggle a key on/off without deleting it (provider + disabled required). Valid providers: anthropic, google, tavily, openai, replicate, hume, brave, elevenlabs. Keys are applied immediately without restart.",
         parameters: ApiKeysSchema,
         execute: async (_toolCallId, args) => {
             const params = args;
@@ -44,8 +47,16 @@ export function createApiKeysTool() {
                     const result = await callGatewayTool("apikeys.remove", {}, { provider });
                     return jsonResult(result);
                 }
+                case "disable": {
+                    const provider = readStringParam(params, "provider", { required: true });
+                    const disabled = params.disabled;
+                    if (typeof disabled !== "boolean")
+                        throw new Error("disabled parameter must be a boolean");
+                    const result = await callGatewayTool("apikeys.disable", {}, { provider, disabled });
+                    return jsonResult(result);
+                }
                 default:
-                    throw new Error(`Unknown action: ${action}. Use "set", "list", or "remove".`);
+                    throw new Error(`Unknown action: ${action}. Use "set", "list", "remove", or "disable".`);
             }
         },
     };

package/dist/agents/tools/contact-create-tool.js

@@ -0,0 +1,59 @@
+import { Type } from "@sinclair/typebox";
+import { getRecord, setRecord } from "../../records/records-manager.js";
+import { jsonResult } from "./common.js";
+const ContactCreateSchema = Type.Object({
+    phone: Type.String({
+        description: "Phone number (record ID) in international format (e.g. '+447490553305').",
+    }),
+    name: Type.String({
+        description: "Full name of the contact (e.g. 'Mrs Sarah Jenkins').",
+    }),
+    fields: Type.Optional(Type.Record(Type.String(), Type.String(), {
+        description: "Optional initial fields to set on the contact (e.g. { status: 'enquiry', source: 'WhatsApp' }).",
+    })),
+});
+/**
+ * Contact record creation tool — admin agent only.
+ *
+ * Creates a new contact record in the secure records store.
+ * The contact record is the source of truth — its phone number and name
+ * are the canonical identifiers that link to user-scoped memory at
+ * `memory/users/{phone}/`.
+ */
+export function createContactCreateTool() {
+    return {
+        label: "Contact Create",
+        name: "contact_create",
+        description: "Create a new contact record. The contact record is the source of truth — " +
+            "its phone number and name are the canonical identifiers linking to user-scoped memory. " +
+            "Use this on first meaningful interaction when you have a name and phone number. " +
+            "Fails if a record already exists for this phone number.",
+        parameters: ContactCreateSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const phone = typeof params.phone === "string" ? params.phone.trim() : "";
+            const name = typeof params.name === "string" ? params.name.trim() : "";
+            const fields = params.fields && typeof params.fields === "object" && !Array.isArray(params.fields)
+                ? params.fields
+                : {};
+            if (!phone) {
+                return jsonResult({ error: "Phone number is required." });
+            }
+            if (!name) {
+                return jsonResult({ error: "Name is required." });
+            }
+            const existing = getRecord(phone);
+            if (existing) {
+                return jsonResult({
+                    error: `A contact record already exists for ${phone} (${existing.name}). Use contact_update to modify it.`,
+                });
+            }
+            const record = setRecord(phone, { name, fields });
+            return jsonResult({
+                ok: true,
+                action: "created",
+                record,
+            });
+        },
+    };
+}

package/dist/agents/tools/contact-delete-tool.js

@@ -0,0 +1,48 @@
+import { Type } from "@sinclair/typebox";
+import { getRecord, deleteRecord } from "../../records/records-manager.js";
+import { jsonResult } from "./common.js";
+const ContactDeleteSchema = Type.Object({
+    phone: Type.String({
+        description: "Phone number (record ID) of the contact to delete (e.g. '+447490553305').",
+    }),
+});
+/**
+ * Contact record deletion tool — admin agent only.
+ *
+ * Deletes a contact record from the secure records store.
+ * Does NOT delete associated user-scoped memory at `memory/users/{phone}/` —
+ * that is a separate decision for the business owner.
+ */
+export function createContactDeleteTool() {
+    return {
+        label: "Contact Delete",
+        name: "contact_delete",
+        description: "Delete a contact record. This removes the structured record only — " +
+            "user-scoped memory at memory/users/{phone}/ is not affected. " +
+            "Use when a contact is no longer relevant (spam, duplicate, etc.).",
+        parameters: ContactDeleteSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const phone = typeof params.phone === "string" ? params.phone.trim() : "";
+            if (!phone) {
+                return jsonResult({ error: "Phone number is required." });
+            }
+            const existing = getRecord(phone);
+            if (!existing) {
+                return jsonResult({
+                    error: `No contact record found for ${phone}.`,
+                });
+            }
+            const deleted = deleteRecord(phone);
+            if (!deleted) {
+                return jsonResult({ error: `Failed to delete contact record for ${phone}.` });
+            }
+            return jsonResult({
+                ok: true,
+                action: "deleted",
+                phone,
+                name: existing.name,
+            });
+        },
+    };
+}

package/dist/agents/tools/contact-update-tool.js

@@ -1,12 +1,13 @@
 import { Type } from "@sinclair/typebox";
-import { getRecord, setRecordField, deleteRecordField } from "../../records/records-manager.js";
+import { getRecord, setRecordField, deleteRecordField, setRecordName, } from "../../records/records-manager.js";
 import { jsonResult } from "./common.js";
 const ContactUpdateSchema = Type.Object({
     phone: Type.String({
         description: "Phone number (record ID) of the contact to update (e.g. '+447490553305').",
     }),
     field: Type.String({
-        description: "Field name to set or delete (e.g. 'license_key', 'notes').",
+        description: "Field name to set or delete (e.g. 'license_key', 'notes'). " +
+            "Use 'name' to update the contact's display name.",
     }),
     value: Type.Optional(Type.String({
         description: "Value to set. Omit to delete the field.",
@@ -44,6 +45,20 @@ export function createContactUpdateTool() {
                     error: `No contact record found for ${phone}. Create one via the Contacts admin page first.`,
                 });
             }
+            // "name" updates the contact's canonical display name, not a custom field.
+            if (field === "name") {
+                if (value === undefined) {
+                    return jsonResult({ error: "Cannot delete the contact name. Provide a new value instead." });
+                }
+                const updated = setRecordName(phone, value);
+                return jsonResult({
+                    ok: true,
+                    action: "renamed",
+                    phone,
+                    name: value,
+                    record: updated,
+                });
+            }
             if (value === undefined) {
                 const updated = deleteRecordField(phone, field);
                 return jsonResult({

package/dist/agents/tools/file-delete-tool.js

@@ -0,0 +1,137 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { Type } from "@sinclair/typebox";
+import { resolveAgentWorkspaceRoot, resolveSessionAgentId } from "../agent-scope.js";
+import { jsonResult, readStringParam } from "./common.js";
+const FileDeleteSchema = Type.Object({
+    path: Type.String({
+        description: "Path to delete, relative to the workspace root " +
+            "(e.g. 'uploads/old-photo.jpg', 'memory/users/+447734875155/scratch.md').",
+    }),
+    recursive: Type.Optional(Type.Boolean({
+        description: "Set to true to delete a non-empty directory and all its contents. " +
+            "Defaults to false — non-empty directories are refused without this flag.",
+    })),
+});
+/**
+ * Protected top-level entries that cannot be deleted.
+ * These are structural directories/files whose removal would break the workspace.
+ */
+const PROTECTED_TOP_LEVEL = new Set([
+    "agents",
+    "IDENTITY.md",
+    "SOUL.md",
+    "AGENTS.md",
+    "TOOLS.md",
+]);
+/**
+ * Validate that `target` is strictly inside `root` (not equal to root).
+ * Both paths must be real (symlinks resolved) before calling.
+ */
+function isInsideRoot(target, root) {
+    const prefix = root.endsWith("/") ? root : `${root}/`;
+    return target.startsWith(prefix);
+}
+export function createFileDeleteTool(options) {
+    return {
+        label: "File Delete",
+        name: "file_delete",
+        description: "Delete a file or folder in the workspace. " +
+            "Path is relative to the workspace root. " +
+            "For non-empty directories, set recursive=true. " +
+            "Cannot delete protected structural paths (agents/, IDENTITY.md, SOUL.md, etc.).",
+        parameters: FileDeleteSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const rawPath = readStringParam(params, "path", { required: true });
+            const recursive = typeof params.recursive === "boolean" ? params.recursive : false;
+            // ── Resolve workspace root ──────────────────────────────────
+            const cfg = options?.config;
+            if (!cfg) {
+                return jsonResult({ error: "No config available — cannot resolve workspace." });
+            }
+            const agentId = resolveSessionAgentId({
+                sessionKey: options?.agentSessionKey,
+                config: cfg,
+            });
+            const workspaceRoot = resolveAgentWorkspaceRoot(cfg, agentId);
+            // ── Normalise and resolve target ────────────────────────────
+            // Reject obviously malicious patterns before touching the filesystem.
+            if (rawPath.includes("\0")) {
+                return jsonResult({ error: "Invalid path." });
+            }
+            const resolved = path.resolve(workspaceRoot, rawPath);
+            // ── Containment check (pre-realpath) ────────────────────────
+            if (!isInsideRoot(resolved, workspaceRoot)) {
+                return jsonResult({ error: "Path is outside the workspace." });
+            }
+            // ── Check existence ─────────────────────────────────────────
+            let stat;
+            try {
+                stat = await fs.lstat(resolved);
+            }
+            catch {
+                return jsonResult({ error: `Not found: ${rawPath}` });
+            }
+            // ── Containment check (post-realpath, catches symlink escapes) ─
+            let realTarget;
+            try {
+                realTarget = await realpath(resolved);
+            }
+            catch {
+                // If realpath fails but lstat succeeded, it's a broken symlink — safe to delete.
+                realTarget = resolved;
+            }
+            let realRoot;
+            try {
+                realRoot = await realpath(workspaceRoot);
+            }
+            catch {
+                return jsonResult({ error: "Workspace root is not accessible." });
+            }
+            if (!isInsideRoot(realTarget, realRoot)) {
+                return jsonResult({ error: "Path resolves outside the workspace." });
+            }
+            // ── Protected path check ────────────────────────────────────
+            const relative = path.relative(realRoot, realTarget);
+            const topSegment = relative.split(path.sep)[0];
+            if (topSegment && PROTECTED_TOP_LEVEL.has(topSegment)) {
+                return jsonResult({
+                    error: `Cannot delete protected path: ${topSegment} is a structural workspace entry.`,
+                });
+            }
+            // ── Delete ──────────────────────────────────────────────────
+            try {
+                if (stat.isDirectory()) {
+                    if (recursive) {
+                        await fs.rm(resolved, { recursive: true, force: true });
+                    }
+                    else {
+                        // rmdir only works on empty directories
+                        await fs.rmdir(resolved);
+                    }
+                }
+                else {
+                    await fs.unlink(resolved);
+                }
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                if (message.includes("not empty") || message.includes("ENOTEMPTY")) {
+                    return jsonResult({
+                        error: `Directory is not empty. Set recursive=true to delete '${rawPath}' and all its contents.`,
+                    });
+                }
+                return jsonResult({ error: `Failed to delete: ${message}` });
+            }
+            return jsonResult({
+                ok: true,
+                action: "deleted",
+                path: rawPath,
+                type: stat.isDirectory() ? "directory" : "file",
+                recursive,
+            });
+        },
+    };
+}

package/dist/agents/tools/file-list-tool.js

@@ -0,0 +1,127 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { realpath } from "node:fs/promises";
+import { Type } from "@sinclair/typebox";
+import { resolveAgentWorkspaceRoot, resolveSessionAgentId } from "../agent-scope.js";
+import { jsonResult, readStringParam, readNumberParam } from "./common.js";
+const FileListSchema = Type.Object({
+    path: Type.Optional(Type.String({
+        description: "Directory to list, relative to the workspace root " +
+            "(e.g. 'memory/users', 'skills'). Defaults to the workspace root.",
+    })),
+    depth: Type.Optional(Type.Number({
+        description: "How many levels deep to recurse. 1 = immediate children only (default). " +
+            "Use 2–3 for a broader view. Maximum 5.",
+    })),
+});
+function isInsideRoot(target, root) {
+    const prefix = root.endsWith("/") ? root : `${root}/`;
+    return target === root || target.startsWith(prefix);
+}
+async function listDir(dirPath, currentDepth, maxDepth) {
+    let entries;
+    try {
+        entries = await fs.readdir(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const result = [];
+    // Sort: directories first, then files, alphabetical within each group
+    const sorted = [...entries].sort((a, b) => {
+        const aDir = a.isDirectory() || a.isSymbolicLink() ? 0 : 1;
+        const bDir = b.isDirectory() || b.isSymbolicLink() ? 0 : 1;
+        if (aDir !== bDir)
+            return aDir - bDir;
+        return String(a.name).localeCompare(String(b.name));
+    });
+    for (const entry of sorted) {
+        const name = String(entry.name);
+        const fullPath = path.join(dirPath, name);
+        const item = {
+            name,
+            type: entry.isDirectory() ? "directory" : entry.isSymbolicLink() ? "symlink" : "file",
+        };
+        if (entry.isFile()) {
+            try {
+                const stat = await fs.stat(fullPath);
+                item.size = stat.size;
+            }
+            catch {
+                // stat failed — skip size
+            }
+        }
+        if ((entry.isDirectory() || entry.isSymbolicLink()) && currentDepth < maxDepth) {
+            item.children = await listDir(fullPath, currentDepth + 1, maxDepth);
+        }
+        result.push(item);
+    }
+    return result;
+}
+export function createFileListTool(options) {
+    return {
+        label: "File List",
+        name: "file_list",
+        description: "List files and folders in the workspace. " +
+            "Path is relative to the workspace root. " +
+            "Returns names, types (file/directory/symlink), and sizes. " +
+            "Use depth > 1 to see nested contents.",
+        parameters: FileListSchema,
+        execute: async (_toolCallId, args) => {
+            const params = args;
+            const rawPath = readStringParam(params, "path") ?? "";
+            const rawDepth = readNumberParam(params, "depth", { integer: true });
+            const maxDepth = Math.max(1, Math.min(rawDepth ?? 1, 5));
+            // ── Resolve workspace root ──────────────────────────────────
+            const cfg = options?.config;
+            if (!cfg) {
+                return jsonResult({ error: "No config available — cannot resolve workspace." });
+            }
+            const agentId = resolveSessionAgentId({
+                sessionKey: options?.agentSessionKey,
+                config: cfg,
+            });
+            const workspaceRoot = resolveAgentWorkspaceRoot(cfg, agentId);
+            // ── Normalise and resolve target ────────────────────────────
+            if (rawPath.includes("\0")) {
+                return jsonResult({ error: "Invalid path." });
+            }
+            const resolved = rawPath ? path.resolve(workspaceRoot, rawPath) : workspaceRoot;
+            // ── Containment check ───────────────────────────────────────
+            let realTarget;
+            try {
+                realTarget = await realpath(resolved);
+            }
+            catch {
+                return jsonResult({ error: `Not found: ${rawPath || "/"}` });
+            }
+            let realRoot;
+            try {
+                realRoot = await realpath(workspaceRoot);
+            }
+            catch {
+                return jsonResult({ error: "Workspace root is not accessible." });
+            }
+            if (!isInsideRoot(realTarget, realRoot)) {
+                return jsonResult({ error: "Path is outside the workspace." });
+            }
+            // ── Verify it's a directory ─────────────────────────────────
+            try {
+                const stat = await fs.stat(realTarget);
+                if (!stat.isDirectory()) {
+                    return jsonResult({ error: `Not a directory: ${rawPath}` });
+                }
+            }
+            catch {
+                return jsonResult({ error: `Not found: ${rawPath || "/"}` });
+            }
+            // ── List ────────────────────────────────────────────────────
+            const entries = await listDir(realTarget, 1, maxDepth);
+            return jsonResult({
+                path: rawPath || "/",
+                depth: maxDepth,
+                entries,
+            });
+        },
+    };
+}

package/dist/agents/tools/message-history-tool.js

@@ -125,10 +125,9 @@ function resolveArchiveSubdir(params) {
     if (source === "admin") {
         return { subdir: "admin" };
     }
-    // Phone number — DM archive
+    // Phone number — always resolve to user archive
     if (source.startsWith("+")) {
-        const subdir = isAdminAgent ? "admin" : `users/${source}`;
-        return { subdir };
+        return { subdir: `users/${source}` };
     }
     // Group JID
     if (source.includes("@g.us")) {

package/dist/auto-reply/media-note.js

@@ -26,6 +26,17 @@ export function buildInboundMediaNote(ctx) {
             }
         }
     }
+    // Audio attachments must NOT be suppressed even when transcription succeeds.
+    // The [media attached: ...] annotation is stored alongside the transcript so
+    // the chat UI can render an audio playback widget via chat-sanitize.
+    const typesArray = Array.isArray(ctx.MediaTypes) ? ctx.MediaTypes : [];
+    const singleType = ctx.MediaType?.trim();
+    for (const idx of [...suppressed]) {
+        const mime = (typesArray[idx] ?? singleType ?? "").split(";")[0].trim();
+        if (mime.startsWith("audio/")) {
+            suppressed.delete(idx);
+        }
+    }
     const pathsFromArray = Array.isArray(ctx.MediaPaths) ? ctx.MediaPaths : undefined;
     const paths = pathsFromArray && pathsFromArray.length > 0
         ? pathsFromArray