@4onstudios/iris-agent 0.1.0

package/dist/api/core/agent/utils/toolLifecycle.js

@@ -0,0 +1,361 @@
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "failed",
+    "error",
+    "success",
+    "ok",
+    "rejected",
+]);
+const IN_PROGRESS_STATUSES = new Set([
+    "in_progress",
+    "pending",
+    "queued",
+    "running",
+    "started",
+]);
+const stableStringify = (value) => {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    return `{${keys
+        .map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`)
+        .join(",")}}`;
+};
+export const resolveToolExecutionStatus = (result) => {
+    if (typeof result === "string")
+        return "completed";
+    if (result === null || result === undefined)
+        return "unknown";
+    if (typeof result !== "object")
+        return "completed";
+    const direct = result;
+    const nested = direct.value;
+    const directStatus = typeof direct.status === "string" ? direct.status.toLowerCase() : null;
+    const nestedStatus = typeof nested?.status === "string" ? nested.status.toLowerCase() : null;
+    const rawStatus = directStatus ?? nestedStatus;
+    const successFlag = direct.success ?? nested?.success;
+    if (typeof successFlag === "boolean") {
+        if (successFlag)
+            return "completed";
+        return "failed";
+    }
+    if (rawStatus === "pending_confirmation")
+        return rawStatus;
+    if (rawStatus && ["pending", "queued", "started"].includes(rawStatus))
+        return "pending";
+    if (rawStatus && ["in_progress", "running"].includes(rawStatus))
+        return "in_progress";
+    if (rawStatus && ["completed", "success", "ok"].includes(rawStatus))
+        return "completed";
+    if (rawStatus && ["failed", "error", "rejected"].includes(rawStatus))
+        return "failed";
+    const hasErrorFlag = direct.isError === true ||
+        direct.is_error === true ||
+        nested?.isError === true ||
+        nested?.is_error === true;
+    const hasErrorMessage = Boolean(direct.error || nested?.error);
+    if (hasErrorFlag || hasErrorMessage)
+        return "failed";
+    return "completed";
+};
+const isTerminalResult = (result) => {
+    return TERMINAL_STATUSES.has(resolveToolExecutionStatus(result));
+};
+const isSettledForPendingReconciliation = (result) => {
+    const status = resolveToolExecutionStatus(result);
+    return status === "pending_confirmation" || TERMINAL_STATUSES.has(status);
+};
+const getResultRank = (result) => {
+    const status = resolveToolExecutionStatus(result);
+    if (status === "unknown")
+        return 1;
+    if (TERMINAL_STATUSES.has(status))
+        return 3;
+    if (IN_PROGRESS_STATUSES.has(status))
+        return 0;
+    return 2;
+};
+const buildDedupKey = (name, args, toolCallId, catalog) => {
+    const signatureKey = buildSignatureKey(name, args || {});
+    if (toolCallId) {
+        return resolveIdentifiedKey(name, args || {}, toolCallId, catalog);
+    }
+    return signatureKey;
+};
+const buildSignatureKey = (name, args) => `sig:${name}:${stableStringify(args)}`;
+export const getToolCallSignature = (name, args) => buildSignatureKey(name, args);
+const hasArgumentDetails = (args) => Object.keys(args || {}).length > 0;
+const buildToolInvocationCatalog = (entries) => {
+    const catalog = new Map();
+    for (const entry of entries) {
+        if (!entry.toolCallId)
+            continue;
+        const signatureKey = buildSignatureKey(entry.name, entry.args || {});
+        const existing = catalog.get(entry.toolCallId) || [];
+        existing.push({
+            toolCallId: entry.toolCallId,
+            name: entry.name,
+            args: entry.args || {},
+            signatureKey,
+            hasArgumentDetails: hasArgumentDetails(entry.args || {}),
+        });
+        catalog.set(entry.toolCallId, existing);
+    }
+    return catalog;
+};
+const resolveUniqueDetailedInvocation = (name, toolCallId, catalog) => {
+    if (!catalog)
+        return undefined;
+    const candidates = (catalog.get(toolCallId) || []).filter((entry) => entry.name === name && entry.hasArgumentDetails);
+    const candidateSignatures = new Set(candidates.map((entry) => entry.signatureKey));
+    if (candidateSignatures.size !== 1) {
+        return undefined;
+    }
+    return candidates[0];
+};
+const resolveIdentifiedKey = (name, args, toolCallId, catalog) => {
+    const signatureKey = buildSignatureKey(name, args || {});
+    if (!catalog || hasArgumentDetails(args || {})) {
+        return `id:${toolCallId}:${signatureKey}`;
+    }
+    const resolvedInvocation = resolveUniqueDetailedInvocation(name, toolCallId, catalog);
+    if (resolvedInvocation) {
+        return `id:${toolCallId}:${resolvedInvocation.signatureKey}`;
+    }
+    return `id:${toolCallId}:${signatureKey}`;
+};
+const resolveIdentifiedArgs = (name, args, toolCallId, catalog) => {
+    if (!toolCallId || hasArgumentDetails(args || {})) {
+        return args || {};
+    }
+    const resolvedInvocation = resolveUniqueDetailedInvocation(name, toolCallId, catalog);
+    return resolvedInvocation?.args || (args || {});
+};
+const extractSignatureFromIdentifiedKey = (key) => {
+    const marker = ":sig:";
+    const markerIndex = key.indexOf(marker);
+    if (markerIndex === -1) {
+        return key;
+    }
+    return `sig:${key.slice(markerIndex + marker.length)}`;
+};
+const hasSameLifecycleStep = (current, previous) => current.lifecycleStepIndex === undefined ||
+    previous.lifecycleStepIndex === undefined ||
+    current.lifecycleStepIndex === previous.lifecycleStepIndex;
+const canReuseSameResultKey = (current, previous) => {
+    if (isTerminalResult(current.result) && isTerminalResult(previous.result)) {
+        return hasSameLifecycleStep(current, previous);
+    }
+    return true;
+};
+export const countUniqueToolCalls = (pendingToolCalls, executedToolResults) => {
+    const identifiedCatalog = buildToolInvocationCatalog([
+        ...pendingToolCalls,
+        ...executedToolResults,
+    ]);
+    const seenIds = new Set();
+    const identifiedCounts = new Map();
+    const pendingAnonymousCounts = new Map();
+    const executedAnonymousCounts = new Map();
+    for (const call of [...pendingToolCalls, ...executedToolResults]) {
+        if (call.toolCallId) {
+            const key = buildDedupKey(call.name, call.args || {}, call.toolCallId, identifiedCatalog);
+            if (seenIds.has(key))
+                continue;
+            seenIds.add(key);
+            const signatureKey = extractSignatureFromIdentifiedKey(key);
+            identifiedCounts.set(signatureKey, (identifiedCounts.get(signatureKey) || 0) + 1);
+        }
+    }
+    for (const call of pendingToolCalls) {
+        if (call.toolCallId)
+            continue;
+        const signatureKey = buildSignatureKey(call.name, call.args || {});
+        pendingAnonymousCounts.set(signatureKey, (pendingAnonymousCounts.get(signatureKey) || 0) + 1);
+    }
+    for (const result of executedToolResults) {
+        if (result.toolCallId)
+            continue;
+        const signatureKey = buildSignatureKey(result.name, result.args || {});
+        const counts = executedAnonymousCounts.get(signatureKey) || {
+            terminal: 0,
+            inProgress: 0,
+            unknown: 0,
+        };
+        const status = resolveToolExecutionStatus("result" in result ? result.result : undefined);
+        if (TERMINAL_STATUSES.has(status)) {
+            counts.terminal += 1;
+        }
+        else if (IN_PROGRESS_STATUSES.has(status)) {
+            counts.inProgress += 1;
+        }
+        else {
+            counts.unknown += 1;
+        }
+        executedAnonymousCounts.set(signatureKey, counts);
+    }
+    const signatures = new Set([
+        ...identifiedCounts.keys(),
+        ...pendingAnonymousCounts.keys(),
+        ...executedAnonymousCounts.keys(),
+    ]);
+    return Array.from(signatures).reduce((total, signatureKey) => {
+        const executedAnonymous = executedAnonymousCounts.get(signatureKey);
+        // Identified calls and anonymous pending calls are distinct invocations
+        // even when they share a signature, so they contribute additively.
+        const invocations = (identifiedCounts.get(signatureKey) || 0) +
+            (pendingAnonymousCounts.get(signatureKey) || 0);
+        // Anonymous result snapshots are overlapping evidence of invocations
+        // already counted above, so they only raise the floor.
+        const anonymousResultEvidence = Math.max(executedAnonymous?.terminal || 0, executedAnonymous?.inProgress || 0, executedAnonymous?.unknown || 0);
+        return total + Math.max(invocations, anonymousResultEvidence);
+    }, 0);
+};
+export const normalizeToolLifecycle = (pendingToolCalls, executedToolResults) => {
+    const identifiedCatalog = buildToolInvocationCatalog([
+        ...pendingToolCalls,
+        ...executedToolResults,
+    ]);
+    const executedByKey = new Map();
+    const anonymousResultKeysBySignature = new Map();
+    // Include identified pending calls when establishing cardinality: an
+    // anonymous (missing-ID) executed result can settle an identified pending
+    // call (see the pending-reconciliation pass below), so an identified
+    // pending call also represents a known invocation slot for its signature.
+    const pendingSignatureCounts = new Map();
+    for (const call of pendingToolCalls) {
+        const signatureKey = buildSignatureKey(call.name, call.args || {});
+        pendingSignatureCounts.set(signatureKey, (pendingSignatureCounts.get(signatureKey) || 0) + 1);
+    }
+    for (const item of executedToolResults) {
+        const resolvedArgs = resolveIdentifiedArgs(item.name, item.args || {}, item.toolCallId, identifiedCatalog);
+        const normalizedItem = resolvedArgs === (item.args || {})
+            ? item
+            : { ...item, args: resolvedArgs };
+        const signatureKey = buildSignatureKey(normalizedItem.name, normalizedItem.args || {});
+        const anonymousKeys = anonymousResultKeysBySignature.get(signatureKey) || [];
+        const pendingCount = pendingSignatureCounts.get(signatureKey) || 0;
+        // Prefer completing an outstanding lower-rank result (transitionKey) before
+        // collapsing into an identical terminal snapshot (sameResultKey). Only
+        // treat an identical payload as a duplicate once we already have at least
+        // as many results as known pending invocations (identified or anonymous)
+        // for this signature. A pendingCount of 0 means there is no established
+        // invocation cardinality for anonymous calls (e.g. only executed results,
+        // no pending calls at all), so these same-rank collapsing rules must not
+        // apply — otherwise distinct anonymous results with the same signature
+        // would be merged as if they were snapshots of a single invocation.
+        const hasEstablishedCardinality = pendingCount > 0 && anonymousKeys.length >= pendingCount;
+        const transitionKey = anonymousKeys.find((candidateKey) => {
+            const previous = executedByKey.get(candidateKey);
+            return (previous &&
+                getResultRank(normalizedItem.result) > getResultRank(previous.result));
+        });
+        const sameResultKey = hasEstablishedCardinality
+            ? anonymousKeys.find((candidateKey) => {
+                const previous = executedByKey.get(candidateKey);
+                return (previous &&
+                    canReuseSameResultKey(normalizedItem, previous) &&
+                    stableStringify(previous.result) ===
+                        stableStringify(normalizedItem.result));
+            })
+            : undefined;
+        const sameRankProgressKey = hasEstablishedCardinality
+            ? anonymousKeys.find((candidateKey) => {
+                const previous = executedByKey.get(candidateKey);
+                return (previous &&
+                    resolveToolExecutionStatus(previous.result) === "in_progress" &&
+                    resolveToolExecutionStatus(normalizedItem.result) === "in_progress");
+            })
+            : undefined;
+        const sameRankTerminalKey = hasEstablishedCardinality
+            ? anonymousKeys.find((candidateKey) => {
+                const previous = executedByKey.get(candidateKey);
+                return (previous &&
+                    hasSameLifecycleStep(normalizedItem, previous) &&
+                    isTerminalResult(previous.result) &&
+                    isTerminalResult(normalizedItem.result) &&
+                    getResultRank(normalizedItem.result) ===
+                        getResultRank(previous.result));
+            })
+            : undefined;
+        const key = normalizedItem.toolCallId
+            ? buildDedupKey(normalizedItem.name, normalizedItem.args || {}, normalizedItem.toolCallId, identifiedCatalog)
+            : transitionKey ||
+                sameResultKey ||
+                sameRankProgressKey ||
+                sameRankTerminalKey ||
+                `${signatureKey}:${anonymousKeys.length}`;
+        const previous = executedByKey.get(key);
+        if (!previous) {
+            executedByKey.set(key, normalizedItem);
+            if (!normalizedItem.toolCallId) {
+                const keys = anonymousResultKeysBySignature.get(signatureKey) || [];
+                keys.push(key);
+                anonymousResultKeysBySignature.set(signatureKey, keys);
+            }
+            continue;
+        }
+        const prevRank = getResultRank(previous.result);
+        const nextRank = getResultRank(normalizedItem.result);
+        const isInProgressUpdate = resolveToolExecutionStatus(previous.result) === "in_progress" &&
+            resolveToolExecutionStatus(normalizedItem.result) === "in_progress";
+        // Once two results share this key, they are already confirmed to be the
+        // same invocation (via toolCallId, or via transitionKey/sameResultKey/
+        // sameRankProgressKey/sameRankTerminalKey for anonymous calls). So an
+        // equal-rank update should always replace the prior snapshot with the
+        // latest one, even when the payloads differ (e.g. failed -> completed).
+        if (nextRank >= prevRank || isInProgressUpdate) {
+            executedByKey.set(key, normalizedItem);
+        }
+    }
+    const normalizedExecuted = Array.from(executedByKey.values());
+    const settledExecutedKeys = new Set(normalizedExecuted
+        .filter((result) => isSettledForPendingReconciliation(result.result))
+        .map((result) => {
+        const key = buildDedupKey(result.name, result.args || {}, result.toolCallId, identifiedCatalog);
+        return key;
+    }));
+    const pendingByKey = new Map();
+    const settledAnonymousResultsBySignature = new Map();
+    for (const result of normalizedExecuted) {
+        if (!result.toolCallId &&
+            isSettledForPendingReconciliation(result.result)) {
+            const signatureKey = buildSignatureKey(result.name, result.args || {});
+            settledAnonymousResultsBySignature.set(signatureKey, (settledAnonymousResultsBySignature.get(signatureKey) || 0) + 1);
+        }
+    }
+    for (const [index, item] of pendingToolCalls.entries()) {
+        const key = buildDedupKey(item.name, item.args || {}, item.toolCallId, identifiedCatalog);
+        if (item.toolCallId && settledExecutedKeys.has(key)) {
+            continue;
+        }
+        const signatureKey = buildSignatureKey(item.name, item.args || {});
+        const matchingResultWithoutId = normalizedExecuted.filter((result) => !result.toolCallId &&
+            buildSignatureKey(result.name, result.args || {}) === signatureKey);
+        const sameSignaturePendingCalls = pendingToolCalls.filter((pending) => buildSignatureKey(pending.name, pending.args || {}) === signatureKey);
+        const hasSettledMatch = matchingResultWithoutId.some((result) => isSettledForPendingReconciliation(result.result));
+        if (hasSettledMatch) {
+            const remainingSettledResults = settledAnonymousResultsBySignature.get(signatureKey) || 0;
+            if (remainingSettledResults > 0) {
+                settledAnonymousResultsBySignature.set(signatureKey, remainingSettledResults - 1);
+                continue;
+            }
+        }
+        const preserveAnonymousMultiplicity = !item.toolCallId && sameSignaturePendingCalls.length > 1;
+        const pendingKey = preserveAnonymousMultiplicity
+            ? `${signatureKey}:${index}`
+            : item.toolCallId || sameSignaturePendingCalls.length === 1
+                ? key
+                : signatureKey;
+        pendingByKey.set(pendingKey, item);
+    }
+    return {
+        pendingToolCalls: Array.from(pendingByKey.values()),
+        executedToolResults: normalizedExecuted,
+    };
+};

package/dist/api/core/agent/utils/toolResultSafetyProcessor.d.ts

@@ -0,0 +1,12 @@
+import type { Processor } from "@mastra/core/processors";
+type RedactionSummary = {
+    result: unknown;
+    redactionCount: number;
+    redactionTypes: Set<string>;
+};
+export declare const redactToolResult: (value: unknown, seen?: WeakMap<object, unknown>) => RedactionSummary;
+export declare class ToolResultSafetyProcessor implements Processor {
+    readonly id = "tool-result-safety";
+    processToolResult({ toolName, toolCallId, args, result, messageList, }: Parameters<NonNullable<Processor["processToolResult"]>>[0]): Promise<import("@mastra/core/agent").MessageList>;
+}
+export {};

package/dist/api/core/agent/utils/toolResultSafetyProcessor.js

@@ -0,0 +1,57 @@
+import { redact } from "../../library/safetyMiddleware.js";
+export const redactToolResult = (value, seen = new WeakMap()) => {
+    if (typeof value === "string") {
+        const { output, redactions } = redact(value);
+        return {
+            result: output,
+            redactionCount: redactions.length,
+            redactionTypes: new Set(redactions.map((entry) => entry.type)),
+        };
+    }
+    if (value === null || typeof value !== "object") {
+        return { result: value, redactionCount: 0, redactionTypes: new Set() };
+    }
+    const existing = seen.get(value);
+    if (existing !== undefined) {
+        return { result: existing, redactionCount: 0, redactionTypes: new Set() };
+    }
+    const output = Array.isArray(value)
+        ? []
+        : {};
+    seen.set(value, output);
+    let redactionCount = 0;
+    const redactionTypes = new Set();
+    for (const [key, entry] of Object.entries(value)) {
+        const redacted = redactToolResult(entry, seen);
+        output[key] = redacted.result;
+        redactionCount += redacted.redactionCount;
+        redacted.redactionTypes.forEach((type) => redactionTypes.add(type));
+    }
+    return { result: output, redactionCount, redactionTypes };
+};
+export class ToolResultSafetyProcessor {
+    id = "tool-result-safety";
+    async processToolResult({ toolName, toolCallId, args, result, messageList, }) {
+        const redacted = redactToolResult(result);
+        if (redacted.redactionCount === 0) {
+            return messageList;
+        }
+        messageList.updateToolInvocation({
+            type: "tool-invocation",
+            toolInvocation: {
+                state: "result",
+                toolCallId,
+                toolName,
+                args,
+                result: redacted.result,
+            },
+        });
+        console.warn("Redacted sensitive data from tool result", {
+            processorId: this.id,
+            toolName,
+            redactionCount: redacted.redactionCount,
+            redactionTypes: Array.from(redacted.redactionTypes).sort(),
+        });
+        return messageList;
+    }
+}

package/dist/api/core/agent/utils/workspaceMutationBridge.d.ts

@@ -0,0 +1,13 @@
+import type { Processor } from "@mastra/core/processors";
+import { type WorkspaceToolHooks } from "@mastra/core/workspace";
+type ValidationResult = Record<string, unknown> | null;
+export declare class WorkspaceMutationBridge implements Processor {
+    private readonly basePath;
+    private readonly validate;
+    readonly id = "workspace-mutation-bridge";
+    private readonly snapshots;
+    constructor(basePath: string, validate: () => Promise<ValidationResult>);
+    readonly hooks: WorkspaceToolHooks;
+    processToolResult({ toolName, toolCallId, args, result, messageList, }: Parameters<NonNullable<Processor["processToolResult"]>>[0]): Promise<import("@mastra/core/agent").MessageList>;
+}
+export {};

package/dist/api/core/agent/utils/workspaceMutationBridge.js

@@ -0,0 +1,149 @@
+import fs from "fs/promises";
+import path from "path";
+import { WORKSPACE_TOOLS, } from "@mastra/core/workspace";
+import { generateDiff } from "./diffUtils.js";
+const MUTATION_TOOLS = new Set([
+    WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE,
+    WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE,
+    WORKSPACE_TOOLS.FILESYSTEM.DELETE,
+    WORKSPACE_TOOLS.FILESYSTEM.MKDIR,
+]);
+const VALIDATED_TOOLS = new Set([
+    WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE,
+    WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE,
+]);
+const getToolCallId = (context) => {
+    if (!context || typeof context !== "object")
+        return undefined;
+    const value = context.toolCallId;
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+const getInputPath = (input) => {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const value = input.path;
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+};
+const isFailedOutput = (output) => {
+    if (typeof output === "string") {
+        return /^(error:|cannot edit|could not find|found \d+ occurrences)/i.test(output.trim());
+    }
+    if (!output || typeof output !== "object")
+        return false;
+    const structured = output;
+    return (structured.success === false ||
+        typeof structured.error === "string" ||
+        ("value" in structured && isFailedOutput(structured.value)));
+};
+const getOutputText = (output) => {
+    if (typeof output === "string")
+        return output;
+    if (output && typeof output === "object") {
+        const structured = output;
+        if (typeof structured.error === "string")
+            return structured.error;
+        if ("value" in structured && isFailedOutput(structured.value)) {
+            return getOutputText(structured.value);
+        }
+        try {
+            return JSON.stringify(output);
+        }
+        catch {
+            return String(output);
+        }
+    }
+    return String(output ?? "");
+};
+const readTextIfPresent = async (absolutePath) => {
+    try {
+        return { exists: true, content: await fs.readFile(absolutePath, "utf8") };
+    }
+    catch {
+        return { exists: false };
+    }
+};
+export class WorkspaceMutationBridge {
+    basePath;
+    validate;
+    id = "workspace-mutation-bridge";
+    snapshots = new Map();
+    constructor(basePath, validate) {
+        this.basePath = basePath;
+        this.validate = validate;
+    }
+    hooks = {
+        beforeToolCall: async ({ workspaceToolName, input, context }) => {
+            if (!MUTATION_TOOLS.has(workspaceToolName))
+                return;
+            const toolCallId = getToolCallId(context);
+            const inputPath = getInputPath(input);
+            if (!toolCallId || !inputPath)
+                return;
+            const absolutePath = path.resolve(this.basePath, inputPath);
+            const relativePath = path.relative(this.basePath, absolutePath);
+            if (relativePath.startsWith("..") || path.isAbsolute(relativePath))
+                return;
+            const before = await readTextIfPresent(absolutePath);
+            this.snapshots.set(toolCallId, {
+                path: absolutePath,
+                fileExisted: before.exists,
+                oldContent: before.content ??
+                    (workspaceToolName === WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE ? "" : undefined),
+            });
+        },
+        afterToolCall: async ({ workspaceToolName, context, output, error }) => {
+            if (!MUTATION_TOOLS.has(workspaceToolName))
+                return;
+            const toolCallId = getToolCallId(context);
+            if (!toolCallId)
+                return;
+            const snapshot = this.snapshots.get(toolCallId);
+            if (!snapshot || error || isFailedOutput(output))
+                return;
+            const after = await readTextIfPresent(snapshot.path);
+            snapshot.newContent = after.content;
+            if (VALIDATED_TOOLS.has(workspaceToolName)) {
+                snapshot.validation = await this.validate();
+            }
+        },
+    };
+    async processToolResult({ toolName, toolCallId, args, result, messageList, }) {
+        const snapshot = this.snapshots.get(toolCallId);
+        if (!snapshot)
+            return messageList;
+        this.snapshots.delete(toolCallId);
+        const output = getOutputText(result);
+        const failed = isFailedOutput(result);
+        const normalizedResult = {
+            success: !failed,
+            output,
+            filePath: snapshot.path,
+            fileExisted: snapshot.fileExisted,
+        };
+        if (!failed && snapshot.oldContent !== undefined && snapshot.newContent !== undefined) {
+            const { diff, linesAdded, linesRemoved } = generateDiff(snapshot.oldContent, snapshot.newContent, snapshot.path);
+            Object.assign(normalizedResult, {
+                oldContent: snapshot.oldContent,
+                newContent: snapshot.newContent,
+                diff,
+                linesAdded,
+                linesRemoved,
+            });
+        }
+        if (snapshot.validation)
+            normalizedResult.validation = snapshot.validation;
+        if (failed)
+            normalizedResult.error = output;
+        messageList.updateToolInvocation({
+            type: "tool-invocation",
+            toolInvocation: {
+                state: "result",
+                toolCallId,
+                toolName,
+                args,
+                result: normalizedResult,
+            },
+        });
+        return messageList;
+    }
+}

package/dist/api/core/agent/utils/workspacePathGuard.d.ts

@@ -0,0 +1,7 @@
+type WorkspaceMutationRejection = {
+    success: false;
+    error: string;
+};
+export declare const isWorkspaceMutationPathAllowed: (workspaceBasePath: string, filePath: string) => Promise<boolean>;
+export declare const rejectUnsafeWorkspaceMutation: (workspaceBasePath: string, isVirtualWorkspace: boolean, filePaths: string[]) => Promise<WorkspaceMutationRejection | null>;
+export {};

package/dist/api/core/agent/utils/workspacePathGuard.js

@@ -0,0 +1,79 @@
+import fs from "fs/promises";
+import path from "path";
+const isPathWithin = (basePath, targetPath) => {
+    const relative = path.relative(basePath, targetPath);
+    return !(path.isAbsolute(relative) ||
+        relative === ".." ||
+        relative.startsWith(`..${path.sep}`));
+};
+const isMissingPathError = (error) => error?.code === "ENOENT";
+const resolveExistingPath = async (targetPath) => {
+    try {
+        await fs.lstat(targetPath);
+    }
+    catch (error) {
+        if (isMissingPathError(error)) {
+            return null;
+        }
+        throw error;
+    }
+    return fs.realpath(targetPath);
+};
+export const isWorkspaceMutationPathAllowed = async (workspaceBasePath, filePath) => {
+    const resolvedWorkspace = path.resolve(workspaceBasePath);
+    const resolvedTarget = path.resolve(filePath);
+    if (!isPathWithin(resolvedWorkspace, resolvedTarget)) {
+        return false;
+    }
+    let realWorkspace;
+    try {
+        realWorkspace = await fs.realpath(resolvedWorkspace);
+    }
+    catch {
+        return false;
+    }
+    try {
+        const realTarget = await resolveExistingPath(resolvedTarget);
+        if (realTarget) {
+            return isPathWithin(realWorkspace, realTarget);
+        }
+    }
+    catch {
+        return false;
+    }
+    // New files do not have a realpath yet. Validate the nearest existing
+    // ancestor, rejecting dangling symlinks and non-ENOENT filesystem errors.
+    let ancestor = path.dirname(resolvedTarget);
+    while (isPathWithin(resolvedWorkspace, ancestor)) {
+        try {
+            const realAncestor = await resolveExistingPath(ancestor);
+            if (realAncestor) {
+                return isPathWithin(realWorkspace, realAncestor);
+            }
+        }
+        catch {
+            return false;
+        }
+        const parent = path.dirname(ancestor);
+        if (parent === ancestor)
+            break;
+        ancestor = parent;
+    }
+    return false;
+};
+export const rejectUnsafeWorkspaceMutation = async (workspaceBasePath, isVirtualWorkspace, filePaths) => {
+    if (isVirtualWorkspace) {
+        return {
+            success: false,
+            error: "Server-side filesystem mutations are disabled for virtual workspaces",
+        };
+    }
+    const allowed = await Promise.all(filePaths.map((filePath) => isWorkspaceMutationPathAllowed(workspaceBasePath, filePath)));
+    if (allowed.every(Boolean)) {
+        return null;
+    }
+    return {
+        success: false,
+        error: "File path is outside the workspace boundary",
+    };
+};