@savvy-web/mcp 3.2.3 → 3.3.0

package/tools/changeset-validate.js

@@ -1,6 +1,6 @@
-import { McpToolError, invalidArgument, mapEngineError, truncateEchoed } from "../errors.js";
-import { SilkMarkdown } from "../markdown.js";
-import { Data, Effect, Schema, SchemaGetter } from "effect";
+import { McpToolError, invalidArgument, mapEngineError } from "../errors.js";
+import { ToolFailure } from "@effected/mcp";
+import { Data, Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Changesets } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -36,29 +36,6 @@ const ChangesetValidateResult = Schema.Struct({
 	description: "Read-only validation of changeset files against the section-aware rules."
 });
 /**
-* Render a repo/lint-derived value as an inert markdown code span. Escapes
-* backticks and backslashes so a crafted filename or message cannot inject
-* markdown structure into the transcript that an agent reads.
-*/
-const mdInline = (value) => `\`${value.replace(/[`\\]/g, "\\$&")}\``;
-/** Render the structured result as a markdown transcript. */
-const renderMarkdown = (data) => {
-	if (data.ok) return `# changeset validate — ${mdInline(data.dir)}\n\nNo changeset issues found.`;
-	const lines = [
-		`# changeset validate — ${mdInline(data.dir)}`,
-		``,
-		`${data.errorCount} issue(s):`,
-		``
-	];
-	for (const m of data.messages) lines.push(`- ${mdInline(`${m.file}:${m.line}:${m.column}`)} ${mdInline(m.rule)} — ${m.message}`);
-	return lines.join("\n");
-};
-/** One-way transform: result to markdown. Encoding back is forbidden. */
-const ChangesetValidateAsMarkdown = ChangesetValidateResult.pipe(Schema.decodeTo(Schema.String, {
-	decode: SchemaGetter.transform(renderMarkdown),
-	encode: SchemaGetter.forbidden(() => "ChangesetValidateAsMarkdown is one-way: markdown cannot be parsed back.")
-}));
-/**
 * Effect handler: resolve the workspace root, then validate the changeset
 * directory via the pure {@link Changesets.ChangesetLinter.validate}. The
 * synchronous call is wrapped in {@link Effect.try} so a thrown error (e.g. a
@@ -90,12 +67,12 @@ const ChangesetValidateParams = Schema.Struct({
 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.",
+	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. Returns a typed object in structuredContent (content[] carries the same object as JSON).",
 	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));
+}).annotate(Tool.Title, "Validate changesets").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
 /**
 * Wire handler: {@link changesetValidate} with its error channel mapped onto
 * {@link McpToolError}. The typed {@link ChangesetValidateError} (a thrown
@@ -103,8 +80,8 @@ const changesetValidateTool = Tool.make("changeset_validate", {
 * 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));
+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 describeCause = (cause) => cause instanceof Error ? ToolFailure.truncate(cause.message) : ToolFailure.truncate(String(cause));
 
 //#endregion
-export { ChangesetLintMessage, ChangesetValidateAsMarkdown, ChangesetValidateError, ChangesetValidateParams, ChangesetValidateResult, changesetValidate, changesetValidateTool, handleChangesetValidate };
+export { ChangesetLintMessage, ChangesetValidateError, ChangesetValidateParams, ChangesetValidateResult, changesetValidate, changesetValidateTool, handleChangesetValidate };

package/tools/repos-inspect.js

@@ -1,7 +1,5 @@
 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 { Effect, FileSystem, Option, Path, Result, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -11,8 +9,7 @@ import { Gitmodules } from "@effected/git";
 /**
 * The `repos_inspect` MCP tool: a discriminated-union result keyed by `mode`
 * (status | config), each variant embedding the corresponding resolved-output
-* schema from silk-effects' Repos namespace, plus a one-way markdown
-* transform. Read-only.
+* schema from silk-effects' Repos namespace. Read-only.
 *
 * @packageDocumentation
 */
@@ -64,81 +61,6 @@ const ReposInspectResult = Schema.Union([
 	title: "repos_inspect result",
 	description: "Drift report (status), the parsed manifest (config), the five-authority reconciliation report (drift), or the decoded .gitmodules sections (gitmodules)."
 });
-/** Render the structured result as a markdown transcript. */
-const renderMarkdown = (data) => {
-	switch (data.mode) {
-		case "status": {
-			const r = data.result;
-			const lines = [
-				`# repos status`,
-				``,
-				`clean: ${r.clean}`,
-				``,
-				`## Repos`
-			];
-			for (const entry of r.repos) {
-				lines.push(`### ${mdInline(entry.name)}`, `- ref: ${mdInline(entry.ref)}`, `- purpose: ${mdInline(entry.purpose)}`, `- present: ${entry.present}`, `- stagedCommit: ${entry.stagedCommit ? mdInline(entry.stagedCommit) : "(none)"}`, `- committedCommit: ${entry.committedCommit ? mdInline(entry.committedCommit) : "(none)"}`, `- checkedOutCommit: ${entry.checkedOutCommit ? mdInline(entry.checkedOutCommit) : "(none)"}`, `- dirty: ${entry.dirty}`);
-				if (entry.staleNoteIds.length > 0) lines.push(`- staleNoteIds: ${entry.staleNoteIds.map(mdInline).join(", ")}`);
-			}
-			if (r.repos.length === 0) lines.push("(none)");
-			return lines.join("\n");
-		}
-		case "config": {
-			const r = data.result;
-			const lines = [
-				`# repos config`,
-				``,
-				`## Repos`
-			];
-			for (const [name, entry] of Object.entries(r.repos)) {
-				lines.push(`### ${mdInline(name)}`, `- url: ${mdInline(entry.url)}`, `- ref: ${mdInline(entry.ref)}`, `- purpose: ${mdInline(entry.purpose)}`);
-				if (entry.sparse && entry.sparse.length > 0) lines.push(`- sparse: ${entry.sparse.map(mdInline).join(", ")}`);
-				if (entry.orientation) {
-					const o = entry.orientation;
-					if (o.layout) lines.push(`- layout: ${mdInline(o.layout)}`);
-					if (o.startHere) lines.push(`- startHere: ${mdInline(o.startHere)}`);
-					if (o.keyPaths) {
-						lines.push(`- keyPaths:`);
-						for (const [key, value] of Object.entries(o.keyPaths)) lines.push(`  - ${mdInline(key)}: ${mdInline(value)}`);
-					}
-				}
-				if (entry.notes && entry.notes.length > 0) {
-					lines.push(`- notes:`);
-					for (const note of entry.notes) lines.push(`  - ${mdInline(note.id)} (${mdInline(note.date)}, ref ${mdInline(note.ref)}): ${mdInline(note.note)}`);
-				}
-			}
-			if (Object.keys(r.repos).length === 0) lines.push("(none)");
-			return lines.join("\n");
-		}
-		case "drift": {
-			const r = data.report;
-			const lines = [
-				`# repos drift`,
-				``,
-				`clean: ${r.clean}`,
-				``,
-				`| name | kind | detail |`,
-				`| --- | --- | --- |`
-			];
-			for (const d of r.drifts) lines.push(`| ${mdInline(d.name)} | ${mdInline(d.kind)} | ${mdInline(d.detail)} |`);
-			if (r.drifts.length === 0) lines.push(``, `(none)`);
-			return lines.join("\n");
-		}
-		case "gitmodules": {
-			const lines = [`# repos gitmodules`, ``];
-			if (data.parseError) lines.push(`parse error: ${mdInline(data.parseError)}`, ``);
-			lines.push(`| name | path | url | branch | shallow |`, `| --- | --- | --- | --- | --- |`);
-			for (const entry of data.entries) lines.push(`| ${mdInline(entry.name)} | ${mdInline(entry.path)} | ${mdInline(entry.url)} | ${entry.branch === void 0 ? "(none)" : mdInline(entry.branch)} | ${entry.shallow === void 0 ? "(unset)" : entry.shallow} |`);
-			if (data.entries.length === 0) lines.push(``, `(none)`);
-			return lines.join("\n");
-		}
-	}
-};
-/** One-way transform: result to markdown. Encoding back is forbidden. */
-const ReposInspectAsMarkdown = ReposInspectResult.pipe(Schema.decodeTo(Schema.String, {
-	decode: SchemaGetter.transform(renderMarkdown),
-	encode: SchemaGetter.forbidden(() => "ReposInspectAsMarkdown is one-way: markdown cannot be parsed back.")
-}));
 /**
 * Effect handler: resolve the workspace root, then dispatch to the matching
 * Repos service keyed by `mode`. Mirrors `changesetInspect`.
@@ -207,7 +129,7 @@ const ReposInspectParams = Schema.Struct({
 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.",
+	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. Returns a typed object in structuredContent (content[] carries the same object as JSON).",
 	parameters: ReposInspectParams,
 	success: ReposInspectResult,
 	failure: McpToolError,
@@ -219,9 +141,9 @@ const reposInspectTool = Tool.make("repos_inspect", {
 		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));
+}).annotate(Tool.Title, "Inspect vendored repos").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
 /** 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, ReposInspectMode, ReposInspectParams, ReposInspectResult, ReposStatusResult, handleReposInspect, reposInspect, reposInspectTool };
+export { ReposConfigResult, ReposDriftResult, ReposGitmodulesResult, ReposInspectMode, ReposInspectParams, ReposInspectResult, ReposStatusResult, handleReposInspect, reposInspect, reposInspectTool };

package/tools/repos-manage.js

@@ -1,12 +1,21 @@
-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 { McpToolError, invalidArgument, mapEngineError } from "../errors.js";
+import { ToolFailure } from "@effected/mcp";
+import { Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Repos } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
 
 //#region src/tools/repos-manage.ts
+/**
+* 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`.
+*
+* @packageDocumentation
+*/
 /** `sync` has no extra fields. */
 const SyncRequest = Schema.TaggedStruct("sync", {});
 /** `pin` requires both `name` and `ref`. */
@@ -129,139 +138,6 @@ const ReposManageResult = Schema.Union([
 	title: "repos_manage result",
 	description: "Result of a mutating repos action: sync, pin, add, note, remove, rename, restore, or deregister."
 });
-/** Render the structured result as a markdown transcript. */
-const renderMarkdown = (data) => {
-	switch (data.action) {
-		case "sync": {
-			const r = data.result;
-			const section = (title, names) => [`## ${title}`, ...names.length > 0 ? names.map((name) => `- ${mdInline(name)}`) : ["(none)"]];
-			return [
-				`# repos sync`,
-				``,
-				...section("Initialized", r.initialized),
-				``,
-				...section("Sparse applied", r.sparseApplied),
-				``,
-				...section("Up to date", r.upToDate),
-				``,
-				...section("Cleared locks", r.clearedLocks),
-				``,
-				...section("URL synced", r.urlSynced),
-				``,
-				...section("Registered", r.registered),
-				``,
-				...section("Boundary marked", r.boundaryMarked)
-			].join("\n");
-		}
-		case "pin": {
-			const r = data.result;
-			const lines = [
-				`# repos pin — ${mdInline(r.name)}`,
-				``,
-				`ref: ${mdInline(r.ref)}`,
-				`oldCommit: ${r.oldCommit ? mdInline(r.oldCommit) : "(none)"}`,
-				`newCommit: ${mdInline(r.newCommit)}`,
-				``,
-				`## Commit message`,
-				``,
-				mdInline(r.commitMessage),
-				``,
-				`## Stale notes`,
-				``
-			];
-			if (r.staleNoteIds.length > 0) lines.push(`These notes reference a ref other than the new pin and should be reviewed before committing:`, ...r.staleNoteIds.map((id) => `- ${mdInline(id)}`));
-			else lines.push("(none)");
-			lines.push(``, `REVIEW AND COMMIT: stage the updated manifest and submodule gitlink, then commit using the message above.`);
-			return lines.join("\n");
-		}
-		case "add": {
-			const r = data.result;
-			return [
-				`# repos add — ${mdInline(r.name)}`,
-				``,
-				`ref: ${mdInline(r.ref)}`,
-				`path: ${mdInline(r.path)}`
-			].join("\n");
-		}
-		case "note": {
-			const r = data.result;
-			return [
-				`# repos note — ${mdInline(r.name)}`,
-				``,
-				`op: ${mdInline(r.op)}`,
-				`id: ${mdInline(r.id)}`,
-				`noteCount: ${r.noteCount}`
-			].join("\n");
-		}
-		case "remove": {
-			const r = data.result;
-			const lines = [
-				`# repos remove — ${mdInline(r.name)}`,
-				``,
-				`path: ${mdInline(r.path)}`,
-				``,
-				`## Commit message`,
-				``,
-				mdInline(r.commitMessage),
-				``,
-				`## Removed notes`,
-				``
-			];
-			if (r.removedNotes.length > 0) lines.push(`Promote any durable ones elsewhere before committing:`, ...r.removedNotes.map((note) => `- ${mdInline(note.id)} (${mdInline(note.ref)}): ${mdInline(note.note)}`));
-			else lines.push("(none)");
-			if (r.removedEntry.orientation) lines.push(``, `## Removed orientation`, ``, `\`add\` does NOT restore this. If you are re-vendoring ${mdInline(r.name)}, pass it back as the \`orientation\` argument:`, ``, "```json", JSON.stringify(r.removedEntry.orientation, null, 2), "```");
-			lines.push(``, `REVIEW AND COMMIT: the manifest, .gitmodules, and gitlink removal are already staged — review and commit using the message above.`);
-			return lines.join("\n");
-		}
-		case "rename": {
-			const r = data.result;
-			return [
-				`# repos rename — ${mdInline(r.oldName)} → ${mdInline(r.newName)}`,
-				``,
-				`path: ${mdInline(r.path)}`,
-				``,
-				`## Commit message`,
-				``,
-				mdInline(r.commitMessage),
-				``,
-				`REVIEW AND COMMIT: the moved worktree, .gitmodules section, and manifest key are already staged — review and commit using the message above.`
-			].join("\n");
-		}
-		case "restore": {
-			const r = data.result;
-			const lines = [
-				`# repos restore`,
-				``,
-				`## Restored`,
-				``
-			];
-			if (r.restored.length > 0) lines.push(`DESTRUCTIVE: any uncommitted worktree edits and untracked files in these repos were discarded — the working tree was hard-reset to the commit below and sparse paths re-applied.`, ``, ...r.restored.map((entry) => `- ${mdInline(entry.name)} → ${mdInline(entry.commit)}`));
-			else lines.push("(none)");
-			lines.push(``, `## Skipped (clean)`, ``);
-			if (r.skippedClean.length > 0) lines.push(...r.skippedClean.map((name) => `- ${mdInline(name)}`));
-			else lines.push("(none)");
-			if (r.stillDirty.length > 0) lines.push(``, `## Still dirty — RESTORE DID NOT FULLY SUCCEED`, ``, `The reset ran but these worktrees remain dirty, so treat the restore as incomplete rather than done:`, ``, ...r.stillDirty.map((name) => `- ${mdInline(name)}`), ``, `Run repos_inspect (mode: drift) — a nestedSubmoduleDivergence or a permission problem is the usual cause.`);
-			return lines.join("\n");
-		}
-		case "deregister": {
-			const r = data.result;
-			return [
-				`# repos deregister — ${mdInline(r.section)}`,
-				``,
-				`Removed the stale ${mdInline(`submodule.${r.section}`)} section from the superproject's LOCAL git config. Keys cleared:`,
-				``,
-				...r.removedKeys.map((key) => `- ${mdInline(key)}`),
-				``,
-				`Local config only — nothing is staged and there is nothing to commit.`
-			].join("\n");
-		}
-	}
-};
-/** One-way transform: result to markdown. Encoding back is forbidden. */
-const ReposManageAsMarkdown = ReposManageResult.pipe(Schema.decodeTo(Schema.String, {
-	decode: SchemaGetter.transform(renderMarkdown),
-	encode: SchemaGetter.forbidden(() => "ReposManageAsMarkdown is one-way: markdown cannot be parsed back.")
-}));
 /**
 * Effect handler: resolve the workspace root, decode the flat wire args into
 * the internal per-action request (naming the missing field on failure), then
@@ -368,21 +244,21 @@ const REMEDIATION = {
 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.",
+	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,
 	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));
+}).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 {@link ENGINE_ECHO_LIMIT}; the engine's own errors go
+* truncated at `ToolFailure.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)));
+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)));
 
 //#endregion
-export { ReposManageAddResult, ReposManageAsMarkdown, ReposManageDeregisterResult, ReposManageNoteResult, ReposManageParams, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, handleReposManage, reposManage, reposManageTool };
+export { ReposManageAddResult, ReposManageDeregisterResult, ReposManageNoteResult, ReposManageParams, ReposManagePinResult, ReposManageRemoveResult, ReposManageRenameResult, ReposManageRestoreResult, ReposManageResult, ReposManageSyncResult, handleReposManage, reposManage, reposManageTool };

package/tools/turbo-inspect.js

@@ -1,6 +1,5 @@
 import { McpToolError, mapEngineError } from "../errors.js";
-import { SilkMarkdown } from "../markdown.js";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { Turbo } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -31,59 +30,6 @@ const TurboInspectResult = Schema.Union([
 	title: "turbo_inspect result",
 	description: "Read-only Turborepo inspection grouped by mode (cache | graph | affected)."
 });
-/** Render the structured result as a markdown transcript. */
-const renderMarkdown = (data) => {
-	switch (data.mode) {
-		case "cache": {
-			const r = data.result;
-			const lines = [
-				`# turbo cache — ${r.task}`,
-				``,
-				`**${r.hits}/${r.totalTasks} cached**, ${r.misses} miss(es).`,
-				``,
-				`## Global hash`,
-				`- rootKey: \`${r.global.rootKey}\``,
-				`- global files: ${r.global.globalFileCount}`,
-				`- external deps hash: \`${r.global.externalDependenciesHash}\``,
-				`- internal deps hash: \`${r.global.internalDependenciesHash}\``,
-				`- global env: ${r.global.globalEnvVars.join(", ") || "(none)"}`
-			];
-			if (r.explanations.length > 0) {
-				lines.push(``, `## Misses`);
-				for (const m of r.explanations) lines.push(`### ${m.package} (\`${m.taskId}\`)`, `- hash: \`${m.hash}\``, `- input files: ${m.inputFileCount}`, `- hashed env: ${m.hashedEnvVars.join(", ") || "(none)"}`, `- external deps hash: \`${m.externalDependenciesHash}\``, `- depends on: ${m.dependsOn.join(", ") || "(none)"}`);
-			}
-			return lines.join("\n");
-		}
-		case "graph": {
-			const r = data.result;
-			return [
-				`# turbo task graph${r.task ? ` — ${r.task}` : ""}`,
-				``,
-				`${r.nodeCount} task node(s).`,
-				``,
-				`## Critical path`,
-				r.criticalPath.map((id, i) => `${i + 1}. \`${id}\``).join("\n") || "(empty)"
-			].join("\n");
-		}
-		case "affected": {
-			const r = data.result;
-			return [
-				`# turbo affected — base ${r.base}`,
-				``,
-				`## Changed packages`,
-				r.packages.map((p) => `- ${p}`).join("\n") || "(none)",
-				``,
-				`## Dependents`,
-				r.dependents.map((p) => `- ${p}`).join("\n") || "(none)"
-			].join("\n");
-		}
-	}
-};
-/** One-way transform: result to markdown. Encoding back is forbidden. */
-const TurboInspectAsMarkdown = TurboInspectResult.pipe(Schema.decodeTo(Schema.String, {
-	decode: SchemaGetter.transform(renderMarkdown),
-	encode: SchemaGetter.forbidden(() => "TurboInspectAsMarkdown is one-way: markdown cannot be parsed back.")
-}));
 /**
 * Effect handler: resolve the workspace root by walking up from the requested
 * directory, then dispatch to the matching {@link Turbo.TurboInspector} method
@@ -121,14 +67,14 @@ const TurboInspectParams = Schema.Struct({
 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).",
+	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). Returns a typed object in structuredContent (content[] carries the same object as JSON).",
 	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));
+}).annotate(Tool.Title, "Inspect Turborepo").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
 /** 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, TurboInspectParams, TurboInspectResult, handleTurboInspect, turboInspect, turboInspectTool };
+export { TurboAffectedResult, TurboCacheResult, TurboGraphResult, TurboInspectParams, TurboInspectResult, handleTurboInspect, turboInspect, turboInspectTool };

package/tools/workspace-info.js

@@ -1,6 +1,5 @@
 import { McpToolError, mapEngineError } from "../errors.js";
-import { SilkMarkdown } from "../markdown.js";
-import { Effect, Schema, SchemaGetter } from "effect";
+import { Effect, Schema } from "effect";
 import { WorkspaceRoot } from "@effected/workspaces";
 import { SilkWorkspaceAnalyzer } from "@savvy-web/silk-effects";
 import { Tool } from "effect/unstable/ai";
@@ -65,27 +64,6 @@ const toWorkspaceInfoResult = (analysis) => ({
 	workspaceCount: analysis.workspaces.length,
 	workspaces: analysis.workspaces.map(toSummary)
 });
-/** Render the structured result as a markdown transcript. */
-const formatWorkspaceInfoMarkdown = (data) => {
-	const pm = data.packageManager.version ? `${data.packageManager.type}@${data.packageManager.version}` : data.packageManager.type;
-	const lines = [
-		`# Workspace: ${data.root}`,
-		"",
-		`- runtime: ${data.runtime}`,
-		`- package manager: ${pm}`,
-		`- workspaces: ${data.workspaceCount}`,
-		"",
-		"| name | version | publishable | versioned | tagged | released |",
-		"| --- | --- | --- | --- | --- | --- |"
-	];
-	for (const w of data.workspaces) lines.push(`| ${w.name} | ${w.version ?? "—"} | ${w.publishable} | ${w.versioned} | ${w.tagged} | ${w.released} |`);
-	return lines.join("\n");
-};
-/** One-way transform: result to markdown. Encoding back is forbidden. */
-const WorkspaceInfoAsMarkdown = WorkspaceInfoResult.pipe(Schema.decodeTo(Schema.String, {
-	decode: SchemaGetter.transform(formatWorkspaceInfoMarkdown),
-	encode: SchemaGetter.forbidden(() => "WorkspaceInfoAsMarkdown is one-way: markdown cannot be parsed back.")
-}));
 /**
 * Effect handler: resolve the workspace root by walking up from `base`, analyze
 * that root, and project to the tool result. Fails with `WorkspaceRootNotFoundError`
@@ -105,12 +83,12 @@ const REMEDIATION = { hint: "The workspace could not be analyzed; check the mani
 * 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.",
+	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 a typed object in structuredContent (content[] carries the same object as JSON).",
 	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));
+}).annotate(Tool.Title, "Workspace info").annotate(Tool.Readonly, true).annotate(Tool.Destructive, false).annotate(Tool.Idempotent, true).annotate(Tool.OpenWorld, false);
 /** Wire handler: the existing {@link workspaceInfo} program with its error channel mapped onto {@link McpToolError}. */
 const handleWorkspaceInfo = (fallbackCwd, params) => {
 	const cwd = params.cwd ?? fallbackCwd;
@@ -118,4 +96,4 @@ const handleWorkspaceInfo = (fallbackCwd, params) => {
 };
 
 //#endregion
-export { WorkspaceInfoAsMarkdown, WorkspaceInfoParams, WorkspaceInfoResult, WorkspaceSummary, formatWorkspaceInfoMarkdown, handleWorkspaceInfo, toWorkspaceInfoResult, workspaceInfo, workspaceInfoTool };
+export { WorkspaceInfoParams, WorkspaceInfoResult, WorkspaceSummary, handleWorkspaceInfo, toWorkspaceInfoResult, workspaceInfo, workspaceInfoTool };

package/version.js

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

package/internal/project-root.js

@@ -1,25 +0,0 @@
-//#region src/internal/project-root.ts
-/**
-* Pure resolution of the MCP server's project working directory.
-*
-* @packageDocumentation
-*/
-/**
-* Resolves the project directory the MCP server should root its runtime in.
-*
-* @remarks
-* Precedence: a non-empty, non-placeholder `argv[0]`, then
-* `env.SAVVY_MCP_PROJECT_DIR`, then `env.CLAUDE_PROJECT_DIR`, then `cwd()`. A
-* `${...}`-shaped `argv[0]` is an unresolved template placeholder (an MCP
-* client that failed to substitute a config variable) and is ignored, as is
-* a whitespace-only value. Takes `argv`/`env`/`cwd` as parameters rather than
-* reading `process` directly so it stays pure and unit-testable; `main.ts` is
-* the sole caller and supplies the real process bindings.
-*/
-function resolveProjectDir(argv, env, cwd) {
-	const trimmed = argv[0]?.trim();
-	return (trimmed !== void 0 && trimmed.length > 0 && !(trimmed.startsWith("${") && trimmed.endsWith("}")) ? trimmed : void 0) ?? env.SAVVY_MCP_PROJECT_DIR ?? env.CLAUDE_PROJECT_DIR ?? cwd();
-}
-
-//#endregion
-export { resolveProjectDir };

package/markdown.js

@@ -1,33 +0,0 @@
-import { Context } from "effect";
-
-//#region src/markdown.ts
-/**
-* The tool annotation that carries each tool's markdown transcript renderer
-* to the server's registration step.
-*
-* @remarks
-* rc.116's `McpServer.registerToolkit` renders every success as
-* `content: [{ type: "text", text: JSON.stringify(encodedResult) }]` plus
-* `structuredContent` and offers no hook over the text
-* (`unstable/ai/McpServer.ts`, `toolResultContent`; Effect-TS/effect#8316
-* proposes one). `server.ts` therefore registers the
-* toolkit itself through the public `McpServer.addTool` and reads this
-* annotation to put the tool's markdown projection in `content[0].text`
-* while `structuredContent` stays the typed object — the dual channel every
-* tool description promises. A tool without the annotation falls back to the
-* framework's JSON text.
-*
-* @packageDocumentation
-*/
-/**
-* Renders a tool's decoded success value as the markdown transcript an agent
-* reads. Typed over `unknown` because the annotation is read generically at
-* registration; each tool supplies `Schema.decodeUnknownSync(<X>AsMarkdown)`,
-* whose own decoder is the type guard.
-*
-* @public
-*/
-var SilkMarkdown = class extends Context.Service()("@savvy-web/mcp/SilkMarkdown") {};
-
-//#endregion
-export { SilkMarkdown };

package/tools/md-inline.js

@@ -1,22 +0,0 @@
-//#region src/tools/md-inline.ts
-/**
-* Render a repo-derived value as an inert markdown code span. Backslash
-* escaping does NOT work inside code spans (CommonMark treats backslashes
-* literally there), so this uses the delimiter-run rule instead: wrap the
-* value in a backtick run strictly longer than any backtick run it contains,
-* padding with spaces when the value starts or ends with a backtick. This
-* keeps vendored-repo content (names, refs, purposes, orientation values,
-* commit messages, note text) — the definition of untrusted input — from
-* injecting markdown structure into the transcript an agent reads.
-*
-* Shared by every tool that interpolates untrusted repo content into a
-* markdown transcript so the escaping rule has exactly one implementation.
-*/
-const mdInline = (value) => {
-	const runs = value.match(/`+/g) ?? [];
-	const delimiter = "`".repeat(Math.max(1, ...runs.map((run) => run.length + 1)));
-	return `${delimiter}${value.startsWith("`") || value.endsWith("`") ? ` ${value} ` : value}${delimiter}`;
-};
-
-//#endregion
-export { mdInline };