@savvy-web/mcp 3.3.0 → 3.4.1

package/errors.js

@@ -1,4 +1,4 @@
-import { ToolFailure } from "@effected/mcp";
+import { ToolFailure, ToolRefusal } from "@effected/mcp";
 import { Schema } from "effect";
 
 //#region src/errors.ts
@@ -14,18 +14,6 @@ var WorkspaceNotFound = class extends Schema.TaggedError()("WorkspaceNotFound",
 	cwd: Schema.String
 }) {};
 /**
-* A tool argument was structurally acceptable but semantically invalid — a
-* `repos_manage` action missing the field it needs, a `biome_check` path
-* outside the workspace, a `changeset_validate` directory that does not
-* exist. `message` is composed through `ToolFailure.message`.
-*
-* @public
-*/
-var InvalidArgument = class extends Schema.TaggedError()("InvalidArgument", {
-	...ToolFailure.fields,
-	argument: Schema.String
-}) {};
-/**
 * A silk-effects engine program failed with one of its own typed errors
 * (`TurboError`, `GitError`, `ReposConfigError`, …). `source` carries that
 * error's `_tag`; `message` is its own rendering plus the remediation,
@@ -38,13 +26,6 @@ var EngineError = class extends Schema.TaggedError()("EngineError", {
 	source: Schema.String
 }) {};
 /**
-* No Biome binary could be located. `message` is composed through
-* `ToolFailure.message`.
-*
-* @public
-*/
-var BiomeUnavailable = class extends Schema.TaggedError()("BiomeUnavailable", { ...ToolFailure.fields }) {};
-/**
 * Biome itself failed (exit status above 1, a spawn error, or a timeout) —
 * distinct from "lint issues found", which is a successful result. `message`
 * is composed through `ToolFailure.message`.
@@ -58,10 +39,9 @@ var BiomeFailed = class extends Schema.TaggedError()("BiomeFailed", {
 /** The one failure schema every savvy-mcp tool declares. @public */
 const McpToolError = Schema.Union([
 	WorkspaceNotFound,
-	InvalidArgument,
 	EngineError,
-	BiomeUnavailable,
-	BiomeFailed
+	BiomeFailed,
+	ToolRefusal
 ]);
 /** The remediation every `WorkspaceNotFound` carries. */
 const WORKSPACE_REMEDIATION = {
@@ -82,30 +62,28 @@ const workspaceNotFound = (cwd) => new WorkspaceNotFound({
 	remediation: WORKSPACE_REMEDIATION
 });
 /**
-* Build an {@link InvalidArgument}: `raw` is the human message (already
-* truncated by the caller where it echoes an argument).
-*
-* @public
-*/
-const invalidArgument = (argument, raw, remediation) => new InvalidArgument({
-	argument,
-	message: ToolFailure.message(raw, remediation),
-	remediation
-});
-/**
 * Build an {@link EngineError} from a silk-effects typed error. Every engine
 * error in this server renders itself through a `message` getter, so that
 * rendering is the raw message — passed through `ToolFailure.truncate` at
 * `ToolFailure.ENGINE_ECHO_LIMIT`, since the kit embeds caller values in it;
 * `source` keeps the tag for anything that inspects the typed error directly.
+* An `Error` in the engine error's own `cause` is appended to that rendering
+* unless the rendering already contains it: a kit error that renders only a
+* one-line summary keeps the actionable detail in `cause`, while one that
+* already folds its cause in (`CatalogAssemblyError` since `@effected/npm`
+* 0.17.0) would otherwise print the detail twice.
 *
 * @public
 */
-const engineError = (cause, remediation) => new EngineError({
-	source: cause._tag,
-	message: ToolFailure.message(ToolFailure.truncate(cause.message, ToolFailure.ENGINE_ECHO_LIMIT), remediation),
-	remediation
-});
+const engineError = (cause, remediation) => {
+	const detail = cause.cause instanceof Error ? cause.cause.message : "";
+	const rendered = detail && !cause.message.includes(detail) ? `${cause.message}: ${detail}` : cause.message;
+	return new EngineError({
+		source: cause._tag,
+		message: ToolFailure.message(ToolFailure.truncate(rendered, ToolFailure.ENGINE_ECHO_LIMIT), remediation),
+		remediation
+	});
+};
 /**
 * The shared mapping every handler applies to its engine error channel: the
 * kit's `WorkspaceRootNotFoundError` becomes {@link WorkspaceNotFound} for the
@@ -121,4 +99,4 @@ const engineError = (cause, remediation) => new EngineError({
 const mapEngineError = (requestedCwd, remediation) => (cause) => cause._tag === "WorkspaceRootNotFoundError" ? workspaceNotFound(requestedCwd) : engineError(cause, remediation);
 
 //#endregion
-export { BiomeFailed, BiomeUnavailable, EngineError, InvalidArgument, McpToolError, WorkspaceNotFound, engineError, invalidArgument, mapEngineError, workspaceNotFound };
+export { BiomeFailed, EngineError, McpToolError, WorkspaceNotFound, engineError, mapEngineError, workspaceNotFound };

package/index.d.ts

@@ -1,4 +1,5 @@
 import { Distribution } from "@effected/engine";
+import { ToolRefusal } from "@effected/mcp";
 import { FileSystem, Layer, Path, Schema, Stdio } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets, Repos, SilkWorkspaceAnalyzer, Turbo } from "@savvy-web/silk-effects";
@@ -22,24 +23,6 @@ declare const WorkspaceNotFound_base: Schema.Class<WorkspaceNotFound, Schema.Tag
  * @public
  */
 export declare class WorkspaceNotFound extends WorkspaceNotFound_base {}
-declare const InvalidArgument_base: Schema.Class<InvalidArgument, Schema.TaggedStruct<"InvalidArgument", {
-  readonly message: Schema.String;
-  readonly remediation: Schema.Struct<{
-    readonly hint: Schema.String;
-    readonly suggestedTool: Schema.optionalKey<Schema.String>;
-    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
-  }>;
-  readonly argument: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-/**
- * A tool argument was structurally acceptable but semantically invalid — a
- * `repos_manage` action missing the field it needs, a `biome_check` path
- * outside the workspace, a `changeset_validate` directory that does not
- * exist. `message` is composed through `ToolFailure.message`.
- *
- * @public
- */
-export declare class InvalidArgument extends InvalidArgument_base {}
 declare const EngineError_base: Schema.Class<EngineError, Schema.TaggedStruct<"EngineError", {
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
@@ -58,21 +41,6 @@ declare const EngineError_base: Schema.Class<EngineError, Schema.TaggedStruct<"E
  * @public
  */
 export declare class EngineError extends EngineError_base {}
-declare const BiomeUnavailable_base: Schema.Class<BiomeUnavailable, Schema.TaggedStruct<"BiomeUnavailable", {
-  readonly message: Schema.String;
-  readonly remediation: Schema.Struct<{
-    readonly hint: Schema.String;
-    readonly suggestedTool: Schema.optionalKey<Schema.String>;
-    readonly suggestedArgs: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
-  }>;
-}>, import("effect/Cause").YieldableError>;
-/**
- * No Biome binary could be located. `message` is composed through
- * `ToolFailure.message`.
- *
- * @public
- */
-export declare class BiomeUnavailable extends BiomeUnavailable_base {}
 declare const BiomeFailed_base: Schema.Class<BiomeFailed, Schema.TaggedStruct<"BiomeFailed", {
   readonly message: Schema.String;
   readonly remediation: Schema.Struct<{
@@ -91,7 +59,7 @@ declare const BiomeFailed_base: Schema.Class<BiomeFailed, Schema.TaggedStruct<"B
  */
 export declare class BiomeFailed extends BiomeFailed_base {}
 /** The one failure schema every savvy-mcp tool declares. @public */
-export declare const McpToolError: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+export declare const McpToolError: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof ToolRefusal]>;
 /** @public */
 export type McpToolError = typeof McpToolError.Type;
 //#endregion
@@ -207,7 +175,7 @@ declare const biomeCheckTool: Tool.Tool<"biome_check", {
     readonly wrote: Schema.Boolean;
     readonly guidance: Schema.String;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof ToolRefusal]>;
   readonly failureMode: "error";
 }, never>;
 //#endregion
@@ -239,7 +207,7 @@ declare const changesetDepsDetectTool: Tool.Tool<"changeset_deps_detect", {
       readonly packages: Schema.$Array<Schema.String>;
     }>>;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, Changesets.DepsRegen | WorkspaceRoot>;
 //#endregion
@@ -265,7 +233,7 @@ declare const changesetDepsRegenTool: Tool.Tool<"changeset_deps_regen", {
     }>>;
     readonly dryRun: Schema.Boolean;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, Changesets.DepsRegen | WorkspaceRoot>;
 //#endregion
@@ -341,7 +309,7 @@ declare const changesetInspectTool: Tool.Tool<"changeset_inspect", {
       }>, Schema.Null]>;
     }>>;
   }>]>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, Changesets.BranchAnalyzer | Changesets.ConfigInspector | WorkspaceRoot>;
 //#endregion
@@ -370,7 +338,7 @@ declare const changesetPreviewTool: Tool.Tool<"changeset_preview", {
       }>>;
     }>>;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, Changesets.ReleasePlanner | WorkspaceRoot>;
 //#endregion
@@ -393,7 +361,7 @@ declare const changesetValidateTool: Tool.Tool<"changeset_validate", {
       readonly message: Schema.String;
     }>>;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof ToolRefusal]>;
   readonly failureMode: "error";
 }, WorkspaceRoot>;
 //#endregion
@@ -458,128 +426,154 @@ declare const reposInspectTool: Tool.Tool<"repos_inspect", {
     }>>;
     readonly parseError: Schema.optionalKey<Schema.String>;
   }>]>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, FileSystem.FileSystem | Path.Path | Repos.ReposConfigStore | Repos.ReposDrift | Repos.ReposManager | WorkspaceRoot>;
 //#endregion
 //#region src/tools/repos-manage.d.ts
-/** The `repos_manage` tool value. Mutating: not read-only, not idempotent. */
-declare const reposManageTool: Tool.Tool<"repos_manage", {
-  readonly parameters: Schema.Struct<{
-    readonly action: Schema.Literals<readonly ["sync", "pin", "add", "note", "remove", "rename", "restore", "deregister"]>;
-    readonly name: Schema.optionalKey<Schema.String>;
-    readonly newName: Schema.optionalKey<Schema.String>;
-    readonly ref: Schema.optionalKey<Schema.String>;
-    readonly url: Schema.optionalKey<Schema.String>;
-    readonly purpose: Schema.optionalKey<Schema.String>;
-    readonly sparse: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    readonly orientation: Schema.optionalKey<Schema.Struct<{
-      readonly layout: Schema.optional<Schema.String>;
-      readonly keyPaths: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
-      readonly startHere: Schema.optional<Schema.String>;
-    }>>;
-    readonly op: Schema.optionalKey<Schema.Literals<readonly ["add", "remove", "promote"]>>;
-    readonly note: Schema.optionalKey<Schema.String>;
-    readonly id: Schema.optionalKey<Schema.String>;
-    readonly into: Schema.optionalKey<Schema.Literals<readonly ["layout", "startHere"]>>;
-    readonly names: Schema.optionalKey<Schema.$Array<Schema.String>>;
-    readonly section: Schema.optionalKey<Schema.String>;
-    readonly cwd: Schema.optionalKey<Schema.String>;
+/**
+ * The `repos_manage` tool value: a `McpToolkit.unionTool`, so the served input
+ * schema is the request union's strict `oneOf` keyed by `action`, and a bad
+ * call is rejected as invalid parameters before the handler runs. Mutating:
+ * not read-only, not idempotent.
+ */
+declare const reposManageTool: import("@effected/mcp").UnionTool<"repos_manage", Schema.Union<readonly [Schema.Struct<{
+  readonly action: Schema.Literal<"sync">;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"pin">;
+  readonly name: Schema.String;
+  readonly ref: Schema.String;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"add">;
+  readonly url: Schema.String;
+  readonly ref: Schema.String;
+  readonly purpose: Schema.String;
+  readonly name: Schema.optionalKey<Schema.String>;
+  readonly sparse: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly orientation: Schema.optionalKey<Schema.Struct<{
+    readonly layout: Schema.optional<Schema.String>;
+    readonly keyPaths: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+    readonly startHere: Schema.optional<Schema.String>;
+  }>>;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"note">;
+  readonly name: Schema.String;
+  readonly op: Schema.Literals<readonly ["add", "remove", "promote"]>;
+  readonly note: Schema.optionalKey<Schema.String>;
+  readonly id: Schema.optionalKey<Schema.String>;
+  readonly into: Schema.optionalKey<Schema.Literals<readonly ["layout", "startHere"]>>;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"remove">;
+  readonly name: Schema.String;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"rename">;
+  readonly name: Schema.String;
+  readonly newName: Schema.String;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"restore">;
+  readonly names: Schema.optionalKey<Schema.$Array<Schema.String>>;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"deregister">;
+  readonly section: Schema.String;
+  readonly cwd: Schema.optionalKey<Schema.String>;
+}>]>, Schema.Union<readonly [Schema.Struct<{
+  readonly action: Schema.Literal<"sync">;
+  readonly result: Schema.Struct<{
+    readonly initialized: Schema.$Array<Schema.String>;
+    readonly sparseApplied: Schema.$Array<Schema.String>;
+    readonly upToDate: Schema.$Array<Schema.String>;
+    readonly clearedLocks: Schema.$Array<Schema.String>;
+    readonly urlSynced: Schema.$Array<Schema.String>;
+    readonly registered: Schema.$Array<Schema.String>;
+    readonly boundaryMarked: Schema.$Array<Schema.String>;
   }>;
-  readonly success: Schema.Union<readonly [Schema.Struct<{
-    readonly action: Schema.Literal<"sync">;
-    readonly result: Schema.Struct<{
-      readonly initialized: Schema.$Array<Schema.String>;
-      readonly sparseApplied: Schema.$Array<Schema.String>;
-      readonly upToDate: Schema.$Array<Schema.String>;
-      readonly clearedLocks: Schema.$Array<Schema.String>;
-      readonly urlSynced: Schema.$Array<Schema.String>;
-      readonly registered: Schema.$Array<Schema.String>;
-      readonly boundaryMarked: Schema.$Array<Schema.String>;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"pin">;
-    readonly result: Schema.Struct<{
-      readonly name: Schema.String;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"pin">;
+  readonly result: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly ref: Schema.String;
+    readonly oldCommit: Schema.NullOr<Schema.String>;
+    readonly newCommit: Schema.String;
+    readonly commitMessage: Schema.String;
+    readonly staleNoteIds: Schema.$Array<Schema.String>;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"add">;
+  readonly result: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly ref: Schema.String;
+    readonly path: Schema.String;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"note">;
+  readonly result: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly op: Schema.Literals<readonly ["add", "remove", "promote"]>;
+    readonly id: Schema.String;
+    readonly noteCount: Schema.Number;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"remove">;
+  readonly result: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly path: Schema.String;
+    readonly commitMessage: Schema.String;
+    readonly removedNotes: Schema.$Array<Schema.Struct<{
+      readonly id: Schema.String;
+      readonly date: Schema.String;
       readonly ref: Schema.String;
-      readonly oldCommit: Schema.NullOr<Schema.String>;
-      readonly newCommit: Schema.String;
-      readonly commitMessage: Schema.String;
-      readonly staleNoteIds: Schema.$Array<Schema.String>;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"add">;
-    readonly result: Schema.Struct<{
-      readonly name: Schema.String;
+      readonly note: Schema.String;
+    }>>;
+    readonly removedEntry: Schema.Struct<{
+      readonly url: Schema.String;
       readonly ref: Schema.String;
-      readonly path: Schema.String;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"note">;
-    readonly result: Schema.Struct<{
-      readonly name: Schema.String;
-      readonly op: Schema.Literals<readonly ["add", "remove", "promote"]>;
-      readonly id: Schema.String;
-      readonly noteCount: Schema.Number;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"remove">;
-    readonly result: Schema.Struct<{
-      readonly name: Schema.String;
-      readonly path: Schema.String;
-      readonly commitMessage: Schema.String;
-      readonly removedNotes: Schema.$Array<Schema.Struct<{
+      readonly purpose: Schema.String;
+      readonly sparse: Schema.optional<Schema.$Array<Schema.String>>;
+      readonly orientation: Schema.optional<Schema.Struct<{
+        readonly layout: Schema.optional<Schema.String>;
+        readonly keyPaths: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+        readonly startHere: Schema.optional<Schema.String>;
+      }>>;
+      readonly notes: Schema.optional<Schema.$Array<Schema.Struct<{
         readonly id: Schema.String;
         readonly date: Schema.String;
         readonly ref: Schema.String;
         readonly note: Schema.String;
-      }>>;
-      readonly removedEntry: Schema.Struct<{
-        readonly url: Schema.String;
-        readonly ref: Schema.String;
-        readonly purpose: Schema.String;
-        readonly sparse: Schema.optional<Schema.$Array<Schema.String>>;
-        readonly orientation: Schema.optional<Schema.Struct<{
-          readonly layout: Schema.optional<Schema.String>;
-          readonly keyPaths: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
-          readonly startHere: Schema.optional<Schema.String>;
-        }>>;
-        readonly notes: Schema.optional<Schema.$Array<Schema.Struct<{
-          readonly id: Schema.String;
-          readonly date: Schema.String;
-          readonly ref: Schema.String;
-          readonly note: Schema.String;
-        }>>>;
-      }>;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"rename">;
-    readonly result: Schema.Struct<{
-      readonly oldName: Schema.String;
-      readonly newName: Schema.String;
-      readonly path: Schema.String;
-      readonly commitMessage: Schema.String;
-    }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"restore">;
-    readonly result: Schema.Struct<{
-      readonly restored: Schema.$Array<Schema.Struct<{
-        readonly name: Schema.String;
-        readonly commit: Schema.String;
-      }>>;
-      readonly skippedClean: Schema.$Array<Schema.String>;
-      readonly stillDirty: Schema.$Array<Schema.String>;
+      }>>>;
     }>;
-  }>, Schema.Struct<{
-    readonly action: Schema.Literal<"deregister">;
-    readonly result: Schema.Struct<{
-      readonly section: Schema.String;
-      readonly removedKeys: Schema.$Array<Schema.String>;
-    }>;
-  }>]>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
-  readonly failureMode: "error";
-}, Repos.ReposManager | WorkspaceRoot>;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"rename">;
+  readonly result: Schema.Struct<{
+    readonly oldName: Schema.String;
+    readonly newName: Schema.String;
+    readonly path: Schema.String;
+    readonly commitMessage: Schema.String;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"restore">;
+  readonly result: Schema.Struct<{
+    readonly restored: Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly commit: Schema.String;
+    }>>;
+    readonly skippedClean: Schema.$Array<Schema.String>;
+    readonly stillDirty: Schema.$Array<Schema.String>;
+  }>;
+}>, Schema.Struct<{
+  readonly action: Schema.Literal<"deregister">;
+  readonly result: Schema.Struct<{
+    readonly section: Schema.String;
+    readonly removedKeys: Schema.$Array<Schema.String>;
+  }>;
+}>]>, Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof ToolRefusal]>, Repos.ReposManager | WorkspaceRoot>;
 //#endregion
 //#region src/tools/turbo-inspect.d.ts
 /** The `turbo_inspect` tool value. */
@@ -641,7 +635,7 @@ declare const turboInspectTool: Tool.Tool<"turbo_inspect", {
       readonly dependents: Schema.$Array<Schema.String>;
     }>;
   }>]>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, Turbo.TurboInspector | WorkspaceRoot>;
 //#endregion
@@ -678,7 +672,7 @@ declare const workspaceInfoTool: Tool.Tool<"workspace_info", {
       readonly fixed: Schema.$Array<Schema.String>;
     }>>;
   }>;
-  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof InvalidArgument, typeof EngineError, typeof BiomeUnavailable, typeof BiomeFailed]>;
+  readonly failure: Schema.Union<readonly [typeof WorkspaceNotFound, typeof EngineError, typeof BiomeFailed, typeof import("@effected/mcp").ToolRefusal]>;
   readonly failureMode: "error";
 }, SilkWorkspaceAnalyzer | WorkspaceRoot>;
 //#endregion

package/index.js

@@ -1,7 +1,7 @@
-import { BiomeFailed, BiomeUnavailable, EngineError, InvalidArgument, McpToolError, WorkspaceNotFound } from "./errors.js";
+import { BiomeFailed, EngineError, McpToolError, WorkspaceNotFound } from "./errors.js";
 import { makeSilkRuntimeLayer } from "./runtime.js";
 import { SilkToolkit, ToolsLayer } from "./toolkit.js";
 import { CURRENT_MCP_VERSION } from "./version.js";
 import { ServerLayer } from "./server.js";
 
-export { BiomeFailed, BiomeUnavailable, CURRENT_MCP_VERSION, EngineError, InvalidArgument, McpToolError, ServerLayer, SilkToolkit, ToolsLayer, WorkspaceNotFound, makeSilkRuntimeLayer };
+export { BiomeFailed, CURRENT_MCP_VERSION, EngineError, McpToolError, ServerLayer, SilkToolkit, ToolsLayer, WorkspaceNotFound, makeSilkRuntimeLayer };

package/main.d.ts

@@ -21,7 +21,8 @@ export interface MainOptions {
  * `SAVVY_MCP_PROJECT_DIR`, then `CLAUDE_PROJECT_DIR`, then the working
  * directory — an empty value or an unsubstituted `${VAR}` placeholder is
  * skipped (`LaunchContext.projectDir`). NO static imports of the server
- * graph — see the module remarks.
+ * graph — see the module remarks. The guard policy is the kit's default:
+ * a stray exception or rejection exits 1, before or after connecting.
  *
  * @public
  */

package/main.js

@@ -1,8 +1,6 @@
+import { McpGuard } from "@effected/mcp/guard";
+
 //#region src/main.ts
-const fatal = (label, error) => {
-	process.stderr.write(`savvy-mcp: ${label}: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
-	process.exit(1);
-};
 /**
 * Run the savvy MCP server over stdio. Owns the process.
 *
@@ -11,26 +9,31 @@ const fatal = (label, error) => {
 * `SAVVY_MCP_PROJECT_DIR`, then `CLAUDE_PROJECT_DIR`, then the working
 * directory — an empty value or an unsubstituted `${VAR}` placeholder is
 * skipped (`LaunchContext.projectDir`). NO static imports of the server
-* graph — see the module remarks.
+* graph — see the module remarks. The guard policy is the kit's default:
+* a stray exception or rejection exits 1, before or after connecting.
 *
 * @public
 */
-const main = async (options = {}) => {
-	process.on("uncaughtException", (e) => fatal("uncaught exception", e));
-	process.on("unhandledRejection", (r) => fatal("unhandled rejection", r));
-	const { NodeRuntime, NodeServices } = await import("@effect/platform-node");
-	const { Layer } = await import("effect");
-	const { LaunchContext } = await import("@effected/engine");
-	const { McpStdio } = await import("@effected/mcp");
-	const { ServerLayer } = await import("./server.js");
-	const cwd = LaunchContext.projectDir({
-		argv: process.argv.slice(2, 3),
-		env: process.env,
-		keys: ["SAVVY_MCP_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
-		cwd: process.cwd()
-	});
-	NodeRuntime.runMain(McpStdio.launch(ServerLayer(cwd, options).pipe(Layer.provide(NodeServices.layer))), { teardown: McpStdio.teardown });
-};
+const main = (options = {}) => McpGuard.run({
+	label: "savvy-mcp",
+	host: process,
+	load: async () => {
+		const NodeRuntime = await import("@effect/platform-node/NodeRuntime");
+		const NodeServices = await import("@effect/platform-node/NodeServices");
+		const { Layer } = await import("effect");
+		const { LaunchContext } = await import("@effected/engine");
+		const { ServerLayer } = await import("./server.js");
+		return {
+			layer: ServerLayer(LaunchContext.projectDir({
+				argv: process.argv.slice(2, 3),
+				env: process.env,
+				keys: ["SAVVY_MCP_PROJECT_DIR", "CLAUDE_PROJECT_DIR"],
+				cwd: process.cwd()
+			}), options).pipe(Layer.provide(NodeServices.layer)),
+			runMain: NodeRuntime.runMain
+		};
+	}
+});
 /* v8 ignore stop */
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "3.3.0",
+	"version": "3.4.1",
 	"private": false,
 	"description": "The savvy MCP server — Silk Suite tooling and library knowledge for coding agents",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/mcp",
@@ -40,10 +40,10 @@
 		"@effected/commands": "^0.9.0",
 		"@effected/engine": "^0.1.0",
 		"@effected/git": "^0.17.0",
-		"@effected/mcp": "^0.1.1",
+		"@effected/mcp": "^0.2.0",
 		"@effected/templates": "^0.8.0",
-		"@effected/workspaces": "^0.26.0",
-		"@savvy-web/silk-effects": "9.1.3",
+		"@effected/workspaces": "^0.28.0",
+		"@savvy-web/silk-effects": "9.2.0",
 		"effect": "4.0.0-rc.117"
 	}
 }

package/toolkit.js

@@ -36,7 +36,7 @@ const ToolsLayer = (cwd) => SilkToolkit.toLayer({
 	changeset_preview: (params) => handleChangesetPreview(cwd, params),
 	changeset_deps_regen: (params) => handleChangesetDepsRegen(cwd, params),
 	repos_inspect: (params) => handleReposInspect(cwd, params),
-	repos_manage: (params) => handleReposManage(cwd, params),
+	repos_manage: handleReposManage(cwd),
 	biome_check: (params) => handleBiomeCheck(cwd, params)
 });
 

package/tools/biome-check.js

@@ -1,5 +1,5 @@
-import { BiomeFailed, BiomeUnavailable, InvalidArgument, McpToolError, invalidArgument } from "../errors.js";
-import { ToolFailure } from "@effected/mcp";
+import { BiomeFailed, McpToolError } from "../errors.js";
+import { ToolFailure, ToolRefusal } from "@effected/mcp";
 import { Effect, Schema } from "effect";
 import { Lint } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -210,30 +210,27 @@ const biomeFailed = (raw, exitCode) => new BiomeFailed({
 *
 * @remarks Resolves the Biome binary via {@link Lint.Biome.findBiome} (global
 * first, then the project's package manager). Throws a typed
-* {@link McpToolError} member — {@link InvalidArgument} for a cwd/path outside
-* the containment tree, {@link BiomeUnavailable} when no binary is found,
-* {@link BiomeFailed} when Biome exits with status > 1 (Biome itself failed,
-* vs. status 1 = lint issues found) — which {@link handleBiomeCheck} lifts
-* into the Effect error channel unchanged.
+* {@link McpToolError} member — a `ToolRefusal` for a cwd/path outside the
+* containment tree or when no binary is found, {@link BiomeFailed} when Biome
+* exits with status > 1 (Biome itself failed, vs. status 1 = lint issues
+* found) — which {@link handleBiomeCheck} lifts into the Effect error channel
+* unchanged.
 */
 const runBiomeCheck = async (args, fallbackCwd) => {
 	const mode = args.mode ?? "check";
 	const root = canonicalize(fallbackCwd);
 	const cwd = canonicalize(args.cwd ?? fallbackCwd);
 	const containmentRoot = resolveContainmentRoot(root, cwd);
-	if (containmentRoot === null) throw invalidArgument("cwd", `cwd escapes the workspace root: ${ToolFailure.truncate(args.cwd ?? fallbackCwd)}.`, CONTAINMENT_REMEDIATION);
+	if (containmentRoot === null) throw ToolRefusal.refuse(`cwd escapes the workspace root: ${ToolFailure.truncate(args.cwd ?? fallbackCwd)}.`, CONTAINMENT_REMEDIATION);
 	const within = (abs) => abs === containmentRoot || abs.startsWith(`${containmentRoot}${sep}`);
 	const paths = (args.paths && args.paths.length > 0 ? args.paths : ["."]).map((p) => {
 		const lexical = resolve(cwd, p);
-		if (!within(canonicalize(lexical))) throw invalidArgument("paths", `path escapes the workspace root: ${ToolFailure.truncate(p)}.`, CONTAINMENT_REMEDIATION);
+		if (!within(canonicalize(lexical))) throw ToolRefusal.refuse(`path escapes the workspace root: ${ToolFailure.truncate(p)}.`, CONTAINMENT_REMEDIATION);
 		return relative(cwd, lexical) || ".";
 	});
 	const doWrite = Boolean(args.write || args.unsafe);
 	const biomeCmd = Lint.Biome.findBiome();
-	if (!biomeCmd) throw new BiomeUnavailable({
-		message: ToolFailure.message("Biome not found.", BIOME_REMEDIATION),
-		remediation: BIOME_REMEDIATION
-	});
+	if (!biomeCmd) throw ToolRefusal.refuse("Biome not found.", BIOME_REMEDIATION);
 	const parts = biomeCmd.split(" ");
 	const bin = parts[0];
 	const prefix = parts.slice(1);
@@ -303,12 +300,18 @@ const biomeCheckTool = Tool.make("biome_check", {
 	success: BiomeCheckResult,
 	failure: McpToolError
 }).annotate(Tool.Title, "Biome check").annotate(Tool.Readonly, false).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, false).annotate(Tool.OpenWorld, false);
-const isMcpToolError = (u) => u instanceof InvalidArgument || u instanceof BiomeUnavailable || u instanceof BiomeFailed;
+/**
+* Every declared failure, recognized from the one union the tool declares, so
+* a member added to {@link McpToolError} is passed through here without a
+* second list to keep in step.
+*/
+const isMcpToolError = Schema.is(McpToolError);
 /**
 * Wire handler: {@link runBiomeCheck} lifted into Effect. The typed members it
 * throws pass through unchanged; anything else (a defect in the parser, say)
 * is reported as {@link BiomeFailed} so the error channel stays closed over
-* {@link McpToolError}.
+* {@link McpToolError} — nothing undeclared reaches core, which would scrub
+* it to a generic internal-error text.
 */
 const handleBiomeCheck = (fallbackCwd, params) => Effect.tryPromise({
 	try: () => runBiomeCheck(params, fallbackCwd),

package/tools/changeset-deps-detect.js

@@ -68,7 +68,7 @@ const ChangesetDepsDetectParams = Schema.Struct({
 	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
 });
 const REMEDIATION = {
-	hint: "The dependency diff could not be planned; check that the base branch exists locally and that every named package is a workspace member.",
+	hint: "The dependency diff could not be planned; check that the base branch exists locally, that every named package is a workspace member, and that every config dependency the base side declares is installed or in the pnpm store (a bumped config dependency's old version usually is not).",
 	suggestedTool: "workspace_info"
 };
 /** The `changeset_deps_detect` tool value. */

package/tools/changeset-deps-regen.js

@@ -77,7 +77,7 @@ const ChangesetDepsRegenParams = Schema.Struct({
 	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
 });
 const REMEDIATION = {
-	hint: "The dependency changesets could not be regenerated; preview the plan with dryRun=true, and check that the base branch exists locally and that every named package is a workspace member.",
+	hint: "The dependency changesets could not be regenerated; preview the plan with dryRun=true, and check that the base branch exists locally, that every named package is a workspace member, and that every config dependency the base side declares is installed or in the pnpm store (a bumped config dependency's old version usually is not).",
 	suggestedTool: "changeset_deps_detect"
 };
 /** The `changeset_deps_regen` tool value. Mutating: not read-only, not idempotent. */

package/tools/changeset-inspect.js

@@ -1,10 +1,18 @@
 import { McpToolError, mapEngineError } from "../errors.js";
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/changeset-inspect.ts
+/**
+* The `changeset_inspect` MCP tool: a discriminated-union result keyed by `mode`
+* (branch | config), each variant embedding the corresponding resolved-output
+* schema from silk-effects' Changesets namespace. Read-only.
+*
+* @packageDocumentation
+*/
 /** Branch-analysis variant. */
 const ChangesetBranchResult = Schema.Struct({
 	mode: Schema.Literal("branch"),
@@ -20,12 +28,15 @@ const ChangesetClassifyResult = Schema.Struct({
 	mode: Schema.Literal("classify"),
 	result: Schema.Array(Changesets.ClassificationSchema)
 }).annotate({ identifier: "ChangesetClassifyResult" });
-/** The `changeset_inspect` tool result — a discriminated union keyed by `mode`. */
-const ChangesetInspectResult = Schema.Union([
+/**
+* The `changeset_inspect` tool result — a discriminated union keyed by `mode`,
+* object-rooted so its `outputSchema` is served.
+*/
+const ChangesetInspectResult = ToolOutputSchema.objectRooted(Schema.Union([
 	ChangesetBranchResult,
 	ChangesetConfigResult,
 	ChangesetClassifyResult
-]).annotate({
+])).annotate({
 	identifier: "ChangesetInspectResult",
 	title: "changeset_inspect result",
 	description: "Read-only changeset analysis grouped by mode (branch | config | classify)."

package/tools/changeset-validate.js

@@ -1,5 +1,5 @@
-import { McpToolError, invalidArgument, mapEngineError } from "../errors.js";
-import { ToolFailure } from "@effected/mcp";
+import { McpToolError, mapEngineError } from "../errors.js";
+import { ToolFailure, ToolRefusal } from "@effected/mcp";
 import { Data, Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
@@ -77,10 +77,10 @@ const changesetValidateTool = Tool.make("changeset_validate", {
 * Wire handler: {@link changesetValidate} with its error channel mapped onto
 * {@link McpToolError}. The typed {@link ChangesetValidateError} (a thrown
 * validate — in practice a missing directory) is an argument problem, so it
-* becomes {@link InvalidArgument} naming `dir`; the echoed directory is
+* becomes a `ToolRefusal` naming the directory; the echoed directory is
 * truncated.
 */
-const handleChangesetValidate = (fallbackCwd, params) => changesetValidate(params, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "ChangesetValidateError" ? invalidArgument("dir", `Changeset directory "${ToolFailure.truncate(error.dir)}" could not be validated: ${describeCause(error.cause)}`, DIR_REMEDIATION) : mapEngineError(params.cwd ?? fallbackCwd, DIR_REMEDIATION)(error)));
+const handleChangesetValidate = (fallbackCwd, params) => changesetValidate(params, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "ChangesetValidateError" ? ToolRefusal.refuse(`Changeset directory "${ToolFailure.truncate(error.dir)}" could not be validated: ${describeCause(error.cause)}`, DIR_REMEDIATION) : mapEngineError(params.cwd ?? fallbackCwd, DIR_REMEDIATION)(error)));
 const describeCause = (cause) => cause instanceof Error ? ToolFailure.truncate(cause.message) : ToolFailure.truncate(String(cause));
 
 //#endregion

package/tools/repos-inspect.js

@@ -1,4 +1,5 @@
 import { McpToolError, mapEngineError } from "../errors.js";
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, FileSystem, Option, Path, Result, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
@@ -50,13 +51,16 @@ const ReposGitmodulesResult = Schema.Struct({
 	entries: Schema.Array(GitmodulesEntrySchema),
 	parseError: Schema.optionalKey(Schema.String)
 }).annotate({ identifier: "ReposGitmodulesResult" });
-/** The `repos_inspect` tool result — a discriminated union keyed by `mode`. */
-const ReposInspectResult = Schema.Union([
+/**
+* The `repos_inspect` tool result — a discriminated union keyed by `mode`,
+* object-rooted so its `outputSchema` is served.
+*/
+const ReposInspectResult = ToolOutputSchema.objectRooted(Schema.Union([
 	ReposStatusResult,
 	ReposConfigResult,
 	ReposDriftResult,
 	ReposGitmodulesResult
-]).annotate({
+])).annotate({
 	identifier: "ReposInspectResult",
 	title: "repos_inspect result",
 	description: "Drift report (status), the parsed manifest (config), the five-authority reconciliation report (drift), or the decoded .gitmodules sections (gitmodules)."

package/tools/repos-manage.js

@@ -1,6 +1,6 @@
-import { McpToolError, invalidArgument, mapEngineError } from "../errors.js";
-import { ToolFailure } from "@effected/mcp";
-import { Effect, Schema } from "effect";
+import { McpToolError, mapEngineError } from "../errors.js";
+import { McpToolkit, ToolOutputSchema, ToolRefusal } from "@effected/mcp";
+import { Effect, Result, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -9,70 +9,117 @@ import { Tool } from "effect/unstable/ai";
 /**
 * The `repos_manage` MCP tool: one action-discriminated mutating tool
 * covering `sync`, `pin`, `add`, `note`, `remove`, `rename`, `restore`, and
-* `deregister` against the vendored `.repos/` submodules. The wire schema is flat (no
-* `oneOf`); the handler maps it into an internal `Schema.TaggedStruct`
-* request union that names the missing field per action on decode failure.
-* Mutating — no `readOnlyHint`.
+* `deregister` against the vendored `.repos/` submodules. Its parameters are
+* a `Schema.Union` of one struct per action, served by `@effected/mcp`'s
+* `McpToolkit.unionTool` as a strict `oneOf` keyed by `action`; the handler
+* receives the decoded member. Mutating — no `readOnlyHint`.
 *
 * @packageDocumentation
 */
-/** `sync` has no extra fields. */
-const SyncRequest = Schema.TaggedStruct("sync", {});
+/** The optional `cwd` every action takes. */
+const cwd = Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }));
+/** `sync` has no fields of its own. */
+const SyncRequest = Schema.Struct({
+	action: Schema.Literal("sync"),
+	cwd
+}).annotate({ description: "Initialize/reconcile submodules per the manifest." });
 /** `pin` requires both `name` and `ref`. */
-const PinRequest = Schema.TaggedStruct("pin", {
-	name: Schema.String,
-	ref: Schema.String
-});
+const PinRequest = Schema.Struct({
+	action: Schema.Literal("pin"),
+	name: Schema.String.annotate({ description: "Repo name to re-pin." }),
+	ref: Schema.String.annotate({ description: "Git ref to pin to." }),
+	cwd
+}).annotate({ description: "Re-pin a repo to a new ref." });
 /**
 * `add` requires `url`/`ref`/`purpose`; `name`, `sparse` and `orientation`
 * are optional. `orientation` is what makes a re-vendor lossless — pass back
 * the block a preceding `remove` reported.
 */
-const AddRequest = Schema.TaggedStruct("add", {
-	url: Schema.String,
-	ref: Schema.String,
-	purpose: Schema.String,
-	name: Schema.optional(Schema.String),
-	sparse: Schema.optional(Schema.Array(Schema.String)),
-	orientation: Schema.optional(Repos.RepoOrientation)
-});
+const AddRequest = Schema.Struct({
+	action: Schema.Literal("add"),
+	url: Schema.String.annotate({ description: "Repo URL to vendor." }),
+	ref: Schema.String.annotate({ description: "Git ref to vendor." }),
+	purpose: Schema.String.annotate({ description: "One-line purpose for the manifest." }),
+	name: Schema.optionalKey(Schema.String.annotate({ description: "Override the repo name." })),
+	sparse: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Sparse-checkout patterns." })),
+	orientation: Schema.optionalKey(Repos.RepoOrientation.annotate({ description: "Orientation block to write. Pass back what a preceding remove reported as removedEntry.orientation — add does NOT restore it on its own, so a re-vendor loses it otherwise." })),
+	cwd
+}).annotate({ description: "Vendor a new repo." });
+/**
+* The note operation a `note` request names, or the reason it is incomplete.
+* The fields each `op` needs are enforced here rather than as three members
+* sharing `action: "note"`, so the served `oneOf` keeps one member per
+* action; the same function is the decode-time filter and the handler's
+* narrowing, so the two cannot disagree.
+*/
+const noteOperation = (request) => {
+	switch (request.op) {
+		case "add": return request.note === void 0 ? Result.fail("note op \"add\" requires `note`") : Result.succeed({
+			op: "add",
+			note: request.note
+		});
+		case "remove": return request.id === void 0 ? Result.fail("note op \"remove\" requires `id`") : Result.succeed({
+			op: "remove",
+			id: request.id
+		});
+		case "promote": return request.id === void 0 || request.into === void 0 ? Result.fail("note op \"promote\" requires both `id` and `into`") : Result.succeed({
+			op: "promote",
+			id: request.id,
+			into: request.into
+		});
+	}
+};
 /**
 * `note` requires `name` and `op`; the fields required beyond that depend on
 * `op` — enforced by the trailing filter so the decode error names exactly
 * what's missing for the chosen op.
 */
-const NoteRequest = Schema.TaggedStruct("note", {
-	name: Schema.String,
+const NoteRequest = Schema.Struct({
+	action: Schema.Literal("note"),
+	name: Schema.String.annotate({ description: "Repo name the note belongs to." }),
 	op: Schema.Literals([
 		"add",
 		"remove",
 		"promote"
-	]),
-	note: Schema.optional(Schema.String),
-	id: Schema.optional(Schema.String),
-	into: Schema.optional(Schema.Literals(["layout", "startHere"]))
-}).check(Schema.makeFilter((request) => {
-	if (request.op === "add" && request.note === void 0) return "note op \"add\" requires `note`";
-	if (request.op === "remove" && request.id === void 0) return "note op \"remove\" requires `id`";
-	if (request.op === "promote" && (request.id === void 0 || request.into === void 0)) return "note op \"promote\" requires both `id` and `into`";
-	return true;
-}));
+	]).annotate({ description: "Note operation." }),
+	note: Schema.optionalKey(Schema.String.annotate({ description: "Note text (op=add)." })),
+	id: Schema.optionalKey(Schema.String.annotate({ description: "Note id (op=remove|promote)." })),
+	into: Schema.optionalKey(Schema.Literals(["layout", "startHere"]).annotate({ description: "Orientation target (op=promote)." })),
+	cwd
+}).check(Schema.makeFilter((request) => Result.match(noteOperation(request), {
+	onFailure: (reason) => reason,
+	onSuccess: () => true
+}))).annotate({ description: "Add, remove or promote an agent note." });
 /** `remove` requires only `name`. */
-const RemoveRequest = Schema.TaggedStruct("remove", { name: Schema.String });
+const RemoveRequest = Schema.Struct({
+	action: Schema.Literal("remove"),
+	name: Schema.String.annotate({ description: "Repo name to unvendor." }),
+	cwd
+}).annotate({ description: "Unvendor a repo." });
 /** `rename` requires `name` (the old name) and `newName`. */
-const RenameRequest = Schema.TaggedStruct("rename", {
-	name: Schema.String,
-	newName: Schema.String
-});
+const RenameRequest = Schema.Struct({
+	action: Schema.Literal("rename"),
+	name: Schema.String.annotate({ description: "The repo's current name." }),
+	newName: Schema.String.annotate({ description: "New repo name." }),
+	cwd
+}).annotate({ description: "Rename a vendored repo's manifest key and worktree." });
 /** `restore`'s `names` is optional and repeatable, mirroring `add`'s `sparse`; omitted means "every dirty entry". */
-const RestoreRequest = Schema.TaggedStruct("restore", { names: Schema.optional(Schema.Array(Schema.String)) });
+const RestoreRequest = Schema.Struct({
+	action: Schema.Literal("restore"),
+	names: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Repo names to restore; omitted restores every dirty repo." })),
+	cwd
+}).annotate({ description: "Hard-reset worktrees back to their pinned gitlink commits." });
 /**
 * `deregister` requires `section` — the stale registration name exactly as the
 * drift report states it (e.g. `.repos/old-name`); the `submodule.` prefix is
 * implied, never passed.
 */
-const DeregisterRequest = Schema.TaggedStruct("deregister", { section: Schema.String });
-/** Internal tagged-union request the flat wire args decode into. */
+const DeregisterRequest = Schema.Struct({
+	action: Schema.Literal("deregister"),
+	section: Schema.String.annotate({ description: "Stale registration name to clear, exactly as the drift report states it (e.g. .repos/old-name); the submodule. prefix is implied." }),
+	cwd
+}).annotate({ description: "Clear a stale submodule registration from local git config." });
+/** The `repos_manage` parameters: one struct per action, discriminated by `action`. */
 const ReposManageRequest = Schema.Union([
 	SyncRequest,
 	PinRequest,
@@ -123,8 +170,11 @@ const ReposManageDeregisterResult = Schema.Struct({
 	action: Schema.Literal("deregister"),
 	result: Repos.ReposDeregisterResult
 }).annotate({ identifier: "ReposManageDeregisterResult" });
-/** The `repos_manage` tool result — a discriminated union keyed by `action`. */
-const ReposManageResult = Schema.Union([
+/**
+* The `repos_manage` tool result — a discriminated union keyed by `action`,
+* object-rooted so its `outputSchema` is served (every member is a struct).
+*/
+const ReposManageResult = ToolOutputSchema.objectRooted(Schema.Union([
 	ReposManageSyncResult,
 	ReposManagePinResult,
 	ReposManageAddResult,
@@ -133,25 +183,24 @@ const ReposManageResult = Schema.Union([
 	ReposManageRenameResult,
 	ReposManageRestoreResult,
 	ReposManageDeregisterResult
-]).annotate({
+])).annotate({
 	identifier: "ReposManageResult",
 	title: "repos_manage result",
 	description: "Result of a mutating repos action: sync, pin, add, note, remove, rename, restore, or deregister."
 });
+const REMEDIATION = {
+	hint: "The mutation did not complete; inspect the vendored-repo state before retrying.",
+	suggestedTool: "repos_inspect"
+};
+const REQUEST_REMEDIATION = { hint: "Pass the fields the chosen note op needs: note (op=add), id (op=remove), or id and into (op=promote)." };
 /**
-* Effect handler: resolve the workspace root, decode the flat wire args into
-* the internal per-action request (naming the missing field on failure), then
-* dispatch to the matching `ReposManager` method.
+* Effect handler: resolve the workspace root, then dispatch the decoded
+* request to the matching `ReposManager` method.
 */
-const reposManage = (args, fallbackCwd) => Effect.gen(function* () {
-	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
+const reposManage = (request, fallbackCwd) => Effect.gen(function* () {
+	const root = yield* (yield* WorkspaceRoot).find(request.cwd ?? fallbackCwd);
 	const manager = yield* Repos.ReposManager;
-	const { action, cwd: _cwd, ...rest } = args;
-	const request = yield* Schema.decodeUnknownEffect(ReposManageRequest)({
-		_tag: action,
-		...rest
-	});
-	switch (request._tag) {
+	switch (request.action) {
 		case "sync": return {
 			action: "sync",
 			result: yield* manager.sync(root)
@@ -172,20 +221,11 @@ const reposManage = (args, fallbackCwd) => Effect.gen(function* () {
 			})
 		};
 		case "note": {
-			const noteOp = request.op === "add" ? {
-				op: "add",
-				note: request.note
-			} : request.op === "remove" ? {
-				op: "remove",
-				id: request.id
-			} : {
-				op: "promote",
-				id: request.id,
-				into: request.into
-			};
+			const operation = noteOperation(request);
+			if (Result.isFailure(operation)) return yield* ToolRefusal.refuse(`repos_manage note: ${operation.failure}.`, REQUEST_REMEDIATION);
 			return {
 				action: "note",
-				result: yield* manager.note(root, request.name, noteOp)
+				result: yield* manager.note(root, request.name, operation.success)
 			};
 		}
 		case "remove": return {
@@ -206,59 +246,27 @@ const reposManage = (args, fallbackCwd) => Effect.gen(function* () {
 		};
 	}
 });
-/** Wire parameters for `repos_manage`: flat (no `oneOf`); the handler decodes them per action. */
-const ReposManageParams = Schema.Struct({
-	action: Schema.Literals([
-		"sync",
-		"pin",
-		"add",
-		"note",
-		"remove",
-		"rename",
-		"restore",
-		"deregister"
-	]).annotate({ description: "Which mutation to perform." }),
-	name: Schema.optionalKey(Schema.String.annotate({ description: "Repo name (pin, note, remove, rename; optional override for add)." })),
-	newName: Schema.optionalKey(Schema.String.annotate({ description: "New repo name (rename)." })),
-	ref: Schema.optionalKey(Schema.String.annotate({ description: "Git ref to pin/vendor to (pin, add)." })),
-	url: Schema.optionalKey(Schema.String.annotate({ description: "Repo URL to vendor (add)." })),
-	purpose: Schema.optionalKey(Schema.String.annotate({ description: "One-line purpose for the manifest (add)." })),
-	sparse: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Sparse-checkout patterns (add)." })),
-	orientation: Schema.optionalKey(Repos.RepoOrientation.annotate({ description: "Orientation block to write (add). Pass back what a preceding remove reported as removedEntry.orientation — add does NOT restore it on its own, so a re-vendor loses it otherwise." })),
-	op: Schema.optionalKey(Schema.Literals([
-		"add",
-		"remove",
-		"promote"
-	]).annotate({ description: "Note operation (note)." })),
-	note: Schema.optionalKey(Schema.String.annotate({ description: "Note text (note, op=add)." })),
-	id: Schema.optionalKey(Schema.String.annotate({ description: "Note id (note, op=remove|promote)." })),
-	into: Schema.optionalKey(Schema.Literals(["layout", "startHere"]).annotate({ description: "Orientation target (note, op=promote)." })),
-	names: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Repo names to restore (restore); omitted restores every dirty repo." })),
-	section: Schema.optionalKey(Schema.String.annotate({ description: "Stale registration name to clear (deregister), exactly as the drift report states it (e.g. .repos/old-name); the submodule. prefix is implied." })),
-	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
-});
-const REMEDIATION = {
-	hint: "The mutation did not complete; inspect the vendored-repo state before retrying.",
-	suggestedTool: "repos_inspect"
-};
-const REQUEST_REMEDIATION = { hint: "Pass the fields the chosen action needs (pin: name+ref; add: url+ref+purpose; note: name+op plus note/id/into; remove: name; rename: name+newName; deregister: section)." };
-/** The `repos_manage` tool value. Mutating: not read-only, not idempotent. */
-const reposManageTool = Tool.make("repos_manage", {
-	description: "Mutating: sync (initialize/reconcile submodules per the manifest), pin (re-pin a repo to a new ref), add (vendor a new repo), note (add/remove/promote an agent note), remove (unvendor a repo), rename (rename a vendored repo's manifest key and worktree), restore (hard-reset a repo's worktree back to its pinned gitlink commit and re-apply sparse paths — DESTRUCTIVE to uncommitted worktree edits; never run implicitly), or deregister (clear a STALE submodule.<section> registration from the superproject's local git config — the phantom entry repos_inspect drift reports as localRegistrationDivergence with no matching manifest entry; refuses a section outside .repos/ and any section still backing a live manifest entry — canonically named or gitdir-diverged — and touches local config only, so nothing is staged). Pass action plus the fields that action needs: pin needs name+ref; add needs url+ref+purpose (name/sparse/orientation optional — pass orientation back from a preceding remove's removedEntry to make a re-vendor lossless); note needs name+op, plus note (op=add), id (op=remove), or id+into (op=promote); remove needs name; rename needs name (the old name) + newName; restore takes an optional names list — omitted, it restores every dirty repo and reports the clean ones as skipped; given, it restores exactly those repos even if already clean; deregister needs section (the registration name exactly as the drift report states it, e.g. .repos/old-name — no submodule. prefix). A decode failure names the missing field. The pin result surfaces commitMessage and staleNoteIds — review and commit after pinning. The remove result surfaces commitMessage, removedNotes and the removed entry's orientation block — promote any durable notes elsewhere, keep the orientation if you intend to re-vendor, then review and commit. The rename result surfaces commitMessage — review and commit after renaming. The restore result names exactly what was discarded. The deregister result lists the config keys the removed section carried — nothing to commit afterwards. Returns a typed object in structuredContent (content[] carries the same object as JSON).",
-	parameters: ReposManageParams,
+/**
+* The `repos_manage` tool value: a `McpToolkit.unionTool`, so the served input
+* schema is the request union's strict `oneOf` keyed by `action`, and a bad
+* call is rejected as invalid parameters before the handler runs. Mutating:
+* not read-only, not idempotent.
+*/
+const reposManageTool = McpToolkit.unionTool("repos_manage", {
+	description: "Mutating: sync (initialize/reconcile submodules per the manifest), pin (re-pin a repo to a new ref), add (vendor a new repo), note (add/remove/promote an agent note), remove (unvendor a repo), rename (rename a vendored repo's manifest key and worktree), restore (hard-reset a repo's worktree back to its pinned gitlink commit and re-apply sparse paths — DESTRUCTIVE to uncommitted worktree edits; never run implicitly), or deregister (clear a STALE submodule.<section> registration from the superproject's local git config — the phantom entry repos_inspect drift reports as localRegistrationDivergence with no matching manifest entry; refuses a section outside .repos/ and any section still backing a live manifest entry — canonically named or gitdir-diverged — and touches local config only, so nothing is staged). Pass action plus the fields that action needs: pin needs name+ref; add needs url+ref+purpose (name/sparse/orientation optional — pass orientation back from a preceding remove's removedEntry to make a re-vendor lossless); note needs name+op, plus note (op=add), id (op=remove), or id+into (op=promote); remove needs name; rename needs name (the old name) + newName; restore takes an optional names list — omitted, it restores every dirty repo and reports the clean ones as skipped; given, it restores exactly those repos even if already clean; deregister needs section (the registration name exactly as the drift report states it, e.g. .repos/old-name — no submodule. prefix). Each action's fields are served as one member of a strict oneOf keyed by action; a missing field or a key the chosen action does not take is rejected as invalid parameters naming it. The pin result surfaces commitMessage and staleNoteIds — review and commit after pinning. The remove result surfaces commitMessage, removedNotes and the removed entry's orientation block — promote any durable notes elsewhere, keep the orientation if you intend to re-vendor, then review and commit. The rename result surfaces commitMessage — review and commit after renaming. The restore result names exactly what was discarded. The deregister result lists the config keys the removed section carried — nothing to commit afterwards. Returns a typed object in structuredContent (content[] carries the same object as JSON).",
+	parameters: ReposManageRequest,
 	success: ReposManageResult,
 	failure: McpToolError,
 	dependencies: [Repos.ReposManager, WorkspaceRoot]
 }).annotate(Tool.Title, "Manage vendored repos").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.Idempotent, false).annotate(Tool.OpenWorld, false);
 /**
-* Wire handler: {@link reposManage} with its error channel mapped onto
-* {@link McpToolError}. The per-action request decode failure (`SchemaError`,
-* which names the missing field, and echoes the decoded value) is an argument
-* problem and becomes {@link InvalidArgument} keyed on `action`, its text
-* truncated at `ToolFailure.ENGINE_ECHO_LIMIT`; the engine's own errors go
-* through {@link mapEngineError}.
+* Wire handler: `McpToolkit.unionHandler` decodes the raw payload into one
+* {@link ReposManageRequest} member (an unknown key or a missing field fails
+* `InvalidParams`, as a `Tool.make` decode failure does), then
+* {@link reposManage} runs with its engine errors mapped onto
+* {@link McpToolError} through {@link mapEngineError}.
 */
-const handleReposManage = (fallbackCwd, params) => reposManage(params, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "SchemaError" ? invalidArgument("action", `repos_manage ${params.action}: ${ToolFailure.truncate(error.message, ToolFailure.ENGINE_ECHO_LIMIT)}`, REQUEST_REMEDIATION) : mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)(error)));
+const handleReposManage = (fallbackCwd) => McpToolkit.unionHandler(reposManageTool, (request) => reposManage(request, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "ToolRefusal" ? error : mapEngineError(request.cwd ?? fallbackCwd, REMEDIATION)(error))));
 
 //#endregion
-export { ReposManageAddResult, ReposManageDeregisterResult, ReposManageNoteResult, ReposManageParams, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, handleReposManage, reposManage, reposManageTool };
+export { ReposManageAddResult, ReposManageDeregisterResult, ReposManageNoteResult, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRequest, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, handleReposManage, reposManage, reposManageTool };

package/tools/turbo-inspect.js

@@ -1,10 +1,18 @@
 import { McpToolError, mapEngineError } from "../errors.js";
+import { ToolOutputSchema } from "@effected/mcp";
 import { Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Turbo } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/turbo-inspect.ts
+/**
+* The `turbo_inspect` MCP tool: a discriminated-union result schema keyed by
+* `mode` (cache | graph | affected), each variant embedding the corresponding
+* `Turbo` result schema from silk-effects. Read-only.
+*
+* @packageDocumentation
+*/
 /** Cache-diagnosis variant of the `turbo_inspect` result. */
 const TurboCacheResult = Schema.Struct({
 	mode: Schema.Literal("cache"),
@@ -20,12 +28,15 @@ const TurboAffectedResult = Schema.Struct({
 	mode: Schema.Literal("affected"),
 	result: Turbo.AffectedResult
 }).annotate({ identifier: "TurboAffectedResult" });
-/** The `turbo_inspect` tool result — a discriminated union keyed by `mode`. */
-const TurboInspectResult = Schema.Union([
+/**
+* The `turbo_inspect` tool result — a discriminated union keyed by `mode`,
+* object-rooted so its `outputSchema` is served.
+*/
+const TurboInspectResult = ToolOutputSchema.objectRooted(Schema.Union([
 	TurboCacheResult,
 	TurboGraphResult,
 	TurboAffectedResult
-]).annotate({
+])).annotate({
 	identifier: "TurboInspectResult",
 	title: "turbo_inspect result",
 	description: "Read-only Turborepo inspection grouped by mode (cache | graph | affected)."

package/version.js

@@ -6,7 +6,7 @@
 *
 * @packageDocumentation
 */
-const CURRENT_MCP_VERSION = "3.3.0";
+const CURRENT_MCP_VERSION = "3.4.1";
 
 //#endregion
 export { CURRENT_MCP_VERSION };