@savvy-web/mcp 2.7.4 → 3.0.0

package/tools/biome-check.js

@@ -1,5 +1,8 @@
+import { BiomeFailed, BiomeUnavailable, InvalidArgument, McpToolError, composeRemediatedMessage, invalidArgument, truncateEchoed } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { Lint } from "@savvy-web/silk-effects";
-import { Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 import { spawnSync } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { relative, resolve, sep } from "node:path";
@@ -208,29 +211,48 @@ const resolveContainmentRoot = (root, cwd, probe = gitWorktreeProbe) => {
 	if (from.topLevel === home.topLevel) return null;
 	return from.topLevel;
 };
+/** Remediation for a path or cwd that escapes the containment tree. */
+const CONTAINMENT_REMEDIATION = { hint: "Keep cwd and every path inside the server's workspace root, or inside a git worktree of the same repository." };
+/** Remediation when no Biome binary can be located. */
+const BIOME_REMEDIATION = { hint: "Install @biomejs/biome globally (recommended) or as a devDependency of the workspace." };
+/** Remediation when Biome itself fails (not "lint issues found", which is a result). */
+const BIOME_FAILED_REMEDIATION = { hint: "Biome did not complete; the message carries its stderr. Fix the configuration or invocation and retry." };
+/** Build a {@link BiomeFailed} from a spawn error or a non-lint exit status. */
+const biomeFailed = (raw, exitCode) => new BiomeFailed({
+	...exitCode === void 0 ? {} : { exitCode },
+	message: composeRemediatedMessage(raw, BIOME_FAILED_REMEDIATION),
+	remediation: BIOME_FAILED_REMEDIATION
+});
 /**
 * Run Biome and return structured diagnostics. When `write`/`unsafe` is set,
 * runs a fix pass first, then a read-only gitlab pass to report what remains.
 *
 * @remarks Resolves the Biome binary via {@link Lint.Biome.findBiome} (global
-* first, then the project's package manager). Throws if Biome is unavailable or
-* exits with status > 1 (Biome itself failed, vs. status 1 = lint issues found).
+* 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.
 */
 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 new Error(`cwd escapes the workspace root: ${args.cwd}`);
+	if (containmentRoot === null) throw invalidArgument("cwd", `cwd escapes the workspace root: ${truncateEchoed(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 new Error(`path escapes the workspace root: ${p}`);
+		if (!within(canonicalize(lexical))) throw invalidArgument("paths", `path escapes the workspace root: ${truncateEchoed(p)}.`, CONTAINMENT_REMEDIATION);
 		return relative(cwd, lexical) || ".";
 	});
 	const doWrite = Boolean(args.write || args.unsafe);
 	const biomeCmd = Lint.Biome.findBiome();
-	if (!biomeCmd) throw new Error("Biome not found. Install @biomejs/biome globally (recommended) or as a devDependency.");
+	if (!biomeCmd) throw new BiomeUnavailable({
+		message: composeRemediatedMessage("Biome not found.", BIOME_REMEDIATION),
+		remediation: BIOME_REMEDIATION
+	});
 	const parts = biomeCmd.split(" ");
 	const bin = parts[0];
 	const prefix = parts.slice(1);
@@ -254,8 +276,8 @@ const runBiomeCheck = async (args, fallbackCwd) => {
 			timeout,
 			killSignal
 		});
-		if (fix.error) throw fix.error;
-		if ((fix.status ?? 0) > 1) throw new Error(`Biome --write failed (exit ${fix.status}): ${(fix.stderr ?? "").trim() || "unknown error"}`);
+		if (fix.error) throw biomeFailed(`Biome --write could not run: ${fix.error.message}`);
+		if ((fix.status ?? 0) > 1) throw biomeFailed(`Biome --write failed (exit ${fix.status}): ${(fix.stderr ?? "").trim() || "unknown error"}`, fix.status ?? void 0);
 		wrote = true;
 	}
 	const readArgs = [
@@ -272,14 +294,45 @@ const runBiomeCheck = async (args, fallbackCwd) => {
 		timeout,
 		killSignal
 	});
-	if (read.error) throw read.error;
-	if ((read.status ?? 0) > 1) throw new Error(`Biome failed (exit ${read.status}): ${(read.stderr ?? "").trim() || "unknown error"}`);
+	if (read.error) throw biomeFailed(`Biome could not run: ${read.error.message}`);
+	if ((read.status ?? 0) > 1) throw biomeFailed(`Biome failed (exit ${read.status}): ${(read.stderr ?? "").trim() || "unknown error"}`, read.status ?? void 0);
 	return buildBiomeResult({
 		diagnostics: parseBiomeGitlab(read.stdout ?? ""),
 		wrote,
 		...args.strict !== void 0 ? { strict: args.strict } : {}
 	});
 };
+/** Wire parameters for `biome_check`. */
+const BiomeCheckParams = Schema.Struct({
+	paths: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Paths to check. Defaults to the whole workspace." })),
+	mode: Schema.optionalKey(Schema.Literals(["check", "lint"]).annotate({ description: "check = lint+format+imports (default); lint = lint only." })),
+	write: Schema.optionalKey(Schema.Boolean.annotate({ description: "Apply safe fixes (--write)." })),
+	unsafe: Schema.optionalKey(Schema.Boolean.annotate({ description: "Apply unsafe fixes (--write --unsafe); implies write." })),
+	strict: Schema.optionalKey(Schema.Boolean.annotate({ description: "Report project warnings as errors (marked with originalSeverity). Default: honor project config." })),
+	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to run from. May be the server's workspace root, a directory inside it, or a git worktree of the SAME repository — a worktree contains the run to that worktree instead of the main checkout. Anything else is rejected." }))
+});
+/**
+* The `biome_check` tool value. Mutating when `write`/`unsafe` is set, so it is
+* annotated non-read-only and non-idempotent; `dependencies` is empty because
+* the handler shells out directly and yields no service.
+*/
+const biomeCheckTool = Tool.make("biome_check", {
+	description: "Run Biome over a path and get structured diagnostics back. mode=check (default; lint + format + organize-imports) or mode=lint. Set write=true to apply safe fixes (--write), unsafe=true for unsafe fixes (--write --unsafe). Severities match the project's Biome config (what `biome check` reports); set strict=true to surface project warnings as errors, each marked with its originalSeverity. Prefer this over shelling out to biome; the LSP already covers files you've edited. Returns markdown in content[] and a typed object in structuredContent. NOTE: with write/unsafe this tool MUTATES files (git-reversible).",
+	parameters: BiomeCheckParams,
+	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).annotate(SilkMarkdown, Schema.decodeUnknownSync(BiomeCheckAsMarkdown));
+const isMcpToolError = (u) => u instanceof InvalidArgument || u instanceof BiomeUnavailable || u instanceof BiomeFailed;
+/**
+* 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}.
+*/
+const handleBiomeCheck = (fallbackCwd, params) => Effect.tryPromise({
+	try: () => runBiomeCheck(params, fallbackCwd),
+	catch: (cause) => isMcpToolError(cause) ? cause : biomeFailed(`Biome check failed: ${cause instanceof Error ? cause.message : String(cause)}`)
+});
 
 //#endregion
-export { BiomeCheckAsMarkdown, BiomeCheckResult, BiomeDiagnostic, BiomeSeverity, buildBiomeResult, parseBiomeGitlab, resolveContainmentRoot, runBiomeCheck };
+export { BiomeCheckAsMarkdown, BiomeCheckParams, BiomeCheckResult, BiomeDiagnostic, BiomeSeverity, biomeCheckTool, buildBiomeResult, handleBiomeCheck, parseBiomeGitlab, resolveContainmentRoot, runBiomeCheck };

package/tools/changeset-deps-detect.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/changeset-deps-detect.ts
 /** One affected workspace package's resolved dependency diff. */
@@ -100,6 +103,28 @@ const changesetDepsDetect = (args, fallbackCwd) => Effect.gen(function* () {
 		}))
 	};
 });
+/** Wire parameters for `changeset_deps_detect`. */
+const ChangesetDepsDetectParams = Schema.Struct({
+	base: Schema.optionalKey(Schema.String.annotate({ description: "Override the base branch used to compute the merge-base." })),
+	package: Schema.optionalKey(Schema.String.annotate({ description: "Restrict output to a single workspace package." })),
+	packages: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Restrict output to these workspace packages (unioned with package)." })),
+	exclude: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Drop these packages from the output entirely." })),
+	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.",
+	suggestedTool: "workspace_info"
+};
+/** The `changeset_deps_detect` tool value. */
+const changesetDepsDetectTool = Tool.make("changeset_deps_detect", {
+	description: "Read-only preview of the cumulative dependency diff (merge-base -> working tree) per workspace package. Returns each affected package's resolved dependency-table rows (catalog:/workspace: specifiers resolved per side; devDependencies retained) as the exact rows a pure-dependency changeset would carry, plus a coexisting list of untouched prose-only changesets that reference an in-scope package (informational — no need to re-list .changeset/). Does NOT write or delete any file. Prefer this over shelling out to savvy changeset deps detect.",
+	parameters: ChangesetDepsDetectParams,
+	success: ChangesetDepsDetectResult,
+	failure: McpToolError,
+	dependencies: [WorkspaceRoot, Changesets.DepsRegen]
+}).annotate(Tool.Title, "Detect dependency changesets").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ChangesetDepsDetectAsMarkdown));
+/** Wire handler: {@link changesetDepsDetect} with its error channel mapped onto {@link McpToolError}. */
+const handleChangesetDepsDetect = (fallbackCwd, params) => changesetDepsDetect(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { ChangesetDepsDetectAsMarkdown, ChangesetDepsDetectCoexisting, ChangesetDepsDetectPackage, ChangesetDepsDetectResult, changesetDepsDetect };
+export { ChangesetDepsDetectAsMarkdown, ChangesetDepsDetectCoexisting, ChangesetDepsDetectPackage, ChangesetDepsDetectParams, ChangesetDepsDetectResult, changesetDepsDetect, changesetDepsDetectTool, handleChangesetDepsDetect };

package/tools/changeset-deps-regen.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/changeset-deps-regen.ts
 /**
@@ -110,6 +113,29 @@ const changesetDepsRegen = (args, fallbackCwd) => Effect.gen(function* () {
 		dryRun: false
 	};
 });
+/** Wire parameters for `changeset_deps_regen`. */
+const ChangesetDepsRegenParams = Schema.Struct({
+	base: Schema.optionalKey(Schema.String.annotate({ description: "Override the base branch used to compute the merge-base." })),
+	package: Schema.optionalKey(Schema.String.annotate({ description: "Restrict regeneration to a single workspace package." })),
+	packages: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Restrict regeneration to these workspace packages (unioned with package)." })),
+	exclude: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Skip these packages entirely: nothing written, existing changesets untouched." })),
+	dryRun: Schema.optionalKey(Schema.Boolean.annotate({ description: "Compute the plan without writing or deleting any file." })),
+	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.",
+	suggestedTool: "changeset_deps_detect"
+};
+/** The `changeset_deps_regen` tool value. Mutating: not read-only, not idempotent. */
+const changesetDepsRegenTool = Tool.make("changeset_deps_regen", {
+	description: "Regenerate pure-dependency changesets: delete stale single-package Dependencies-only changesets and write fresh single-package, patch-bump changesets from the cumulative dependency diff (catalog:/workspace: resolved; devDependencies dropped). Mixed changesets (Dependencies plus other content) are left untouched, and the result's coexisting list accounts for untouched prose-only changesets that reference an in-scope package (informational — no need to re-list .changeset/). Set dryRun=true to preview the plan without touching the filesystem. NOTE: without dryRun this tool MUTATES .changeset/*.md (git-reversible). Prefer this over shelling out to savvy changeset deps regen.",
+	parameters: ChangesetDepsRegenParams,
+	success: ChangesetDepsRegenResult,
+	failure: McpToolError,
+	dependencies: [WorkspaceRoot, Changesets.DepsRegen]
+}).annotate(Tool.Title, "Regenerate dependency changesets").annotate(Tool.Readonly, false).annotate(Tool.Destructive, true).annotate(Tool.Idempotent, false).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ChangesetDepsRegenAsMarkdown));
+/** Wire handler: {@link changesetDepsRegen} with its error channel mapped onto {@link McpToolError}. */
+const handleChangesetDepsRegen = (fallbackCwd, params) => changesetDepsRegen(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { ChangesetCoexistingEntry, ChangesetDepsRegenAsMarkdown, ChangesetDepsRegenResult, changesetDepsRegen };
+export { ChangesetCoexistingEntry, ChangesetDepsRegenAsMarkdown, ChangesetDepsRegenParams, ChangesetDepsRegenResult, changesetDepsRegen, changesetDepsRegenTool, handleChangesetDepsRegen };

package/tools/changeset-inspect.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/changeset-inspect.ts
 /** Branch-analysis variant. */
@@ -124,6 +127,35 @@ const changesetInspect = (args, fallbackCwd) => Effect.gen(function* () {
 		};
 	}
 });
+/** Wire parameters for `changeset_inspect`. */
+const ChangesetInspectParams = Schema.Struct({
+	mode: Schema.Literals([
+		"branch",
+		"config",
+		"classify"
+	]).annotate({ description: "Which inspection to run." }),
+	base: Schema.optionalKey(Schema.String.annotate({ description: "Override the base branch (branch mode only)." })),
+	paths: Schema.optionalKey(Schema.Array(Schema.String).annotate({ description: "Paths to classify (classify mode only)." })),
+	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
+});
+const REMEDIATION = {
+	hint: "Check .changeset/config.json and that the base branch exists locally (fetch it if the merge base cannot be computed).",
+	suggestedTool: "changeset_inspect"
+};
+/** The `changeset_inspect` tool value. */
+const changesetInspectTool = Tool.make("changeset_inspect", {
+	description: "Read-only changeset analysis for the changeset-manager workflow. mode=branch diffs the current branch against its base and classifies every changed file by owning package (with packagesAffected and the unmapped paths to ask the user about; an unmapped path may carry a machine-readable unmappedHint reason — e.g. a deleted versionFiles/additionalScopes target or a known template mirror — meaning it is probably already accounted for). mode=config surfaces the resolved .changeset/config.json (release surfaces, versionFiles, ignore list). mode=classify maps arbitrary repo-relative paths to their owning package. Prefer this over shelling out to the savvy CLI.",
+	parameters: ChangesetInspectParams,
+	success: ChangesetInspectResult,
+	failure: McpToolError,
+	dependencies: [
+		Changesets.BranchAnalyzer,
+		Changesets.ConfigInspector,
+		WorkspaceRoot
+	]
+}).annotate(Tool.Title, "Inspect changesets").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ChangesetInspectAsMarkdown));
+/** Wire handler: {@link changesetInspect} with its error channel mapped onto {@link McpToolError}. */
+const handleChangesetInspect = (fallbackCwd, params) => changesetInspect(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { ChangesetBranchResult, ChangesetClassifyResult, ChangesetConfigResult, ChangesetInspectAsMarkdown, ChangesetInspectResult, changesetInspect };
+export { ChangesetBranchResult, ChangesetClassifyResult, ChangesetConfigResult, ChangesetInspectAsMarkdown, ChangesetInspectParams, ChangesetInspectResult, changesetInspect, changesetInspectTool, handleChangesetInspect };

package/tools/changeset-preview.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/changeset-preview.ts
 /** The `changeset_preview` result — the silk-effects preview shape. */
@@ -39,6 +42,22 @@ const changesetPreview = (args, fallbackCwd) => Effect.gen(function* () {
 	const root = yield* (yield* WorkspaceRoot).find(args.cwd ?? fallbackCwd);
 	return yield* (yield* Changesets.ReleasePlanner).preview(root);
 });
+/** Wire parameters for `changeset_preview`. */
+const ChangesetPreviewParams = Schema.Struct({ cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." })) });
+const REMEDIATION = {
+	hint: "The changesets engine could not render the release; validate the pending changesets first.",
+	suggestedTool: "changeset_validate"
+};
+/** The `changeset_preview` tool value. */
+const changesetPreviewTool = Tool.make("changeset_preview", {
+	description: "Read-only preview of the next release. Runs the genuine changesets engine over the pending changesets and returns each package's version bump (old -> new) plus the rendered CHANGELOG block (dependency tables included), exactly as it would ship. Does not modify the repo. Prefer this over hand-merging changeset files.",
+	parameters: ChangesetPreviewParams,
+	success: ChangesetPreviewResult,
+	failure: McpToolError,
+	dependencies: [Changesets.ReleasePlanner, WorkspaceRoot]
+}).annotate(Tool.Title, "Preview the next release").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ChangesetPreviewAsMarkdown));
+/** Wire handler: {@link changesetPreview} with its error channel mapped onto {@link McpToolError}. */
+const handleChangesetPreview = (fallbackCwd, params) => changesetPreview(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { ChangesetPreviewAsMarkdown, ChangesetPreviewResult, changesetPreview };
+export { ChangesetPreviewAsMarkdown, ChangesetPreviewParams, ChangesetPreviewResult, changesetPreview, changesetPreviewTool, handleChangesetPreview };

package/tools/changeset-validate.js

@@ -1,6 +1,9 @@
+import { McpToolError, invalidArgument, mapEngineError, truncateEchoed } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Data, Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
-import { Data, Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 import { resolve } from "node:path";
 
 //#region src/tools/changeset-validate.ts
@@ -79,6 +82,29 @@ const changesetValidate = (args, fallbackCwd) => Effect.gen(function* () {
 		messages
 	};
 });
+/** Wire parameters for `changeset_validate`. */
+const ChangesetValidateParams = Schema.Struct({
+	dir: Schema.optionalKey(Schema.String.annotate({ description: "Changeset directory to validate (default .changeset)." })),
+	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
+});
+const DIR_REMEDIATION = { hint: "Pass dir as a path (relative to the workspace root) to an existing changeset directory, or omit it for .changeset." };
+/** The `changeset_validate` tool value. */
+const changesetValidateTool = Tool.make("changeset_validate", {
+	description: "Read-only validation of changeset files against the section-aware rules. Pass dir (default .changeset). Returns typed diagnostics (file, rule, line, column, message) plus ok/errorCount in structuredContent. Prefer this over shelling out to savvy changeset lint.",
+	parameters: ChangesetValidateParams,
+	success: ChangesetValidateResult,
+	failure: McpToolError,
+	dependencies: [WorkspaceRoot]
+}).annotate(Tool.Title, "Validate changesets").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ChangesetValidateAsMarkdown));
+/**
+* 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
+* truncated.
+*/
+const handleChangesetValidate = (fallbackCwd, params) => changesetValidate(params, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "ChangesetValidateError" ? invalidArgument("dir", `Changeset directory "${truncateEchoed(error.dir)}" could not be validated: ${describeCause(error.cause)}`, DIR_REMEDIATION) : mapEngineError(params.cwd ?? fallbackCwd, DIR_REMEDIATION)(error)));
+const describeCause = (cause) => cause instanceof Error ? truncateEchoed(cause.message) : truncateEchoed(String(cause));
 
 //#endregion
-export { ChangesetLintMessage, ChangesetValidateAsMarkdown, ChangesetValidateError, ChangesetValidateResult, changesetValidate };
+export { ChangesetLintMessage, ChangesetValidateAsMarkdown, ChangesetValidateError, ChangesetValidateParams, ChangesetValidateResult, changesetValidate, changesetValidateTool, handleChangesetValidate };

package/tools/repos-inspect.js

@@ -1,7 +1,10 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
 import { mdInline } from "./md-inline.js";
+import { Effect, FileSystem, Option, Path, Result, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
-import { Effect, FileSystem, Option, Path, Result, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 import { Gitmodules } from "@effected/git";
 
 //#region src/tools/repos-inspect.ts
@@ -186,6 +189,39 @@ const reposInspect = (args, fallbackCwd) => Effect.gen(function* () {
 		}
 	}
 });
+/**
+* The `repos_inspect` wire-level `mode` enum. Exported so tests can assert
+* the boundary rejects an unknown mode without duplicating the member list.
+*/
+const ReposInspectMode = Schema.Literals([
+	"status",
+	"config",
+	"drift",
+	"gitmodules"
+]).annotate({ description: "status = drift report; config = the full agent brief; drift = five-authority submodule reconciliation; gitmodules = decoded .gitmodules sections." });
+/** Wire parameters for `repos_inspect`. */
+const ReposInspectParams = Schema.Struct({
+	mode: ReposInspectMode,
+	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
+});
+const REMEDIATION = { hint: "The vendored-repo state could not be read; check .repos/config.json and .gitmodules, and that git can run in the workspace." };
+/** The `repos_inspect` tool value. */
+const reposInspectTool = Tool.make("repos_inspect", {
+	description: "Read-only: drift report or parsed .repos/config.json manifest with orientation and notes. mode=status is the per-repo drift summary from ReposManager (present/dirty/commit); mode=config is the parsed manifest; mode=drift reconciles all four submodule authorities (manifest, .gitmodules, worktree, git submodule status) and reports every disagreement; mode=gitmodules decodes the raw .gitmodules file's submodule sections.",
+	parameters: ReposInspectParams,
+	success: ReposInspectResult,
+	failure: McpToolError,
+	dependencies: [
+		Repos.ReposManager,
+		Repos.ReposConfigStore,
+		Repos.ReposDrift,
+		WorkspaceRoot,
+		FileSystem.FileSystem,
+		Path.Path
+	]
+}).annotate(Tool.Title, "Inspect vendored repos").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(ReposInspectAsMarkdown));
+/** Wire handler: {@link reposInspect} with its error channel mapped onto {@link McpToolError}. */
+const handleReposInspect = (fallbackCwd, params) => reposInspect(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { ReposConfigResult, ReposDriftResult, ReposGitmodulesResult, ReposInspectAsMarkdown, ReposInspectResult, ReposStatusResult, reposInspect };
+export { ReposConfigResult, ReposDriftResult, ReposGitmodulesResult, ReposInspectAsMarkdown, ReposInspectMode, ReposInspectParams, ReposInspectResult, ReposStatusResult, handleReposInspect, reposInspect, reposInspectTool };

package/tools/repos-manage.js

@@ -1,7 +1,10 @@
+import { ENGINE_ECHO_LIMIT, McpToolError, invalidArgument, mapEngineError, truncateEchoed } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
 import { mdInline } from "./md-inline.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/repos-manage.ts
 /** `sync` has no extra fields. */
@@ -327,6 +330,59 @@ 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's markdown surfaces commitMessage and staleNoteIds — review and commit after pinning. The remove result's markdown 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's markdown surfaces commitMessage — review and commit after renaming. The restore result's markdown names exactly what was discarded. The deregister result's markdown lists the config keys the removed section carried — nothing to commit afterwards.",
+	parameters: ReposManageParams,
+	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).annotate(SilkMarkdown, Schema.decodeUnknownSync(ReposManageAsMarkdown));
+/**
+* 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 {@link ENGINE_ECHO_LIMIT}; the engine's own errors go
+* through {@link mapEngineError}.
+*/
+const handleReposManage = (fallbackCwd, params) => reposManage(params, fallbackCwd).pipe(Effect.mapError((error) => error._tag === "SchemaError" ? invalidArgument("action", `repos_manage ${params.action}: ${truncateEchoed(error.message, ENGINE_ECHO_LIMIT)}`, REQUEST_REMEDIATION) : mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)(error)));
 
 //#endregion
-export { ReposManageAddResult, ReposManageAsMarkdown, ReposManageDeregisterResult, ReposManageNoteResult, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, reposManage };
+export { ReposManageAddResult, ReposManageAsMarkdown, ReposManageDeregisterResult, ReposManageNoteResult, ReposManageParams, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, handleReposManage, reposManage, reposManageTool };

package/tools/turbo-inspect.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Turbo } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/turbo-inspect.ts
 /** Cache-diagnosis variant of the `turbo_inspect` result. */
@@ -104,6 +107,28 @@ const turboInspect = (args, fallbackCwd) => Effect.gen(function* () {
 		};
 	}
 });
+/** Wire parameters for `turbo_inspect`. */
+const TurboInspectParams = Schema.Struct({
+	mode: Schema.Literals([
+		"cache",
+		"graph",
+		"affected"
+	]).annotate({ description: "Which inspection to run." }),
+	task: Schema.optionalKey(Schema.String.annotate({ description: "Task name (defaults to build:dev for cache/graph)." })),
+	base: Schema.optionalKey(Schema.String.annotate({ description: "Base git ref for affected mode." })),
+	cwd: Schema.optionalKey(Schema.String.annotate({ description: "Directory to resolve the workspace root from." }))
+});
+const REMEDIATION = { hint: "turbo could not complete the dry run; check that the task exists in turbo.json and that turbo resolves from the workspace." };
+/** The `turbo_inspect` tool value. */
+const turboInspectTool = Tool.make("turbo_inspect", {
+	description: "Read-only Turborepo inspection. mode=cache diagnoses why a task's cache is hitting/missing (per-package status plus the exact hash contributors: input files, env vars, external-dep hashes, global hash). mode=graph returns the task graph and critical path. mode=affected lists changed packages and their dependents. Never executes tasks (uses --dry).",
+	parameters: TurboInspectParams,
+	success: TurboInspectResult,
+	failure: McpToolError,
+	dependencies: [Turbo.TurboInspector, WorkspaceRoot]
+}).annotate(Tool.Title, "Inspect Turborepo").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(TurboInspectAsMarkdown));
+/** Wire handler: {@link turboInspect} with its error channel mapped onto {@link McpToolError}. */
+const handleTurboInspect = (fallbackCwd, params) => turboInspect(params, fallbackCwd).pipe(Effect.mapError(mapEngineError(params.cwd ?? fallbackCwd, REMEDIATION)));
 
 //#endregion
-export { TurboAffectedResult, TurboCacheResult, TurboGraphResult, TurboInspectAsMarkdown, TurboInspectResult, turboInspect };
+export { TurboAffectedResult, TurboCacheResult, TurboGraphResult, TurboInspectAsMarkdown, TurboInspectParams, TurboInspectResult, handleTurboInspect, turboInspect, turboInspectTool };

package/tools/workspace-info.js

@@ -1,6 +1,9 @@
+import { McpToolError, mapEngineError } from "../errors.js";
+import { SilkMarkdown } from "../markdown.js";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { SilkWorkspaceAnalyzer } from "@savvy-web/silk-effects";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/workspace-info.ts
 /** A flattened, non-recursive summary of one analyzed workspace. */
@@ -93,6 +96,26 @@ const workspaceInfo = (base) => Effect.gen(function* () {
 	const analysis = yield* (yield* SilkWorkspaceAnalyzer).analyze(root);
 	return toWorkspaceInfoResult(analysis);
 });
+/** Wire parameters for `workspace_info`. */
+const WorkspaceInfoParams = Schema.Struct({ cwd: Schema.optionalKey(Schema.String.annotate({ description: "Workspace root to analyze. Defaults to the server's project dir." })) });
+const REMEDIATION = { hint: "The workspace could not be analyzed; check the manifest and lockfile at the root named in the message." };
+/**
+* The `workspace_info` tool value. `dependencies` names the two services the
+* handler yields so `Tool.HandlerServices` carries them (without it the
+* handler record fails against `Toolkit.HandlersFrom`).
+*/
+const workspaceInfoTool = Tool.make("workspace_info", {
+	description: "Use when you need the Silk workspace layout: runtime, package manager, and a per-workspace summary (publishability, versioning, tag/release state). Prefer this over running shell commands to inspect the workspace. Returns markdown in content[] and a typed object in structuredContent.",
+	parameters: WorkspaceInfoParams,
+	success: WorkspaceInfoResult,
+	failure: McpToolError,
+	dependencies: [SilkWorkspaceAnalyzer, WorkspaceRoot]
+}).annotate(Tool.Title, "Workspace info").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false).annotate(SilkMarkdown, Schema.decodeUnknownSync(WorkspaceInfoAsMarkdown));
+/** Wire handler: the existing {@link workspaceInfo} program with its error channel mapped onto {@link McpToolError}. */
+const handleWorkspaceInfo = (fallbackCwd, params) => {
+	const cwd = params.cwd ?? fallbackCwd;
+	return workspaceInfo(cwd).pipe(Effect.mapError(mapEngineError(cwd, REMEDIATION)));
+};
 
 //#endregion
-export { WorkspaceInfoAsMarkdown, WorkspaceInfoResult, WorkspaceSummary, formatWorkspaceInfoMarkdown, toWorkspaceInfoResult, workspaceInfo };
+export { WorkspaceInfoAsMarkdown, WorkspaceInfoParams, WorkspaceInfoResult, WorkspaceSummary, formatWorkspaceInfoMarkdown, handleWorkspaceInfo, toWorkspaceInfoResult, workspaceInfo, workspaceInfoTool };

package/version.js

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