@akira-tl/forgerelay 0.8.8 → 0.8.10

package/dist/{remote-workspace-relay.js → workspaces/relay/workspace-relay.js}

@@ -1,15 +1,13 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { CallToolResultSchema } from "@modelcontextprotocol/sdk/types.js";
-import { isRemoteMcpUnauthorized, refreshRemoteAuthentication, } from "./remote-auth.js";
-import { RemoteMcpConnectionPool } from "./remote-mcp-connection-pool.js";
-import { withRemoteServiceEndpoint } from "./remote-transport.js";
-import { loadForgeRelayFiles, writeForgeRelayRemote, } from "./user-config.js";
-const ROUTE_LOCK_RETRY_MS = 10;
-const ROUTE_LOCK_TIMEOUT_MS = 5_000;
-const ROUTE_LOCK_STALE_MS = 30_000;
-const ROUTE_LOCK_SLEEP = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
+import { isRemoteMcpUnauthorized, refreshRemoteAuthentication, } from "./auth/remote-auth.js";
+import { RemoteMcpConnectionPool } from "./transport/remote-mcp-connection-pool.js";
+import { withFileLock } from "../../runtime/state/lock/file-lock.js";
+import { withRemoteServiceEndpoint } from "./transport/remote-transport.js";
+import { loadForgeRelayFiles, writeForgeRelayRemote, } from "../../runtime/config/user-config.js";
+import { assertRemoteToolSucceeded, stringField, copyStringField, copyBooleanField, copyNumberField, safeTaskSummary, toolResultText, remapToolResultWorkspaceId, replaceExactWorkspaceId, sanitizedRemoteError, errorMessage } from "./result-support.js";
 export class RemoteWorkspaceRelay {
     routes = new Map();
     turnRoutes = new Map();
@@ -109,7 +107,7 @@ export class RemoteWorkspaceRelay {
             throw new Error("Remote open_workspace response did not include a valid workspace mode.");
         }
         const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : undefined;
-        const route = this.findOrCreateRoute({
+        const route = await this.findOrCreateRoute({
             remoteInstanceId: resolved.remote.instanceId,
             remoteWorkspaceId,
             root,
@@ -167,7 +165,7 @@ export class RemoteWorkspaceRelay {
             ? structured.mode
             : route.mode;
         const sourceRoot = typeof structured?.sourceRoot === "string" ? structured.sourceRoot : route.sourceRoot;
-        this.findOrCreateRoute({
+        await this.findOrCreateRoute({
             remoteInstanceId: route.remoteInstanceId,
             remoteWorkspaceId: route.remoteWorkspaceId,
             root,
@@ -194,6 +192,9 @@ export class RemoteWorkspaceRelay {
     async bash(gatewayWorkspaceId, input, conversationScopeId) {
         return this.callWorkspaceTool(gatewayWorkspaceId, "bash", input, conversationScopeId);
     }
+    async workspaceInstruction(gatewayWorkspaceId, path, conversationScopeId) {
+        return this.callWorkspaceTool(gatewayWorkspaceId, "workspace_instruction", { path }, conversationScopeId);
+    }
     async execCommand(gatewayWorkspaceId, input, conversationScopeId) {
         return this.callWorkspaceTool(gatewayWorkspaceId, "exec_command", input, conversationScopeId);
     }
@@ -296,7 +297,7 @@ export class RemoteWorkspaceRelay {
         const remoteStructured = result.structuredContent;
         if (action === "delete") {
             this.routes.delete(gatewayWorkspaceId);
-            this.deletePersistedRoute(gatewayWorkspaceId);
+            await this.deletePersistedRoute(gatewayWorkspaceId);
         }
         for (const [turnId, routedWorkspaceId] of this.turnRoutes) {
             if (routedWorkspaceId === gatewayWorkspaceId)
@@ -356,35 +357,33 @@ export class RemoteWorkspaceRelay {
             this.routes.set(workspaceId, route);
         }
     }
-    findOrCreateRoute(input) {
-        let selected;
+    async findOrCreateRoute(input) {
         mkdirSync(this.routeStateDir, { recursive: true });
-        this.withRouteFileLock(() => {
+        const selected = await withFileLock(`${this.routeStatePath}.lock`, () => {
             const routes = this.readRoutesFromDisk();
             const existing = [...routes.values()]
                 .filter((route) => route.remoteInstanceId === input.remoteInstanceId &&
                 route.remoteWorkspaceId === input.remoteWorkspaceId)
                 .sort((left, right) => left.gatewayWorkspaceId.localeCompare(right.gatewayWorkspaceId))[0];
-            selected = {
+            const route = {
                 gatewayWorkspaceId: existing?.gatewayWorkspaceId ?? this.allocateGatewayWorkspaceId(routes),
                 ...input,
             };
-            routes.set(selected.gatewayWorkspaceId, selected);
+            routes.set(route.gatewayWorkspaceId, route);
             this.writeRoutesToDisk(routes);
+            return route;
         });
-        if (!selected)
-            throw new Error("Failed to persist relayed Workspace route.");
         this.routes.set(selected.gatewayWorkspaceId, selected);
         return selected;
     }
-    deletePersistedRoute(workspaceId) {
-        this.updatePersistedRoutes((routes) => {
+    async deletePersistedRoute(workspaceId) {
+        await this.updatePersistedRoutes((routes) => {
             routes.delete(workspaceId);
         });
     }
-    updatePersistedRoutes(update) {
+    async updatePersistedRoutes(update) {
         mkdirSync(this.routeStateDir, { recursive: true });
-        this.withRouteFileLock(() => {
+        await withFileLock(`${this.routeStatePath}.lock`, () => {
             const routes = this.readRoutesFromDisk();
             update(routes);
             this.writeRoutesToDisk(routes);
@@ -418,43 +417,6 @@ export class RemoteWorkspaceRelay {
             rmSync(tempPath, { force: true });
         }
     }
-    withRouteFileLock(operation) {
-        const lockPath = `${this.routeStatePath}.lock`;
-        const deadline = Date.now() + ROUTE_LOCK_TIMEOUT_MS;
-        for (;;) {
-            try {
-                const fd = openSync(lockPath, "wx", 0o600);
-                closeSync(fd);
-                break;
-            }
-            catch (error) {
-                const code = error.code;
-                if (code !== "EEXIST")
-                    throw error;
-                try {
-                    if (Date.now() - statSync(lockPath).mtimeMs > ROUTE_LOCK_STALE_MS) {
-                        rmSync(lockPath, { force: true });
-                        continue;
-                    }
-                }
-                catch (statError) {
-                    if (statError.code === "ENOENT")
-                        continue;
-                    throw statError;
-                }
-                if (Date.now() >= deadline) {
-                    throw new Error(`Timed out waiting for relayed workspace route lock: ${lockPath}`);
-                }
-                Atomics.wait(ROUTE_LOCK_SLEEP, 0, 0, ROUTE_LOCK_RETRY_MS);
-            }
-        }
-        try {
-            return operation();
-        }
-        finally {
-            rmSync(lockPath, { force: true });
-        }
-    }
     remoteByAlias(aliasInput) {
         const alias = aliasInput.trim();
         if (!alias)
@@ -522,7 +484,7 @@ export class RemoteWorkspaceRelay {
     }
     async refreshRemote(alias, remote, endpoint) {
         const refreshed = await refreshRemoteAuthentication(remote, endpoint);
-        writeForgeRelayRemote(alias, refreshed, this.authEnv);
+        await writeForgeRelayRemote(alias, refreshed, this.authEnv);
         return refreshed;
     }
     allocateGatewayWorkspaceId(routes = this.routes) {
@@ -533,114 +495,3 @@ export class RemoteWorkspaceRelay {
         return workspaceId;
     }
 }
-function assertRemoteToolSucceeded(alias, tool, result) {
-    if (result.isError !== true)
-        return;
-    throw new Error(`Remote ForgeRelay ${alias} ${tool} failed: ${toolResultText(result)}`);
-}
-function stringField(structured, field, label) {
-    const value = structured?.[field];
-    if (typeof value !== "string" || !value) {
-        throw new Error(`${label} did not include ${field}.`);
-    }
-    return value;
-}
-function copyStringField(source, target, field) {
-    const value = source[field];
-    if (typeof value === "string")
-        target[field] = value;
-}
-function copyBooleanField(source, target, field) {
-    const value = source[field];
-    if (typeof value === "boolean")
-        target[field] = value;
-}
-function copyNumberField(source, target, field) {
-    const value = source[field];
-    if (typeof value === "number" && Number.isFinite(value) && value >= 0)
-        target[field] = value;
-}
-function safeTaskSummary(value) {
-    if (!value || typeof value !== "object")
-        return undefined;
-    const summary = value;
-    if (summary.level !== "summary" ||
-        summary.version !== 1 ||
-        typeof summary.revision !== "number" ||
-        !Number.isInteger(summary.revision) ||
-        summary.revision < 0 ||
-        !Array.isArray(summary.lists)) {
-        return undefined;
-    }
-    const lists = [];
-    for (const value of summary.lists) {
-        if (!value || typeof value !== "object")
-            return undefined;
-        const list = value;
-        if (typeof list.id !== "string" ||
-            typeof list.name !== "string" ||
-            (list.state !== "active" && list.state !== "archived") ||
-            typeof list.revision !== "number" || !Number.isInteger(list.revision) || list.revision <= 0 ||
-            typeof list.taskCount !== "number" || !Number.isInteger(list.taskCount) || list.taskCount < 0 ||
-            typeof list.unfinishedTaskCount !== "number" || !Number.isInteger(list.unfinishedTaskCount) || list.unfinishedTaskCount < 0) {
-            return undefined;
-        }
-        lists.push({
-            id: list.id,
-            name: list.name,
-            state: list.state,
-            revision: list.revision,
-            taskCount: list.taskCount,
-            unfinishedTaskCount: list.unfinishedTaskCount,
-        });
-    }
-    return {
-        level: "summary",
-        version: 1,
-        revision: summary.revision,
-        lists,
-    };
-}
-function toolResultText(result) {
-    return (result.content ?? [])
-        .filter((entry) => entry.type === "text")
-        .map((entry) => entry.text)
-        .join("\n") || "remote tool returned an error";
-}
-function remapToolResultWorkspaceId(result, remoteWorkspaceId, gatewayWorkspaceId) {
-    return {
-        ...result,
-        content: (result.content ?? []).map((entry) => entry.type === "text"
-            ? { ...entry, text: entry.text.split(remoteWorkspaceId).join(gatewayWorkspaceId) }
-            : entry),
-        ...(result._meta
-            ? { _meta: replaceExactWorkspaceId(result._meta, remoteWorkspaceId, gatewayWorkspaceId) }
-            : {}),
-        ...(result.structuredContent
-            ? {
-                structuredContent: replaceExactWorkspaceId(result.structuredContent, remoteWorkspaceId, gatewayWorkspaceId),
-            }
-            : {}),
-    };
-}
-function replaceExactWorkspaceId(value, from, to) {
-    if (typeof value === "string")
-        return value.split(from).join(to);
-    if (Array.isArray(value))
-        return value.map((entry) => replaceExactWorkspaceId(entry, from, to));
-    if (!value || typeof value !== "object")
-        return value;
-    return Object.fromEntries(Object.entries(value)
-        .map(([key, entry]) => [key, replaceExactWorkspaceId(entry, from, to)]));
-}
-function sanitizedRemoteError(error, remoteWorkspaceId, gatewayWorkspaceId) {
-    let message = errorMessage(error);
-    if (remoteWorkspaceId && gatewayWorkspaceId) {
-        message = message.split(remoteWorkspaceId).join(gatewayWorkspaceId);
-    }
-    message = message.replace(/(^|[^A-Za-z0-9_])ws_[0-9a-f]{10}(?=$|[^A-Za-z0-9_])/g, "$1[remote-workspace]");
-    return new Error(message, { cause: error });
-}
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}

package/dist/workspaces/resources/resource-monitor.js

@@ -0,0 +1,377 @@
+import { readFileSync, realpathSync, unwatchFile, watchFile } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { skillSummaryFromContent } from "./skills.js";
+const WATCH_INTERVAL_MS = 750;
+const MAX_HISTORY = 128;
+const MAX_DELIVERY_CHARACTERS = 32 * 1024;
+const MAX_PATCH_CHARACTERS = 8 * 1024;
+const sharedWatches = new Map();
+let monitorSequence = 0;
+/**
+ * Tracks already-advertised Workspace instruction and Skill files. The OS-level
+ * stat watcher is process-global and canonical-path keyed, so two Workspaces or
+ * conversations that refer to the same physical file still create only one
+ * underlying watcher. Resource changes are delivered as bounded deltas.
+ */
+export class WorkspaceResourceMonitor {
+    id = `monitor-${++monitorSequence}`;
+    states = new Map();
+    trackWorkspace(input) {
+        const state = this.states.get(input.workspaceId) ?? {
+            root: input.root,
+            revision: 0,
+            tracked: new Map(),
+            subscriptions: new Map(),
+            changes: [],
+            deliveredRevisionByScope: new Map(),
+        };
+        state.root = input.root;
+        this.states.set(input.workspaceId, state);
+        const desired = new Map();
+        for (const path of input.availableInstructions) {
+            this.addDesired(desired, path, {
+                kind: "instruction-available",
+                displayPath: displayWorkspacePath(path, input.root),
+                exposeSkillBody: false,
+            });
+        }
+        for (const path of input.loadedInstructions) {
+            this.addDesired(desired, path, {
+                kind: "instruction-loaded",
+                displayPath: displayWorkspacePath(path, input.root),
+                exposeSkillBody: false,
+            });
+        }
+        for (const skill of input.skills) {
+            this.addDesired(desired, skill.filePath, {
+                kind: "skill",
+                displayPath: `skills://${encodeURIComponent(skill.name)}`,
+                skillName: skill.name,
+                exposeSkillBody: skill.activated,
+            });
+        }
+        for (const [key, stop] of state.tracked) {
+            if (desired.has(key))
+                continue;
+            stop();
+            state.tracked.delete(key);
+            state.subscriptions.delete(key);
+        }
+        for (const [key, item] of desired) {
+            state.subscriptions.set(key, item.subscription);
+            if (state.tracked.has(key)) {
+                synchronizeSharedWatch(key);
+                continue;
+            }
+            const subscriberId = `${this.id}:${input.workspaceId}:${key}`;
+            const stop = subscribeSharedWatch(item.path, subscriberId, (oldContent, newContent) => {
+                this.recordChange(input.workspaceId, key, oldContent, newContent);
+            });
+            state.tracked.set(key, stop);
+        }
+    }
+    trackLoadedInstruction(workspaceId, root, path) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        const key = canonicalWatchKey(path);
+        state.subscriptions.set(key, {
+            kind: "instruction-loaded",
+            displayPath: displayWorkspacePath(path, root),
+            exposeSkillBody: false,
+        });
+        if (state.tracked.has(key))
+            return;
+        const subscriberId = `${this.id}:${workspaceId}:${key}`;
+        state.tracked.set(key, subscribeSharedWatch(path, subscriberId, (oldContent, newContent) => {
+            this.recordChange(workspaceId, key, oldContent, newContent);
+        }));
+    }
+    markSkillActivated(workspaceId, skillPath) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        const subscription = state.subscriptions.get(canonicalWatchKey(skillPath));
+        if (subscription?.kind === "skill")
+            subscription.exposeSkillBody = true;
+    }
+    acknowledge(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        state.deliveredRevisionByScope.set(conversationScopeId, state.revision);
+        this.pruneDeliveredHistory(state);
+    }
+    claim(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return undefined;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return undefined;
+        // File watcher delivery is advisory and can lag behind a tool call. Refresh
+        // tracked files synchronously before deciding whether this conversation has
+        // new context so rapid consecutive writes cannot be skipped.
+        for (const key of state.tracked.keys())
+            synchronizeSharedWatch(key);
+        const deliveredRevision = state.deliveredRevisionByScope.get(conversationScopeId) ?? state.revision;
+        const changes = state.changes.filter((change) => change.revision > deliveredRevision);
+        state.deliveredRevisionByScope.set(conversationScopeId, state.revision);
+        if (changes.length === 0)
+            return undefined;
+        const grouped = coalesceChanges(changes);
+        const sections = [];
+        const coveredComponents = new Set();
+        for (const change of grouped) {
+            const formatted = formatResourceChange(change);
+            if (!formatted)
+                continue;
+            sections.push(formatted.text);
+            for (const component of formatted.coveredComponents)
+                coveredComponents.add(component);
+        }
+        this.pruneDeliveredHistory(state);
+        if (sections.length === 0)
+            return undefined;
+        const header = "Workspace context changed after this Workspace was opened. Apply only these deltas; unchanged instructions and Skill metadata remain active:";
+        const joined = [header, ...sections].join("\n\n");
+        const text = joined.length <= MAX_DELIVERY_CHARACTERS
+            ? joined
+            : `${joined.slice(0, MAX_DELIVERY_CHARACTERS)}\n\n[Additional Workspace context deltas were truncated; reopen with context=\"auto\" to refresh metadata.]`;
+        return {
+            text,
+            coveredComponents: [...coveredComponents],
+            revision: state.revision,
+        };
+    }
+    isCurrentForScope(workspaceId, conversationScopeId) {
+        if (!conversationScopeId)
+            return false;
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return false;
+        return state.deliveredRevisionByScope.get(conversationScopeId) === state.revision;
+    }
+    forgetWorkspace(workspaceId) {
+        const state = this.states.get(workspaceId);
+        if (!state)
+            return;
+        for (const stop of state.tracked.values())
+            stop();
+        this.states.delete(workspaceId);
+    }
+    pruneWorkspaces(activeWorkspaceIds) {
+        const active = new Set(activeWorkspaceIds);
+        for (const workspaceId of this.states.keys()) {
+            if (!active.has(workspaceId))
+                this.forgetWorkspace(workspaceId);
+        }
+    }
+    get watchedPhysicalFiles() {
+        return sharedWatches.size;
+    }
+    addDesired(desired, path, subscription) {
+        const key = canonicalWatchKey(path);
+        const current = desired.get(key);
+        if (current?.subscription.kind === "instruction-loaded")
+            return;
+        desired.set(key, { path, subscription });
+    }
+    recordChange(workspaceId, key, oldContent, newContent) {
+        if (oldContent === newContent)
+            return;
+        const state = this.states.get(workspaceId);
+        const subscription = state?.subscriptions.get(key);
+        if (!state || !subscription)
+            return;
+        state.revision += 1;
+        state.changes.push({
+            ...subscription,
+            revision: state.revision,
+            watchKey: key,
+            oldContent,
+            newContent,
+        });
+        if (state.changes.length > MAX_HISTORY) {
+            state.changes.splice(0, state.changes.length - MAX_HISTORY);
+        }
+    }
+    pruneDeliveredHistory(state) {
+        if (state.changes.length === 0 || state.deliveredRevisionByScope.size === 0)
+            return;
+        const floor = Math.min(...state.deliveredRevisionByScope.values());
+        while (state.changes[0] && state.changes[0].revision <= floor)
+            state.changes.shift();
+    }
+}
+function subscribeSharedWatch(inputPath, subscriberId, subscriber) {
+    const key = canonicalWatchKey(inputPath);
+    let entry = sharedWatches.get(key);
+    if (!entry) {
+        const watchPath = resolve(inputPath);
+        const listener = () => synchronizeSharedWatch(key);
+        entry = {
+            key,
+            watchPath,
+            content: readOptionalFile(watchPath),
+            subscribers: new Map(),
+            listener,
+        };
+        sharedWatches.set(key, entry);
+        watchFile(watchPath, { interval: WATCH_INTERVAL_MS, persistent: false }, listener);
+    }
+    else {
+        synchronizeSharedWatch(key);
+    }
+    entry.subscribers.set(subscriberId, subscriber);
+    return () => {
+        const current = sharedWatches.get(key);
+        if (!current)
+            return;
+        current.subscribers.delete(subscriberId);
+        if (current.subscribers.size > 0)
+            return;
+        unwatchFile(current.watchPath, current.listener);
+        sharedWatches.delete(key);
+    };
+}
+function synchronizeSharedWatch(key) {
+    const entry = sharedWatches.get(key);
+    if (!entry)
+        return;
+    const next = readOptionalFile(entry.watchPath);
+    if (next === entry.content)
+        return;
+    const previous = entry.content;
+    entry.content = next;
+    for (const subscriber of entry.subscribers.values())
+        subscriber(previous, next);
+}
+function canonicalWatchKey(path) {
+    const absolute = resolve(path);
+    try {
+        return realpathSync(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function readOptionalFile(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && (error.code === "ENOENT" || error.code === "ENOTDIR")) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+function displayWorkspacePath(path, workspaceRoot) {
+    const relationship = relative(workspaceRoot, path);
+    if (!relationship || relationship === ".." || relationship.startsWith(`..${sep}`))
+        return resolve(path);
+    return relationship.split(sep).join("/");
+}
+function coalesceChanges(changes) {
+    const grouped = new Map();
+    for (const change of changes) {
+        const existing = grouped.get(change.watchKey);
+        if (!existing) {
+            grouped.set(change.watchKey, { ...change });
+            continue;
+        }
+        grouped.set(change.watchKey, {
+            ...change,
+            oldContent: existing.oldContent,
+        });
+    }
+    return [...grouped.values()].sort((left, right) => left.revision - right.revision);
+}
+function formatResourceChange(change) {
+    if (change.oldContent === change.newContent)
+        return undefined;
+    if (change.kind === "instruction-available") {
+        return {
+            text: `Nested Workspace instruction changed: ${change.displayPath}. Its body remains lazy; read it before working under that directory.`,
+            coveredComponents: [],
+        };
+    }
+    if (change.kind === "instruction-loaded") {
+        return {
+            text: [
+                `Workspace instruction delta: ${change.displayPath}`,
+                boundedPatch(change.displayPath, change.oldContent, change.newContent),
+            ].join("\n"),
+            coveredComponents: ["agentsFiles"],
+        };
+    }
+    if (change.exposeSkillBody) {
+        return {
+            text: [
+                `Active Skill delta: ${change.displayPath}`,
+                boundedPatch(change.displayPath, change.oldContent, change.newContent),
+            ].join("\n"),
+            coveredComponents: skillMetadataChanged(change) ? ["skills"] : [],
+        };
+    }
+    const metadata = formatSkillMetadataDelta(change);
+    return {
+        text: metadata ?? `Skill content changed: ${change.displayPath}. The Skill body was not injected because it was not active when it changed; reload it before next use.`,
+        coveredComponents: metadata ? ["skills"] : [],
+    };
+}
+function skillMetadataChanged(change) {
+    try {
+        const oldSummary = change.oldContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.oldContent, change.watchKey);
+        const newSummary = change.newContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.newContent, change.watchKey);
+        return JSON.stringify(oldSummary) !== JSON.stringify(newSummary);
+    }
+    catch {
+        return true;
+    }
+}
+function formatSkillMetadataDelta(change) {
+    try {
+        const oldSummary = change.oldContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.oldContent, change.watchKey);
+        const newSummary = change.newContent === undefined
+            ? undefined
+            : skillSummaryFromContent(change.newContent, change.watchKey);
+        if (JSON.stringify(oldSummary) === JSON.stringify(newSummary))
+            return undefined;
+        if (!oldSummary) {
+            return `Skill metadata added: ${change.displayPath}\n+ name: ${newSummary?.name ?? change.skillName ?? "unknown"}\n+ description: ${newSummary?.description ?? ""}\n+ disable-model-invocation: ${newSummary?.disableModelInvocation === true}`;
+        }
+        if (!newSummary)
+            return `Skill removed: ${change.displayPath}`;
+        const lines = [`Skill metadata delta: ${change.displayPath}`];
+        for (const field of ["name", "description", "disableModelInvocation"]) {
+            if (oldSummary[field] === newSummary[field])
+                continue;
+            const label = field === "disableModelInvocation" ? "disable-model-invocation" : field;
+            lines.push(`- ${label}: ${String(oldSummary[field])}`);
+            lines.push(`+ ${label}: ${String(newSummary[field])}`);
+        }
+        return lines.join("\n");
+    }
+    catch {
+        return `Skill metadata became unreadable or changed format: ${change.displayPath}. Reload it before next use.`;
+    }
+}
+function boundedPatch(path, oldContent, newContent) {
+    const patch = createTwoFilesPatch(path, path, oldContent ?? "", newContent ?? "", oldContent === undefined ? "missing" : "before", newContent === undefined ? "missing" : "after", { context: 1 });
+    const lines = patch.split("\n");
+    const hunk = lines.slice(Math.max(0, lines.findIndex((line) => line.startsWith("@@"))));
+    const compact = hunk.join("\n").trimEnd();
+    if (compact.length <= MAX_PATCH_CHARACTERS)
+        return compact;
+    return `${compact.slice(0, MAX_PATCH_CHARACTERS)}\n[delta truncated]`;
+}