unity-open-mcp 0.9.0 → 1.1.0

package/dist/tool-hint.js

@@ -0,0 +1,98 @@
+// Centralized "how to name a tool inside an agent-facing hint" helper.
+//
+// specs/feedback.md 2026-08-14 (hint regression) — a runtime hint that names a
+// tool the caller cannot see is worse than no hint at all: the agent follows
+// it, the tool is not in its surface (`ToolSearch` answers "no matching
+// deferred tools found"), and it falls back to hand-rolling the behavior the
+// tool exists to replace. This had already been fixed once by appending the
+// `manage_tools` activation call at three hand-maintained call sites; the
+// strings drifted apart again on the next release.
+//
+// The structural fix is this module: ONE helper that looks the tool's group up
+// from the registry (`capabilities/tool-groups.ts`) and appends the activation
+// call automatically when — and only when — that group is not enabled by
+// default. No call site can forget it, and a future group move (or a group
+// flipping to `defaultEnabled`) fixes every hint at once.
+//
+// `tool-hint.test.ts` pins the invariant at the string level: every emitted
+// hint / tool description that names a non-default-group tool must also carry
+// the `manage_tools` activation call.
+import { DEFAULT_ENABLED_GROUPS, groupFor, } from "./capabilities/tool-groups.js";
+// ---------------------------------------------------------------------------
+// feedback 2026-08-17 — a hint must not name a tool that is not registered.
+// The reported case: the remediation hint pointed at
+// unity_open_mcp_recompile_scripts (in the typed-editor group), the agent
+// activated the group, and the tool was still absent from its surface — the
+// hint sent it down a dead end. `tools/index.ts` registers the full
+// ALL_TOOLS name list here once at module init (a push, so this module never
+// imports the tool graph and no import cycle exists). Until that
+// registration has run — i.e. during module-eval-time calls from tool
+// definition files — the registry is empty and the guard is a no-op; the
+// static companion test in tool-hint.test.ts pins the invariant at source
+// level instead.
+// ---------------------------------------------------------------------------
+/** Names of every registered MCP tool. Empty until tools/index.ts registers. */
+const registeredTools = new Set();
+/** Warn-once bookkeeping so an unregistered name logs a single line. */
+const warnedUnregistered = new Set();
+/**
+ * Register the reachable tool-name set. Called once from `tools/index.ts`
+ * after `ALL_TOOLS` is built. Not part of the public agent surface.
+ */
+export function registerHintableToolNames(names) {
+    for (const name of names)
+        registeredTools.add(name);
+}
+/**
+ * Build the `manage_tools` activation call for a group id. Mirrors the exact
+ * invocation an agent must issue, so a hint can be followed verbatim.
+ */
+export function activateInstruction(groupId) {
+    return `activate with manage_tools(action:"activate", group:"${groupId}")`;
+}
+/**
+ * True when `toolName` is reachable in a fresh session without a
+ * `manage_tools` activation — i.e. it has no group assignment (always-visible
+ * meta-tool) or its group is default-enabled.
+ */
+export function isDefaultVisible(toolName) {
+    const group = groupFor(toolName);
+    if (group === null)
+        return true;
+    return DEFAULT_ENABLED_GROUPS.has(group);
+}
+/**
+ * Render a tool reference for use inside an agent-facing hint or tool
+ * description.
+ *
+ * Default-visible tools render as the bare name. A tool in a group that is NOT
+ * enabled by default renders as the name plus the group and the concrete
+ * activation call, e.g.
+ *
+ *   unity_open_mcp_recompile_scripts (in the typed-editor group, not enabled
+ *   by default — activate with manage_tools(action:"activate",
+ *   group:"typed-editor"))
+ *
+ * Unknown tool names render bare: this helper never invents an activation call
+ * for a tool it cannot resolve. A name that is known to the group catalog but
+ * NOT registered (verified against the names registered by tools/index.ts,
+ * once available) also renders bare — a hint must not prescribe an activation
+ * call for a tool the server cannot actually serve — and logs one maintainer
+ * warning so the drift is visible.
+ */
+export function toolHintReference(toolName) {
+    const group = groupFor(toolName);
+    const unregistered = registeredTools.size > 0 && !registeredTools.has(toolName);
+    if (unregistered && !warnedUnregistered.has(toolName)) {
+        warnedUnregistered.add(toolName);
+        console.error(`[unity-open-mcp] tool-hint drift: '${toolName}' is assigned to group ` +
+            `${group ?? "(none)"} but is not a registered tool — rendering the hint ` +
+            `without its activation call. Check tools/index.ts.`);
+    }
+    if (group === null || DEFAULT_ENABLED_GROUPS.has(group) || unregistered) {
+        return toolName;
+    }
+    return (`${toolName} (in the ${group} group, not enabled by default — ` +
+        `${activateInstruction(group)})`);
+}
+//# sourceMappingURL=tool-hint.js.map

package/dist/tool-hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-hint.js","sourceRoot":"","sources":["../src/tool-hint.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,+EAA+E;AAC/E,6EAA6E;AAC7E,wEAAwE;AACxE,6EAA6E;AAC7E,4EAA4E;AAC5E,0EAA0E;AAC1E,mDAAmD;AACnD,EAAE;AACF,+EAA+E;AAC/E,+EAA+E;AAC/E,yEAAyE;AACzE,2EAA2E;AAC3E,0DAA0D;AAC1D,EAAE;AACF,4EAA4E;AAC5E,8EAA8E;AAC9E,sCAAsC;AAEtC,OAAO,EACL,sBAAsB,EACtB,QAAQ,GACT,MAAM,+BAA+B,CAAC;AAEvC,8EAA8E;AAC9E,4EAA4E;AAC5E,qDAAqD;AACrD,0EAA0E;AAC1E,4EAA4E;AAC5E,oEAAoE;AACpE,6EAA6E;AAC7E,iEAAiE;AACjE,sEAAsE;AACtE,yEAAyE;AACzE,0EAA0E;AAC1E,iBAAiB;AACjB,8EAA8E;AAE9E,gFAAgF;AAChF,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU,CAAC;AAE1C,wEAAwE;AACxE,MAAM,kBAAkB,GAAG,IAAI,GAAG,EAAU,CAAC;AAE7C;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,KAAwB;IAChE,KAAK,MAAM,IAAI,IAAI,KAAK;QAAE,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,OAAO,wDAAwD,OAAO,IAAI,CAAC;AAC7E,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAAgB;IAC/C,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAChC,OAAO,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACjC,MAAM,YAAY,GAChB,eAAe,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAC7D,IAAI,YAAY,IAAI,CAAC,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,kBAAkB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACjC,OAAO,CAAC,KAAK,CACX,sCAAsC,QAAQ,yBAAyB;YACrE,GAAG,KAAK,IAAI,QAAQ,qDAAqD;YACzE,oDAAoD,CACvD,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,IAAI,sBAAsB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,YAAY,EAAE,CAAC;QACxE,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,CACL,GAAG,QAAQ,YAAY,KAAK,mCAAmC;QAC/D,GAAG,mBAAmB,CAAC,KAAK,CAAC,GAAG,CACjC,CAAC;AACJ,CAAC"}

package/dist/tool-router.d.ts

@@ -26,8 +26,24 @@ export interface HubControlBackend {
 import type { ToolSessionState } from "./tool-session-state.js";
 export type SourceTag = "live" | "offline" | "local";
 export interface RouteMeta {
-    route: "live" | "batch";
+    /**
+     * Where the response came from: "live" (bridge), "batch" (headless spawn),
+     * "offline" (disk parser / offline-first attempt, no bridge contact), or
+     * "local" (caller-side validation / locally-computed result). The
+     * compressible branch derives this from the payload's `_source` tag —
+     * including error bodies — so the two tags never disagree about the origin.
+     */
+    route: "live" | "batch" | "offline" | "local";
     fallbackReason?: string;
+    /**
+     * feedback-fable-04-08 §7 — present only when a `live_unavailable` batch
+     * fallback landed on `editor_instance_locked` AND a live PID holds the
+     * project. The actionable truth for the agent is "the editor is busy
+     * (TestRunner run / long import); retry later", not a lock conflict, so
+     * `fallbackReason` is rewritten to `editor_busy` and the live PID is
+     * surfaced here so the agent can correlate.
+     */
+    editorPid?: number;
 }
 export declare class ToolRouter implements Router {
     private live;
@@ -37,6 +53,7 @@ export declare class ToolRouter implements Router {
     private sessionState;
     private onToolListChanged?;
     private hubBackend;
+    private globalLogPathOverride?;
     private readonly modelCache;
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -50,7 +67,7 @@ export declare class ToolRouter implements Router {
      */
     private routeHandlers?;
     private getRouteHandlers;
-    constructor(live: LiveClient, batch: BatchSpawn, projectPath: string, eventStream: BridgeEventStream, sessionState: ToolSessionState, onToolListChanged?: (() => void | Promise<void>) | undefined, hubBackend?: HubControlBackend);
+    constructor(live: LiveClient, batch: BatchSpawn, projectPath: string, eventStream: BridgeEventStream, sessionState: ToolSessionState, onToolListChanged?: (() => void | Promise<void>) | undefined, hubBackend?: HubControlBackend, globalLogPathOverride?: string | undefined);
     route(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
     /**
      * M23 Plan 3 — route with a per-call live-client override. Used when a
@@ -63,8 +80,26 @@ export declare class ToolRouter implements Router {
     routeOverride(toolName: string, args: Record<string, unknown>, overrideLive: LiveClient): Promise<CallToolResult>;
     private routeCore;
     private batchPingResult;
+    /**
+     * feedback-fable-04-08 §7 — when a `live_unavailable` batch fallback lands
+     * on `editor_instance_locked`, the message describes the BATCH SPAWNER's
+     * problem ("a live editor holds the project lock, so no headless spawn"),
+     * but the agent's actionable truth is "the editor is busy (TestRunner run /
+     * long import); retry later", not a lock conflict. Detect this case by
+     * inspecting the batch result for `error.code === "editor_instance_locked"`
+     * AND confirming a live PID still holds the project (a stale lock with no
+     * live PID is a genuine lock conflict — leave it as `live_unavailable`).
+     *
+     * Returns the rewritten meta (and the result unchanged — the lock error body
+     * is real and must stay intact) so the caller stamps it via injectRouteMeta.
+     * The live PID is surfaced as `editorPid` for agent correlation. Falls
+     * through unchanged when the code differs, no live PID exists, or the body
+     * is unparseable.
+     */
+    private rewriteEditorBusy;
     private routeReadCompileErrors;
     private resolveLiveEditorPid;
+    private resolveLiveUnityVersion;
     private routeListAssets;
     private routePullEvents;
     private routeCapabilities;
@@ -119,6 +154,16 @@ export declare class ToolRouter implements Router {
     private routeRestartEditor;
     /** Build the confirmed-kill response from a {@link KillResult}. */
     private restartEditorKillResponse;
+    /**
+     * Flatten a unity_senses_read_console result body into a single string the
+     * health-issue extractor can scan for the fd-exhaustion signature. The
+     * console result is a JSON object with an `entries[]` array of
+     * `{ message, stack, ... }`; we join message + stack so the Bee driver's
+     * `Could not register to wait for file descriptor N` frame (which lives in
+     * the stack trace) is reachable by {@link extractProjectHealthIssues}.
+     * Returns "" when the body has no entries.
+     */
+    private serializeConsoleEntries;
     /**
      * T31.4 — sample the live Unity process's file-descriptor usage and report
      * headroom against Mono's ~1024 fd ceiling (the real trip point for the Bee