zidane 6.6.3 → 7.0.0

package/dist/src-DzzhE2YO.js

@@ -0,0 +1,2461 @@
+import { t as defineSkill } from "./skills-PJyiSRCp.js";
+import { h as McpOAuthProvider, m as sseToJsonFetchIfNeeded, o as expandMcpConfigEnv, p as createTolerantClient, v as isOAuthTokenRejectionError } from "./mcp-BIWa57eY.js";
+import { createRequire } from "node:module";
+import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { homedir } from "node:os";
+import { createServer } from "node:http";
+//#region src/behaviors/local-reliability.ts
+const DEFAULT_LOCAL_RELIABILITY = {
+	maxConcurrentTools: 3,
+	readFileDefaults: {
+		limit: 400,
+		maxBytes: 64 * 1024
+	},
+	toolOutputBudget: 32 * 1024,
+	textToolCallRescue: { mode: "steer" },
+	thinkingOverrunPolicy: {
+		mode: "steer-next-turn",
+		thresholdTokens: 2048
+	}
+};
+/**
+* Opt-in behavior overlay for brittle/local OpenAI-compatible endpoints.
+* Returns plain `AgentBehavior` so hosts can spread it before or after their
+* own overrides; no built-in profile uses this helper by default.
+*/
+function localReliabilityBehavior(overrides = {}) {
+	return {
+		...DEFAULT_LOCAL_RELIABILITY,
+		...overrides,
+		readFileDefaults: {
+			...DEFAULT_LOCAL_RELIABILITY.readFileDefaults,
+			...overrides.readFileDefaults ?? {}
+		},
+		textToolCallRescue: overrides.textToolCallRescue ?? DEFAULT_LOCAL_RELIABILITY.textToolCallRescue,
+		thinkingOverrunPolicy: overrides.thinkingOverrunPolicy ?? DEFAULT_LOCAL_RELIABILITY.thinkingOverrunPolicy
+	};
+}
+//#endregion
+//#region src/chat/commands.ts
+/**
+* Persisted form of output blocks inside a display-only `command` turn:
+* plain blocks → `text` content; `detail` blocks → `tool_result` content
+* with the label/syntax carried in namespaced metadata (rebuilt into the
+* collapsed rendering on reload). Shared by the command emit flush and
+* `ctx.appendNote` so both persist identically.
+*/
+function commandBlocksToContent(blocks) {
+	return blocks.map((block) => {
+		if (!block.detail && !block.custom) return {
+			type: "text",
+			text: block.text
+		};
+		const commandMeta = block.custom ? { custom: {
+			renderer: block.custom.renderer,
+			...block.custom.data !== void 0 ? { data: block.custom.data } : {}
+		} } : {
+			...block.detail?.label ? { label: block.detail.label } : {},
+			...block.detail?.syntax ? { syntax: block.detail.syntax } : {}
+		};
+		return {
+			type: "tool_result",
+			callId: `command_detail_${crypto.randomUUID()}`,
+			output: block.text,
+			...Object.keys(commandMeta).length > 0 ? { metadata: { command: commandMeta } } : {}
+		};
+	});
+}
+/**
+* Map ONE command-output block to its LIVE transcript event — the
+* in-memory mirror of {@link commandBlocksToContent}'s persisted shape
+* (whose replay side lives in `eventsFromTurns`). One definition shared
+* by the command emit flush and the `ctx.appendNote` host impl so live
+* rendering can never drift from reloaded rendering — the exact drift
+* that shipped `custom` blocks rendering only after a reload.
+*
+* Precedence matches the persisted side: `custom` > `detail` > markdown.
+*/
+function commandBlockToEvent(block) {
+	if (block.custom) return {
+		kind: "custom",
+		text: block.text,
+		custom: {
+			renderer: block.custom.renderer,
+			...block.custom.data !== void 0 ? { data: block.custom.data } : {}
+		}
+	};
+	if (block.detail) return {
+		kind: "command-detail",
+		text: block.text,
+		...block.detail.label ? { label: block.detail.label } : {},
+		...block.detail.syntax ? { syntax: block.detail.syntax } : {}
+	};
+	return {
+		kind: "markdown",
+		text: block.text,
+		streaming: false
+	};
+}
+/** Normalize a command to its ordered step list (`steps` wins over `run`). */
+function commandSteps(command) {
+	if (command.steps && command.steps.length > 0) return command.steps;
+	if (command.run) return [{ run: command.run }];
+	return [];
+}
+/**
+* Parse a prompt as a command invocation, but only when the command token is
+* the LEADING token of the whole prompt and names a known command. This is
+* what keeps mid-prompt `/skill` mentions routed to the skills provider:
+* `"summarize /research"` is not a command, `"/research foo"` is.
+*
+* `known` is matched case-insensitively; entries may be bare names or
+* `{ name, aliases }` records — an alias hit canonicalizes to the entry's
+* `name` (registered casing), so dispatch-by-name downstream just works.
+*/
+function parseCommandInvocation(prompt, known) {
+	const body = prompt.trimStart();
+	if (body[0] !== "/") return null;
+	const afterSlash = body.slice(1);
+	const wsIdx = afterSlash.search(/\s/);
+	const typed = (wsIdx === -1 ? afterSlash : afterSlash.slice(0, wsIdx)).toLowerCase();
+	if (typed.length === 0) return null;
+	let canonical;
+	for (const entry of known) {
+		const name = typeof entry === "string" ? entry : entry.name;
+		if (name.toLowerCase() === typed) {
+			canonical = name;
+			break;
+		}
+		if (typeof entry !== "string" && entry.aliases?.some((a) => a.toLowerCase() === typed)) {
+			canonical = name;
+			break;
+		}
+	}
+	if (canonical === void 0) return null;
+	const args = (wsIdx === -1 ? "" : afterSlash.slice(wsIdx + 1)).trim();
+	return {
+		name: canonical,
+		invokedAs: typed,
+		args,
+		argv: args.length > 0 ? args.split(/\s+/) : []
+	};
+}
+/**
+* Run a command's steps in order, threading `ctx.data`. Stops at the first
+* step that throws (error isolated + returned, not rethrown) or when the
+* signal aborts. Pure orchestration — all I/O lives in the host-supplied
+* `ctx` capabilities.
+*/
+async function executeCommand(command, ctx) {
+	const steps = commandSteps(command);
+	let ranSteps = 0;
+	for (const step of steps) {
+		if (ctx.signal.aborted) return {
+			ok: false,
+			ranSteps,
+			aborted: true
+		};
+		ranSteps++;
+		try {
+			const result = await step.run(ctx);
+			if (result && result.data) Object.assign(ctx.data, result.data);
+		} catch (error) {
+			if (ctx.signal.aborted) return {
+				ok: false,
+				ranSteps,
+				aborted: true
+			};
+			return {
+				ok: false,
+				ranSteps,
+				error
+			};
+		}
+	}
+	return {
+		ok: true,
+		ranSteps
+	};
+}
+//#endregion
+//#region src/zod.ts
+function isStandardSchema(value) {
+	if (typeof value !== "object" || value === null) return false;
+	const marker = value["~standard"];
+	return typeof marker === "object" && marker !== null && typeof marker.vendor === "string";
+}
+/**
+* Resolve a {@link SchemaInput} to the plain JSON Schema object providers
+* expect. Zod schemas convert via the lazily-imported `z.toJSONSchema`
+* (v4 native); other Standard Schema vendors are rejected with a clear
+* error — conversion is vendor-specific and only zod is wired today.
+*/
+async function resolveSchemaInput(schema) {
+	if (!isStandardSchema(schema)) return schema;
+	const vendor = schema["~standard"].vendor;
+	if (vendor !== "zod") throw new Error(`unsupported schema vendor "${vendor}" — pass a zod v4 schema or a plain JSON Schema object`);
+	let toJSONSchema;
+	try {
+		toJSONSchema = (await import("zod")).z.toJSONSchema;
+	} catch {
+		throw new Error("a zod schema was passed but the \"zod\" package could not be imported — install zod >= 4");
+	}
+	return zodToJsonSchema(toJSONSchema(schema));
+}
+/**
+* Normalize a JSON Schema (e.g. from zod v4's z.toJSONSchema()) for use
+* as a ToolSpec.inputSchema.
+*
+* Strips the $schema key that some providers reject.
+*/
+function zodToJsonSchema(jsonSchema) {
+	const { $schema, ...rest } = jsonSchema;
+	return rest;
+}
+//#endregion
+//#region src/chat/generate-title.ts
+/** Hard cap on the result length. Anything longer is truncated client-side. */
+const TITLE_MAX_CHARS = 60;
+/** Default turn count fed to the model. 10 covers most exchanges without bloat. */
+const DEFAULT_MAX_TURNS = 10;
+/** Tokens budgeted for the model's reply. 64 fits any sane title with headroom. */
+const TITLE_RESPONSE_MAX_TOKENS = 64;
+/** Per-turn body cap when assembling the prompt — keeps the request payload tight. */
+const PROMPT_TURN_CHAR_MAX = 2e3;
+/**
+* System prompt for the titling call.
+*
+* Written as a LABELING task, not a chat turn: handed a bare "generate a
+* title for this conversation" instruction with the transcript inline, a
+* cheap model reads the trailing assistant message and just keeps
+* talking — observed in the wild as a session titled `I don't have a
+* "plan tool" available in this conversation…`, i.e. the model answering
+* the last user turn instead of naming it. The rules below say what the
+* model IS (an annotator, not a participant), and the examples show the
+* shape — including the exact failure case (a transcript whose last turn
+* is a refusal) so the answer-shaped completion has a labeled
+* counter-example to copy instead.
+*/
+const TITLE_SYSTEM_PROMPT = [
+	"You label conversations. Each input is a transcript of a session between a user and a coding agent.",
+	"Name what the session is ABOUT. You are an annotator, never a participant in the conversation.",
+	"",
+	"Rules:",
+	"- Reply with ONLY the label: no quotes, no markdown, no trailing punctuation, no preamble.",
+	`- 3 to 7 words, under ${TITLE_MAX_CHARS} characters, written as a noun phrase or an imperative.`,
+	"- Name the user's topic or task using concrete nouns from the transcript: files, tools, features, errors.",
+	"- NEVER answer, continue, or comment on the conversation — not even when the last message is a question, a refusal, or an error.",
+	"- No first person (\"I\", \"we\"), no \"the user\", and no filler words like conversation, session, chat, request, discussion, help.",
+	"",
+	"Examples of a transcript and its label:",
+	"- user asks why `bun test` hangs after an upgrade, agent finds a stuck worker → Bun test hangs on stuck worker",
+	"- user asks for a --json flag on the CLI → Add JSON output flag to the CLI",
+	"- user asks about a plan tool, agent replies that no such tool exists → Missing plan tool in the agent toolset"
+].join("\n");
+/**
+* Openers that mark a model reply rather than a label — the model
+* answering the transcript instead of naming it. Treated as a failed
+* generation (see {@link cleanTitle}) so the auto-titler retries on the
+* next run rather than persisting a sentence as the session name.
+*
+* Deliberately conservative: only phrasings that a real title would
+* never start with. Excluded on purpose because they head perfectly good
+* titles: `no` / `there is` ("No JSON output in the CLI"), `ok` / `yes` /
+* `great` ("OK button never fires", "Yes/no confirm regression").
+*
+* The pronoun cases require FOLLOWING WHITESPACE rather than a word
+* boundary — `\b` after `i` also matches punctuation, which rejected
+* "I/O timeout in the docker context". Contractions are matched
+* explicitly instead, with both the straight and typographic apostrophe
+* (models emit U+2019 freely, and `here's` / `let's` have no bare-word
+* alternative to fall back on).
+*/
+const ANSWER_SHAPED_OPENER = /^(?:i\s|i['’](?:m|ve|ll|d)\b|we\s|we['’](?:re|ve|ll)\b|let['’]s\b|let\s+(?:me|us)\b|sure\b|certainly\b|okay\b|sorry\b|thanks\b|unfortunately\b|here['’]s\b|here\s+is\b|as\s+an\b|you\s+(?:can|should|need)\b|it\s+(?:looks|seems|appears)\b)/i;
+/**
+* Drive the provider's `stream()` once and return a concise title for
+* the conversation represented by `turns`. Throws when:
+*   - `turns` contains no text-bearing content (nothing to summarize),
+*   - the provider stream completes with no output text,
+*   - the model answered the transcript instead of labeling it (see
+*     {@link cleanTitle}) — a failed generation the caller retries,
+*   - `signal` is aborted (rethrown verbatim).
+*
+* Output is trimmed, single-line, with surrounding quotes / trailing
+* punctuation stripped, and truncated to `TITLE_MAX_CHARS`.
+*/
+async function generateSessionTitle({ provider, model, turns, maxTurns = DEFAULT_MAX_TURNS, signal }) {
+	const transcript = renderTitleTranscript(turns, maxTurns);
+	if (!transcript) throw new Error("No text content in the recent turns to summarize.");
+	const userPrompt = [
+		"<transcript>",
+		transcript,
+		"</transcript>",
+		"",
+		"Write the label for the session in the transcript above. Label only."
+	].join("\n");
+	let text = "";
+	const result = await provider.stream({
+		model,
+		system: TITLE_SYSTEM_PROMPT,
+		tools: [],
+		messages: [provider.userMessage(userPrompt)],
+		maxTokens: TITLE_RESPONSE_MAX_TOKENS,
+		...signal ? { signal } : {}
+	}, { onText: (delta) => {
+		text += delta;
+	} });
+	return cleanTitle(text.trim().length > 0 ? text : result.text);
+}
+/**
+* Decide whether a session is ready for one-shot automatic titling.
+*
+* Returns `true` iff the conversation has had its first exchange — at
+* least two turns, i.e. the opening user message plus the assistant's
+* reply (this is exactly the "N turns" count the sessions list shows) —
+* AND no explicit title has been set yet. An existing `metadata.title`
+* (a previous auto-generation, or a manual title from the session-details
+* "generate title" action) is never clobbered.
+*
+* Pure + total. The runtime layers its own "is one already in flight?"
+* and "is a provider picked?" guards on top of this; the predicate only
+* encodes the content-level rule so it can be pinned in tests without a
+* mock provider — same rationale as the exported {@link cleanTitle}.
+*/
+function shouldAutoGenerateTitle(turns, metadata) {
+	if ((typeof metadata?.title === "string" ? metadata.title.trim() : "").length > 0) return false;
+	return turns.length >= 2;
+}
+/**
+* Assemble the transcript fed to the titling model: the session's
+* OPENING user turn (when it falls outside the window) followed by the
+* last `maxTurns` turns, separated by an `…` gap marker.
+*
+* The tail alone is not enough. A session's topic is set by the first
+* thing the user asked; after a dozen turns that message is off the
+* window and the model ends up naming whatever tangent the conversation
+* was on when titling fired — or, worse, the assistant's last reply.
+* Anchoring on the opening intent keeps the label about the session.
+*
+* `maxTurns` keeps its meaning (a cap on TRAILING turns); the anchor is
+* one extra entry on top, and only exists when the window actually cut
+* it off. Returns `''` when nothing in the selection carries text.
+*/
+function renderTitleTranscript(turns, maxTurns) {
+	const cap = Math.max(1, maxTurns);
+	const tail = renderTurnsForPrompt(turns.slice(-cap));
+	const opening = turns.slice(0, Math.max(0, turns.length - cap)).find((turn) => turn.role === "user" && textBodyOf(turn).length > 0);
+	const anchor = opening ? renderTurnsForPrompt([opening]) : "";
+	if (anchor && tail) return `${anchor}\n\n…\n\n${tail}`;
+	return anchor || tail;
+}
+/**
+* Compact a turn list into a transcript-style prompt:
+*
+*   user: …
+*   assistant: …
+*   user: …
+*
+* Tool calls and tool results are dropped entirely — a cheap title model
+* happily echoes plumbing like `[tool: list_files]` back as "the title"
+* when a marker is the only assistant content it sees. The topical text
+* is what a title needs. Per-turn text is clipped at `PROMPT_TURN_CHAR_MAX`
+* so a single huge code dump doesn't blow the budget.
+*
+* Returns an empty string when the slice has no text-bearing content
+* (e.g. a turn list that's only tool plumbing).
+*
+* Exported for reuse by other silent one-shot helpers (`generate-data`'s
+* optional conversation context) so every side-channel inference compacts
+* history the same way.
+*/
+function renderTurnsForPrompt(turns) {
+	const lines = [];
+	for (const turn of turns) {
+		const body = textBodyOf(turn);
+		if (!body) continue;
+		const role = turn.role === "assistant" ? "assistant" : turn.role === "user" ? "user" : "system";
+		lines.push(`${role}: ${clip(body, PROMPT_TURN_CHAR_MAX)}`);
+	}
+	return lines.join("\n\n");
+}
+function textBodyOf(turn) {
+	const parts = [];
+	for (const block of turn.content) if (block.type === "text" && block.text.trim()) parts.push(block.text.trim());
+	return parts.join(" ");
+}
+/** Strip one layer of matched surrounding quotes (`"foo"`, `'foo'`, `` `foo` ``, `“foo”`). */
+function unwrapQuotes(s) {
+	if (s.length < 2) return s;
+	const first = s.charAt(0);
+	const last = s.charAt(s.length - 1);
+	return first === "\"" && last === "\"" || first === "'" && last === "'" || first === "`" && last === "`" || first === "“" && last === "”" ? s.slice(1, -1).trim() : s;
+}
+/**
+* Normalize a model-generated title into the shape we want to persist:
+*
+*   - Collapse internal whitespace + take the first line only (some
+*     models emit "Title: foo\n\nReason: …" despite instructions).
+*   - Strip surrounding quotes, a leading `Title:` / `title -` preamble,
+*     and a `user:` / `assistant:` role prefix echoed from the transcript
+*     — repeatedly, in any nesting order.
+*   - Reject placeholders and answer-shaped replies (see
+*     {@link ANSWER_SHAPED_OPENER}) by throwing.
+*   - Strip trailing punctuation (`.`, `!`, `?`) — titles read cleaner
+*     without it.
+*   - Truncate to `TITLE_MAX_CHARS` with a trailing `…` when over.
+*
+* Exported as `cleanTitle` so tests can pin the normalization rules
+* without going through a mock provider.
+*/
+function cleanTitle(raw) {
+	let s = raw.split("\n")[0]?.trim() ?? "";
+	for (let pass = 0; pass < 4; pass++) {
+		const before = s;
+		s = unwrapQuotes(s);
+		s = s.replace(/^\s*title\s*[:\-–—]\s*/i, "");
+		s = s.replace(/^\s*(?:user|assistant|system)\s*:\s*/i, "");
+		if (s === before) break;
+	}
+	s = s.replace(/[.!?]+$/, "").trim();
+	if (s.length === 0) throw new Error("Model returned an empty title.");
+	if (/^\[.*\]$/.test(s)) throw new Error("Model returned a placeholder instead of a title.");
+	if (ANSWER_SHAPED_OPENER.test(s)) throw new Error("Model answered the conversation instead of titling it.");
+	return s.length > TITLE_MAX_CHARS ? `${s.slice(0, TITLE_MAX_CHARS - 1)}…` : s;
+}
+function clip(text, max) {
+	return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+//#endregion
+//#region src/chat/generate-data.ts
+/** Synthetic forced-choice tool name (never persisted — the call is side-channel only). */
+const DATA_TOOL_NAME = "__data__";
+/** Default cap on conversation turns folded into the context block. */
+const DEFAULT_CONTEXT_TURNS = 12;
+async function generateStructuredData(options) {
+	const { provider, model, prompt, signal } = options;
+	const spec = {
+		name: DATA_TOOL_NAME,
+		description: "Return the result. The input of this call IS the answer — it must conform to the schema.",
+		inputSchema: await resolveSchemaInput(options.schema)
+	};
+	const contextTurns = options.turns && options.turns.length > 0 ? options.turns.slice(-(options.maxContextTurns ?? DEFAULT_CONTEXT_TURNS)) : [];
+	const transcript = contextTurns.length > 0 ? renderTurnsForPrompt(contextTurns) : "";
+	const userPrompt = transcript ? `<conversation>\n${transcript}\n</conversation>\n\n${prompt}` : prompt;
+	const payload = (await provider.stream({
+		model,
+		system: options.system ?? `You produce structured data. Call the ${DATA_TOOL_NAME} tool exactly once with the requested value. No prose.`,
+		tools: provider.formatTools([spec]),
+		messages: [provider.userMessage(userPrompt)],
+		toolChoice: {
+			type: "tool",
+			name: DATA_TOOL_NAME
+		},
+		...signal ? { signal } : {}
+	}, { onText: () => {} })).toolCalls.find((tc) => tc.name === DATA_TOOL_NAME)?.input;
+	if (payload === void 0) throw new Error("generateStructuredData: the model returned no structured payload");
+	return payload;
+}
+//#endregion
+//#region src/chat/inline-autocomplete.ts
+/**
+* Inline (ghost-text) autocomplete for the prompt.
+*
+* Distinct from the trigger-based completion popover (`@` files, `/`
+* commands): providers here suggest plain text SUFFIX candidates to
+* append at the cursor — the first renders as dim ghost text, up/down
+* rotates through the rest, Tab accepts. No popover.
+*
+* Providers are queried in registration order with a shared AbortSignal;
+* the engine returns the first provider's non-empty candidate list.
+* Extensions add providers via `ctx.registerInlineAutocompleteProvider`
+* — the built-in path provider ({@link createPathAutocompleteProvider})
+* is always first.
+*/
+/** Default per-provider deadline — a hung provider is treated as "no suggestion". */
+const PROVIDER_DEADLINE_MS = 150;
+/** Hard cap on a provider's `deadlineMs` — past this, waiting for a ghost reads as broken. */
+const MAX_PROVIDER_DEADLINE_MS = 2e3;
+/**
+* Query `providers` in order; the first provider yielding a non-empty
+* candidate list wins (a bare string normalizes to a 1-element list).
+* Provider errors are swallowed (a broken extension provider must not
+* break typing), and each provider races its deadline —
+* {@link PROVIDER_DEADLINE_MS} by default, a provider's own `deadlineMs`
+* (capped at {@link MAX_PROVIDER_DEADLINE_MS}) when declared — so one
+* hung provider can't permanently suppress the ghosts of providers
+* behind it. Returns null when aborted or nothing matched.
+*/
+async function resolveInlineSuggestion(providers, ctx, deadlineMs = PROVIDER_DEADLINE_MS, maxDeadlineMs = MAX_PROVIDER_DEADLINE_MS) {
+	const TIMEOUT = Symbol("timeout");
+	for (const provider of providers) {
+		if (ctx.signal.aborted) return null;
+		try {
+			let timer;
+			const budget = provider.deadlineMs !== void 0 ? Math.min(Math.max(provider.deadlineMs, 1), maxDeadlineMs) : deadlineMs;
+			const result = await Promise.race([Promise.resolve(provider.suggest(ctx)), new Promise((r) => {
+				timer = setTimeout(r, budget, TIMEOUT);
+			})]);
+			if (timer !== void 0) clearTimeout(timer);
+			if (result === TIMEOUT) continue;
+			if (ctx.signal.aborted) return null;
+			const suffixes = (typeof result === "string" ? [result] : result ?? []).filter((s) => typeof s === "string" && s.length > 0);
+			if (suffixes.length > 0) return {
+				suffixes,
+				providerId: provider.id
+			};
+		} catch {}
+	}
+	return null;
+}
+/**
+* Extract the whitespace-delimited token that ends at `cursor`. Returns
+* null when the cursor sits right after whitespace (nothing to complete).
+*/
+function tokenEndingAtCursor(text, cursor) {
+	const match = text.slice(0, cursor).match(/\S+$/);
+	return match ? match[0] : null;
+}
+/**
+* Does this token carry an explicit path shape (`/` separator or a `~`
+* prefix)? Path-shaped tokens complete from the first character after
+* the separator; bare tokens (`sr` → `c/`) still complete against the
+* cwd listing but need ≥2 chars first — see the provider.
+*/
+function looksLikePath(token) {
+	return token.includes("/") || token.startsWith("~");
+}
+/**
+* Cap on candidates returned for an ambiguous fragment — rotation past
+* a dozen-odd entries stops being faster than typing another character.
+*/
+const MAX_PATH_CANDIDATES = 16;
+function defaultReaddir(dir) {
+	return readdirSync(dir, { withFileTypes: true }).map((e) => ({
+		name: e.name,
+		isDirectory: e.isDirectory()
+	}));
+}
+/**
+* Built-in provider: complete filesystem paths under `cwd` (or absolute /
+* `~` paths). Given the token `src/chat/comp`, lists `src/chat/` and
+* returns every matching continuation of `comp` as a candidate list —
+* directories first, alphabetical, `/`-terminated for directories so
+* typing can continue. The host ghosts the first candidate and rotates
+* through the rest on up/down.
+*
+* Bare tokens (no `/` yet) are matched against the cwd listing too, so
+* a directory ghost appears as soon as the first characters of `src`
+* are typed — but only from the second character on, so 1-letter prose
+* words don't ghost-spam.
+*
+* Dotfiles are only offered when the typed fragment itself starts with
+* `.` — the usual completion convention.
+*/
+function createPathAutocompleteProvider(opts = {}) {
+	const readdir = opts.io?.readdir ?? defaultReaddir;
+	const fallbackCwd = opts.cwd ?? (() => process.cwd());
+	return {
+		id: "paths",
+		suggest(ctx) {
+			const token = tokenEndingAtCursor(ctx.text, ctx.cursor);
+			if (!token) return null;
+			if (!looksLikePath(token) && token.length < 2) return null;
+			const expanded = token.startsWith("~") ? join(homedir(), token.slice(1)) : token;
+			const endsWithSep = expanded.endsWith("/");
+			const dirPart = endsWithSep ? expanded : dirname(expanded);
+			const fragment = endsWithSep ? "" : basename(expanded);
+			const baseCwd = ctx.cwd || fallbackCwd();
+			const dir = isAbsolute(dirPart) ? dirPart : resolve(baseCwd, dirPart);
+			let entries;
+			try {
+				entries = readdir(dir);
+			} catch {
+				return null;
+			}
+			const matches = entries.filter((e) => e.name.startsWith(fragment) && (fragment.startsWith(".") || !e.name.startsWith(".")));
+			matches.sort((a, b) => a.isDirectory !== b.isDirectory ? a.isDirectory ? -1 : 1 : a.name.localeCompare(b.name));
+			const suffixes = matches.map((e) => e.name.slice(fragment.length) + (e.isDirectory ? "/" : "")).filter((s) => s.length > 0).slice(0, MAX_PATH_CANDIDATES);
+			return suffixes.length > 0 ? suffixes : null;
+		}
+	};
+}
+/**
+* Optimistically transform the current ghost across a buffer edit so it
+* stays visible while the debounced provider re-query is in flight —
+* without this, every keystroke inside a completable token blinks the
+* ghost (hide → 120 ms → reshow).
+*
+* Two edits are reconcilable (everything else returns null and waits for
+* the authoritative result):
+*   - typing FORWARD along the suggestion (`bi` → `bin` with ghost
+*     `n/`): candidates are filtered to those starting with the typed
+*     chars and trimmed;
+*   - deleting BACKWARD within the token (`bin` → `bi` with ghost `/`):
+*     the deleted chars are re-prepended to every candidate. Guarded to
+*     non-whitespace so crossing a token boundary drops the ghost.
+*
+* The patched ghost is provisional — the provider's answer replaces it
+* (and may add candidates the patch couldn't know about).
+*/
+function patchInlineGhost(prev, text, cursor) {
+	if (!prev) return null;
+	if (text === prev.text && cursor === prev.cursor) return prev;
+	if (text.slice(cursor) !== prev.text.slice(prev.cursor)) return null;
+	if (cursor > prev.cursor) {
+		if (text.slice(0, prev.cursor) !== prev.text.slice(0, prev.cursor)) return null;
+		const typed = text.slice(prev.cursor, cursor);
+		const shown = prev.suffixes[prev.index];
+		const suffixes = prev.suffixes.filter((s) => s.startsWith(typed) && s.length > typed.length).map((s) => s.slice(typed.length));
+		if (suffixes.length === 0) return null;
+		const shownTrimmed = shown.startsWith(typed) ? shown.slice(typed.length) : null;
+		return {
+			suffixes,
+			index: shownTrimmed !== null ? Math.max(0, suffixes.indexOf(shownTrimmed)) : 0,
+			text,
+			cursor
+		};
+	}
+	if (prev.text.slice(0, cursor) !== text.slice(0, cursor)) return null;
+	const deleted = prev.text.slice(cursor, prev.cursor);
+	if (deleted.length === 0 || /\s/.test(deleted)) return null;
+	return {
+		suffixes: prev.suffixes.map((s) => deleted + s),
+		index: prev.index,
+		text,
+		cursor
+	};
+}
+//#endregion
+//#region src/extension-authoring.ts
+/**
+* Session-metadata key marking an "edit / create extension" session. The value
+* is an {@link ExtensionEditMarker}. Both hosts stamp it at session creation so
+* the agent build can scope the docs skill to exactly these sessions (and it
+* survives reload because metadata is persisted).
+*/
+const EXTENSION_EDIT_METADATA_KEY = "zidane.extensionEdit";
+/** Name of the inline docs skill auto-activated in extension edit sessions. */
+const ZIDANE_EXTENSION_SKILL_NAME = "zidane-extension";
+/**
+* Session-metadata key marking an "edit skill" session — the skill-editing
+* counterpart of {@link EXTENSION_EDIT_METADATA_KEY}. The value is a
+* {@link SkillEditMarker}. Stamped at session creation by both hosts (via
+* {@link editSessionMetadata}); persisted metadata means it survives reload.
+*/
+const SKILL_EDIT_METADATA_KEY = "zidane.skillEdit";
+/** Name of the inline preset skill auto-activated in skill edit sessions. */
+const ZIDANE_SKILL_EDIT_SKILL_NAME = "zidane-skill";
+/**
+* THE canonical seed for "open an editing session with preset context" —
+* the session metadata both hosts stamp at creation time. The engines read
+* the marker back and inject + auto-activate the matching inline preset
+* skill ({@link buildZidaneExtensionSkill} / {@link buildZidaneSkillEditSkill}),
+* so the preset rides as real conversation context from turn one.
+*/
+function editSessionMetadata(target) {
+	return target.kind === "extension" ? { [EXTENSION_EDIT_METADATA_KEY]: { dir: target.dir } } : { [SKILL_EDIT_METADATA_KEY]: {
+		dir: target.dir,
+		name: target.name
+	} };
+}
+/**
+* Parse a persisted {@link SkillEditMarker} back out of session metadata.
+* Tolerant: anything that isn't `{ dir: string, name: string }` → `null`
+* (older sessions, manual metadata edits, type drift).
+*/
+function readSkillEditMarker(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const { dir, name } = raw;
+	if (typeof dir !== "string" || dir.length === 0 || typeof name !== "string" || name.length === 0) return null;
+	return {
+		dir,
+		name
+	};
+}
+/**
+* Minimal valid extension module for a freshly-created extension. `name` MUST
+* equal the folder name or the loader rejects it (see `src/extensions/discovery`).
+* Does nothing by default — the author registers contributions via `ctx.*`
+* inside `setup`; the auto-activated docs skill guides them from there.
+*/
+function extensionScaffold(name) {
+	return `import { defineExtension } from 'zidane'
+
+/**
+ * ${name} — a zidane extension.
+ *
+ * Register tools / hooks / skills / MCP servers / subagents / config / themes /
+ * agents / keybindings via the \`ctx\` surface inside \`setup\`.
+ *
+ * Authoring reference: activate the \`${ZIDANE_EXTENSION_SKILL_NAME}\` skill — it carries
+ * the full \`ctx\` API + invariants and is available whenever you open this
+ * folder in zidane (or run \`zidane\` from inside it).
+ */
+export default defineExtension({
+  name: '${name}',
+  setup(ctx) {
+    // e.g. ctx.registerTool('${name}_hello', {
+    //   spec: { name: '${name}_hello', description: 'say hi', inputSchema: { type: 'object', properties: {} } },
+    //   isConcurrencySafe: true,
+    //   async execute() { return 'hello from ${name}' },
+    // })
+  },
+})
+`;
+}
+/**
+* Locate the shipped `docs/` directory (`docs/EXTENSIONS.md` + siblings).
+*
+* The docs ship via `package.json` `files`, so an installed consumer has
+* `<root>/node_modules/zidane/docs` and the repo itself has `<repo>/docs`.
+* Returns the first existing candidate, or `null` (the skill then falls back to
+* the literal `node_modules/zidane/docs` hint, which the model's file tools can
+* still attempt from cwd).
+*/
+function resolveExtensionDocsDir(cwd = process.cwd()) {
+	const candidates = [];
+	try {
+		const req = createRequire(import.meta.url);
+		candidates.push(join(dirname(req.resolve("zidane/package.json")), "docs"));
+	} catch {}
+	try {
+		let dir = dirname(fileURLToPath(import.meta.url));
+		for (let i = 0; i < 6; i++) {
+			if (existsSync(join(dir, "docs", "EXTENSIONS.md"))) {
+				candidates.push(join(dir, "docs"));
+				break;
+			}
+			dir = dirname(dir);
+		}
+	} catch {}
+	candidates.push(join(cwd, "node_modules", "zidane", "docs"));
+	for (const candidate of candidates) if (existsSync(join(candidate, "EXTENSIONS.md"))) return candidate;
+	return null;
+}
+/** Entry-file probe order for an extension dir (mirrors the loader's discovery). */
+const EXTENSION_ENTRY_FILES = [
+	"index.ts",
+	"index.tsx",
+	"index.mjs",
+	"index.js"
+];
+/**
+* If `cwd` sits inside a zidane extension, return that extension's root dir,
+* else `null`. Mirrors the discovery layout
+* `<scope>/.{agents,zidane}/extensions/<name>/` — the root is the `<name>` dir
+* (parent `extensions`, grandparent `.agents` / `.zidane`) holding an entry
+* file. Walks up from `cwd`, so the nearest enclosing extension wins. Lets the
+* hosts surface the authoring skill for a plain `zidane` launched from an
+* extension folder, not just sessions opened through the edit/create flow.
+*/
+function extensionDirForCwd(cwd = process.cwd()) {
+	let dir = resolve(cwd);
+	for (let i = 0; i < 64; i++) {
+		const parent = dirname(dir);
+		if (basename(parent) === "extensions" && (basename(dirname(parent)) === ".agents" || basename(dirname(parent)) === ".zidane") && EXTENSION_ENTRY_FILES.some((f) => existsSync(join(dir, f)))) return dir;
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* The authoring reference embedded into the skill body. Kept INLINE (not a
+* filesystem path) on purpose: a `bun build --compile` TUI binary has no
+* resolvable `node_modules/zidane/docs`, no real `import.meta.url`, and the
+* edited extension's own cwd has no `node_modules` — so a path reference dead-
+* ends there. The model gets the API verbatim on activation regardless of host.
+*
+* Mirrors `ExtensionContext` (src/extensions/types.ts) — keep in sync when the
+* `ctx.*` surface changes.
+*/
+const EXTENSION_AUTHORING_CHEATSHEET = `## defineExtension
+
+A zidane extension is a module at \`<scope>/.{agents,zidane}/extensions/<name>/index.{ts,tsx,mjs,js}\`
+that default-exports \`defineExtension({ ... })\`. It runs in-process in the host (TUI / GUI / SDK).
+
+\`\`\`ts
+import { defineExtension } from 'zidane'
+
+export default defineExtension({
+  name: 'my-ext',          // MUST equal the folder name
+  apiVersion: 1,           // optional; omitted means v1
+  version: '0.1.0',        // optional — shown in Settings → Extensions
+  displayName: 'My Ext',   // optional UI label
+  description: 'what it does',
+  capabilities: ['tools'], // optional descriptive manifest labels
+  permissions: [],         // optional descriptive labels; not a sandbox
+  setup(ctx) { /* register everything here; may be async */ },
+  teardown() {},           // optional, reserved (no hot-reload yet)
+})
+\`\`\`
+
+Zero-import form — required INSIDE compiled binaries, which can't \`import 'zidane'\` at runtime:
+\`\`\`ts
+import type { ExtensionContext } from 'zidane' // type-only: erased at runtime
+export default {
+  name: 'my-ext',
+  setup(ctx: ExtensionContext) { /* ... */ },
+}
+\`\`\`
+
+## ctx surface (call everything inside setup)
+
+Identity / utilities:
+- ctx.name / ctx.version / ctx.dir / ctx.scope ('project' | 'user' | 'inline' | 'builtin')
+- ctx.logger          — Logger namespaced \`extension:<name>\`
+- ctx.config          — read THIS extension's config, default-first: \`ctx.config.get(key)\`
+- ctx.paths           — cwd/projectRoot/dataDir/cacheDir/configDir/stateDir
+- ctx.storage.path(scope, ...segments) — extension-scoped storage path
+- ctx.session         — JSON-only per-session state: get / set / delete
+
+Renderer-agnostic registration:
+- ctx.registerTool(name, toolDef)
+- ctx.registerHook(event, handler)             — an AgentHooks event; fires on the PARENT agent (use child:* for subagents)
+- ctx.registerMcpServer(config)
+- ctx.registerSkill(skillConfig)               — a defineSkill() shape
+- ctx.registerCompletionProvider(provider)     — single-char '/' '@' '!' trigger
+- ctx.tui.notify(text, { tone? })              — one-shot transcript line (info/warn/error); buffered pre-mount
+- ctx.tui.setStatus(text | null, { loader?, timeout? }) — single dim status line (transcript-tail slot); loader glyph, auto-clear ms
+- ctx.tui.setBanner(lines | null, { timeout? }) — short block above the prompt (stacked with the todo indicator); auto-clear ms
+- ctx.submitPrompt(text, { delivery? })        — submit as the user: 'auto' (run-or-queue), 'steer', 'followUp'; false when detached
+- ctx.registerToolPolicy({ tools?, decide })   — gate tool calls: allow / { block } / { patch } (patches re-validated by the loop)
+- ctx.registerToolResultTransform(fn)          — middleware over finished tool results (chained)
+- ctx.registerContextTransform(fn)             — rewrite wire messages before each provider call
+- ctx.registerPromptTransform(fn)              — transform or consume submitted prompts (after / commands, before skills)
+- ctx.runtime / ctx.sessions                   — late-bound host controls: model()/thinking()/setThinking(), sessions list/switch/create
+- ctx.appendNote(blocks)                       — durable display-only transcript note (command-output block vocabulary)
+- ctx.workspace.exec/readFile/writeFile/listFiles/fileSize — shell + files through the SESSION'S execution context (sandbox-correct; host child_process silently targets the wrong filesystem under docker/e2b). Detached ⇒ rejects; guard with \`await ctx.workspace.available()\`.
+- ctx.tui.registerToolRenderer({ tools?, render }) — custom view for tool-result rows; return null to fall through to the default. View-layer only: never persisted, error-bounded per row, TUI-scoped.
+- ctx.tui.registerRenderer(id, render) + emit/appendNote \`custom: { renderer, data }\` blocks — custom components in the transcript. \`data\` must be JSON-safe (it persists); the block's \`text\` is the MANDATORY markdown fallback (disabled extension, headless host, GUI, renderer throw). appendNote auto-prefixes bare ids; command emit needs \`<ext>/<id>\`.
+- Renderer components: import \`react\` / \`@opentui/react\` BARE (never as your own dependency) — the host maps them to its live instances at load time, so hooks work. Async data: render() stays sync; return a component that fetches with useState/useEffect.
+- Renderer async caching: \`useSessionState(id, initial)\` (per-row, session-persisted — rehydrates on reload) + \`useRowVisible()\` (latched viewport gate) from \`zidane/tui\` — fetch once, only when scrolled in.
+- ctx.registerCommand(command)                 — a '/<name>' workflow (handler or steps[]); step ctx: emit (local output),
+                                                 runAgent (interactive sub-run), generateData (silent zod/JSON-Schema JSON),
+                                                 session? (read-only turns/runs view), interaction? (confirm / askUser forms /
+                                                 presentPlan approval — both optional; guard for bare hosts)
+- ctx.registerTheme(theme)
+- ctx.registerAgent(profile)                   — extra agent profile in the picker
+- ctx.registerSubagent(def)                    — spawnable subagent (the spawn tool's subagent_type)
+- ctx.registerSubagentOverride(name, fn)       — edit/delete an existing subagent
+- ctx.registerProvider(descriptor)
+- ctx.registerSystemPromptFragment(text)
+- ctx.registerContextBreakdownSection(fn)      — render extension-owned rows in the context panel
+- ctx.registerContextPanelSection(section)     — richer context panel section with rows/load
+- ctx.registerToolResultMetadata(registration) — project namespaced tool-result metadata into context
+- ctx.registerRunTransform(fn)                 — sync rewrite of agent.run options
+- ctx.registerBehaviorTransform(fn)            — sync rewrite of resolved behavior
+- ctx.registerProviderMiddleware(fn)           — wrap provider instances
+- ctx.registerToolCatalogTransform(fn)         — shape/hide/rename tools before disclosure/execution
+- ctx.registerMcpConfigTransform(fn)           — rewrite MCP server configs before connect
+- ctx.registerSkillPolicy(policy)              — auto-activate skills by run context
+- ctx.registerConfigCategory(category)
+- ctx.registerConfigItem([categoryId,] item)   — typed setting; supports scope/onChange metadata
+
+TUI-only (ctx.tui.* — silently ignored on non-TUI hosts):
+- ctx.tui.registerKeybinding(binding)
+- ctx.tui.registerFooterHint(hint)
+- ctx.tui.registerModal(modal)                 — keep UI lazy: \`node: () => import('./panel')\`
+
+GUI-only:
+- ctx.gui.registerPanel(panel)                  — collected, not rendered yet
+
+Completion providers may also implement submit hooks:
+- resolveReferences(refs, ctx, signal)
+- onSubmit({ text, cursor, references }, signal)
+Both TUI and GUI call these before dispatching a submitted prompt.
+
+## ToolDef shape
+\`\`\`ts
+ctx.registerTool('my_tool', {
+  spec: { name: 'my_tool', description: '...', inputSchema: { type: 'object', properties: {} } },
+  isConcurrencySafe: true,   // default false (barrier/write); true = read-only, fans out in parallel
+  async execute(args) { return 'result' },
+})
+\`\`\`
+
+## Invariants
+- The folder name MUST equal \`name\`, or the loader rejects the extension.
+- Optional metadata lives in \`extension.json\` or \`package.json#zidane\`; unsupported \`apiVersion\` is rejected.
+- Export as \`default\` (or a named \`extension\` export).
+- Register ONLY inside \`setup\` — calls after it resolves are dropped (logger.warn).
+- A throw in \`setup\` is caught and shown on the extension's Settings row; the rest of boot continues.
+- Discovery order, first per name wins: project \`.agents\` → project \`.zidane\` → \`~/.agents\` → \`~/.zidane\`.
+- \`/reload\` is a TRUE hot-reload: re-discover + re-run setup, and each extension's module graph is re-imported fresh — code edits (deep imports included) apply live. Module-level state resets; clean up external resources in \`teardown\`.
+
+## Distribution
+- Users install via Settings → Extensions → \`ctrl+g\` (source input + scope picker) — GitHub (\`owner/repo[#ref][:sub/dir]\`, tree URLs) or npm (\`pkg[@version]\`, exact versions / dist-tags).
+- Update / remove: Settings → Extensions, \`ctrl+u\` / \`ctrl+x\` on the focused row (update replays the recorded \`.install.json\` provenance in place, skipping when the recorded commit/version still matches the remote).
+- Shape your repo/package as a root \`index.ts\` (single extension) or \`extensions/<name>/index.*\` dirs (collection).
+- Reference packages to copy: \`extensions/git-flow\` in the zidane repo (zero-dep \`/commit\` command) and \`extensions/headroom\` (hooks + tool + config).
+- Declare runtime deps in \`package.json#dependencies\` — installed with bun/npm/… WITHOUT lifecycle scripts; don't rely on postinstall.
+- The installed folder is named from your exported \`definition.name\` — pick it to be folder-safe ([A-Za-z0-9_.-]).`;
+/** Preset preamble for "edit / create extension" sessions. */
+const EXTENSION_EDIT_PRESET = "You are authoring / editing a zidane extension. Authoritative API reference:";
+/** Preset preamble for "edit skill" sessions — same spirit, skill-flavored. */
+function skillEditPreset(marker) {
+	return `We are going to work on ${marker.name}, in ${marker.dir} directory, next messages will be requests at modifying and improving the skill or understanding how it works better.`;
+}
+/**
+* The inline `zidane-extension` skill. Carries the authoring reference IN its
+* body ({@link EXTENSION_AUTHORING_CHEATSHEET}) so it works in every host —
+* incl. compiled binaries where the on-disk docs aren't resolvable. The shipped
+* `EXTENSIONS.md` (prose long-form) is appended as a "see also" only when found
+* on disk. `source: 'inline'` (the `defineSkill` default) survives the
+* project-trust gate.
+*/
+function buildZidaneExtensionSkill(opts = {}) {
+	const docsDir = resolveExtensionDocsDir(opts.cwd);
+	const seeAlso = docsDir ? `\n\n---\nFull prose reference on disk: ${join(docsDir, "EXTENSIONS.md")}\nSibling docs cover related surfaces (ARCHITECTURE.md, CHAT.md, TUI.md, SKILL.md, HEADLESS.md, …).` : "\n\n---\nFuller prose reference, when present: node_modules/zidane/docs/EXTENSIONS.md (often absent in compiled binaries — the API above is authoritative).";
+	return defineSkill({
+		name: ZIDANE_EXTENSION_SKILL_NAME,
+		description: "Authoring or editing a zidane extension (a module calling defineExtension, under .zidane/extensions/** or .agents/extensions/**). Carries the extension authoring reference.",
+		instructions: `${EXTENSION_EDIT_PRESET}\n\n${EXTENSION_AUTHORING_CHEATSHEET}${seeAlso}`
+	});
+}
+/**
+* Inject the `zidane-extension` skill into an already-merged {@link SkillsConfig}.
+*
+* Call this on the FINAL merged skills object (after folding extension / preset
+* skills): `composePresets` is last-wins on `catalog`, so injecting earlier
+* would be silently dropped whenever an extension also contributes skills.
+*
+* Adds the skill to the catalog and, when an `enabled` allowlist is in force,
+* force-includes the name so the allowlist filter can't hide it (mirrors how
+* extension-contributed skill names are force-included). When skills are fully
+* disabled (`enabled === false`), the edit session still gets just this skill.
+*/
+function withZidaneExtensionSkill(skills, opts = {}) {
+	return injectInlineSkill(skills, buildZidaneExtensionSkill(opts));
+}
+/**
+* Compact skill-authoring reference embedded into the skill-edit skill body.
+* Inline for the same reason as {@link EXTENSION_AUTHORING_CHEATSHEET}: works
+* in compiled binaries where on-disk docs don't resolve.
+*/
+const SKILL_AUTHORING_CHEATSHEET = `## SKILL.md anatomy
+
+A skill is a directory holding a \`SKILL.md\` (YAML frontmatter + markdown body)
+per the Agent Skills standard (agentskills.io/specification):
+
+\`\`\`md
+---
+name: my-skill            # 1-64 chars, lowercase alphanumeric + hyphens; SHOULD match the directory name
+description: what it does AND when to use it (drives activation — 1-1024 chars)
+license: MIT              # optional
+compatibility: …          # optional environment requirements
+allowed-tools:            # optional — restricts the agent to these tools while active
+  - read_file
+metadata:                 # optional flat string map; zidane-specific keys use the \`zidane.\` prefix
+  some-key: value
+---
+The body is the skill's instructions — injected into context when the skill
+is activated. Keep it token-lean: move depth into references/.
+\`\`\`
+
+## Bundled resources (all optional, discovered automatically)
+- \`references/\` — docs loaded on demand via \`skills_read\`
+- \`scripts/\`    — executables run via \`skills_run_script\` (honor shebangs)
+- \`assets/\`     — templates / static files
+
+## Guidance
+- The description is the activation trigger — write it for the ROUTER ("use when …"), the body for the ACTIVATED agent.
+- Prefer small bodies + lazy references over one giant SKILL.md.
+- Shell interpolation (exclamation mark + backtick-quoted command) in the body runs at activation — use sparingly; hosts may gate or disable it.
+- Validate names: mismatched frontmatter name vs directory loads with a warning diagnostic.`;
+/**
+* The inline skill auto-activated in "edit skill" sessions. Body = the
+* session preset (which skill, which directory, what the next messages will
+* be about) + a compact SKILL.md authoring reference — the skill-editing
+* counterpart of {@link buildZidaneExtensionSkill}.
+*/
+function buildZidaneSkillEditSkill(marker, opts = {}) {
+	const docsDir = resolveExtensionDocsDir(opts.cwd);
+	const seeAlso = docsDir && existsSync(join(docsDir, "SKILL.md")) ? `\n\n---\nFull prose reference on disk: ${join(docsDir, "SKILL.md")}` : "";
+	return defineSkill({
+		name: ZIDANE_SKILL_EDIT_SKILL_NAME,
+		description: `Editing or improving the "${marker.name}" agent skill (its SKILL.md, references, scripts, and assets). Carries the skill-authoring reference for this edit session.`,
+		instructions: `${skillEditPreset(marker)}\n\n${SKILL_AUTHORING_CHEATSHEET}${seeAlso}`
+	});
+}
+/**
+* Inject the skill-edit preset skill into an already-merged {@link SkillsConfig}.
+* Same contract as {@link withZidaneExtensionSkill} — call on the FINAL merged
+* skills object.
+*/
+function withZidaneSkillEditSkill(skills, marker, opts = {}) {
+	return injectInlineSkill(skills, buildZidaneSkillEditSkill(marker, opts));
+}
+/**
+* Shared injector: add `skill` to the catalog and, when an `enabled`
+* allowlist is in force, force-include its name so the filter can't hide it
+* (mirrors how extension-contributed skill names are force-included). When
+* skills are fully disabled (`enabled === false`), the edit session still
+* gets just this skill.
+*/
+function injectInlineSkill(skills, skill) {
+	const catalog = [...skills.catalog ?? [], skill];
+	const enabled = skills.enabled;
+	const nextEnabled = enabled === void 0 ? void 0 : Array.isArray(enabled) ? enabled.includes(skill.name) ? enabled : [...enabled, skill.name] : [skill.name];
+	return {
+		...skills,
+		catalog,
+		...nextEnabled !== void 0 ? { enabled: nextEnabled } : {}
+	};
+}
+//#endregion
+//#region src/mcp/oauth-callback.ts
+const DEFAULT_PATH = "/callback";
+const DEFAULT_HOST = "127.0.0.1";
+/**
+* Fallback renderer for hosts that don't inject one (bare SDK use) —
+* deliberately minimal, no framework, no branding. All interpolations are
+* escaped: a malicious authorization server could craft an
+* `error_description` containing markup, and even a one-shot loopback
+* page must not XSS.
+*/
+const renderMinimalPage = (page) => {
+	const escaped = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+	const ok = page.kind === "success";
+	return `<!doctype html>
+<html><head><meta charset="utf-8"><title>${ok ? "Logged in" : "Login failed"}</title>
+<style>body{font:14px/1.5 -apple-system,system-ui,sans-serif;margin:6rem auto;max-width:28rem;text-align:center;color:#1d1d1f}.ok{color:#1f8a4c;font-weight:600}.err{color:#c43c2c;font-weight:600}</style>
+</head><body>
+<p class="${ok ? "ok" : "err"}">${ok ? "Logged in." : "Login failed."}</p>
+${page.details ? `<p>${escaped(page.details)}</p>` : ""}
+<p>${escaped(page.message)}</p>
+</body></html>`;
+};
+const CLOSE_TAB_MESSAGE = "You can close this tab and return to the terminal.";
+/**
+* Start a one-shot OAuth callback server. The returned handle's `redirectUri`
+* should be passed to the authorization server as the `redirect_uri` query
+* parameter; `promise` resolves once the user finishes the browser flow.
+*
+* Always `await handle.close()` in a `finally` block — even on success, the
+* server stays open until told to shut down (so it can serve the
+* "you can close this tab" page).
+*/
+async function startOAuthCallback(opts = {}) {
+	const path = opts.path ?? DEFAULT_PATH;
+	const host = opts.host ?? DEFAULT_HOST;
+	const port = opts.port ?? 0;
+	const renderPage = opts.renderPage ?? renderMinimalPage;
+	const provider = opts.provider ?? "MCP server";
+	if (!path.startsWith("/")) throw new Error(`OAuth callback path must start with "/" (got: ${JSON.stringify(path)})`);
+	if (opts.signal?.aborted) throw new Error("OAuth callback aborted");
+	let resolveResult;
+	let rejectResult;
+	const promise = new Promise((resolve, reject) => {
+		resolveResult = resolve;
+		rejectResult = reject;
+	});
+	promise.catch(() => {});
+	let settled = false;
+	const resolveOnce = (value) => {
+		if (settled) return;
+		settled = true;
+		resolveResult(value);
+	};
+	const rejectOnce = (error) => {
+		if (settled) return;
+		settled = true;
+		rejectResult(error);
+	};
+	const server = createServer((req, res) => {
+		const url = new URL(req.url ?? "/", `http://${host}`);
+		if (url.pathname !== path) {
+			res.writeHead(404, { "content-type": "text/plain" });
+			res.end("Not Found");
+			return;
+		}
+		const htmlHeaders = {
+			"content-type": "text/html; charset=utf-8",
+			"cache-control": "no-store"
+		};
+		const error = url.searchParams.get("error");
+		if (error) {
+			const desc = url.searchParams.get("error_description") ?? error;
+			res.writeHead(400, htmlHeaders);
+			res.end(renderPage({
+				kind: "error",
+				message: CLOSE_TAB_MESSAGE,
+				details: desc,
+				provider
+			}));
+			rejectOnce(/* @__PURE__ */ new Error(`OAuth authorization failed: ${desc}`));
+			return;
+		}
+		const code = url.searchParams.get("code");
+		if (!code) {
+			res.writeHead(400, { "content-type": "text/plain" });
+			res.end("Missing \"code\" query parameter.");
+			return;
+		}
+		const state = url.searchParams.get("state") ?? void 0;
+		res.writeHead(200, htmlHeaders);
+		res.end(renderPage({
+			kind: "success",
+			message: CLOSE_TAB_MESSAGE,
+			provider
+		}));
+		resolveOnce({
+			code,
+			state
+		});
+	});
+	server.on("error", (err) => {
+		rejectOnce(err instanceof Error ? err : new Error(String(err)));
+	});
+	await new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(port, host, () => {
+			server.off("error", reject);
+			resolve();
+		});
+	});
+	const addr = server.address();
+	if (!addr || typeof addr === "string") {
+		server.close();
+		throw new Error("OAuth callback server did not bind to a TCP port");
+	}
+	let closing;
+	let closeServer;
+	const onAbort = () => {
+		rejectOnce(/* @__PURE__ */ new Error("OAuth callback aborted"));
+		closeServer();
+	};
+	closeServer = () => {
+		if (closing) return closing;
+		closing = new Promise((resolve) => {
+			server.closeAllConnections?.();
+			server.close(() => {
+				opts.signal?.removeEventListener("abort", onAbort);
+				if (opts.signal?.aborted) rejectOnce(/* @__PURE__ */ new Error("OAuth callback aborted"));
+				else rejectOnce(/* @__PURE__ */ new Error("OAuth callback server closed"));
+				resolve();
+			});
+		});
+		return closing;
+	};
+	opts.signal?.addEventListener("abort", onAbort, { once: true });
+	return {
+		redirectUri: `http://${host}:${addr.port}${path}`,
+		promise,
+		close: closeServer
+	};
+}
+//#endregion
+//#region src/mcp/login.ts
+const DEFAULT_LOGIN_TIMEOUT_MS = 5 * 6e4;
+const DEFAULT_CONNECT_TIMEOUT_MS = 3e4;
+/**
+* Run the full interactive OAuth flow for `config`. Only supports `sse` and
+* `streamable-http` transports — `stdio` MCP servers don't speak OAuth.
+*
+* Throws on:
+*   - Wrong transport.
+*   - Abort signal.
+*   - Browser-side error (user denied, server rejected, etc.).
+*   - Code exchange failure.
+*   - Post-exchange connect failure.
+*
+* Always closes the loopback callback server before returning, success or
+* failure.
+*/
+async function loginMcpServer(config, options) {
+	if (config.transport !== "sse" && config.transport !== "streamable-http") throw new Error(`MCP OAuth: cannot login for transport "${config.transport}" — only sse / streamable-http are supported`);
+	if (!config.url) throw new Error(`MCP OAuth: server "${config.name}" is missing a url`);
+	const hooks = options.hooks;
+	let settled = false;
+	let callback;
+	try {
+		callback = await startOAuthCallback({
+			signal: options.signal,
+			path: options.callbackPath,
+			...options.renderCallbackPage ? { renderPage: options.renderCallbackPage } : {},
+			provider: config.name
+		});
+		const handle = callback;
+		const provider = new McpOAuthProvider({
+			name: config.name,
+			store: options.store,
+			redirectUri: handle.redirectUri,
+			clientName: options.clientName,
+			scope: options.scope,
+			onAuthorizationUrl: async (url) => {
+				if (settled || options.signal?.aborted) return;
+				await hooks?.callHook("mcp:auth:url", {
+					name: config.name,
+					url: url.toString()
+				});
+				await options.onAuthorizationUrl?.(url);
+			}
+		});
+		let transport = await createInteractiveTransport(config, provider);
+		const client = await createTolerantClient({
+			name: "zidane",
+			version: "1.0.0"
+		});
+		let needsAuth = false;
+		const connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+		for (let attempt = 0;; attempt++) try {
+			await raceAbort(client.connect(transport), options.signal, connectTimeoutMs, `MCP OAuth: "${config.name}" did not respond within ${connectTimeoutMs}ms — the server may be unreachable`);
+			break;
+		} catch (err) {
+			if (isUnauthorizedError(err)) {
+				needsAuth = true;
+				break;
+			}
+			if (attempt === 0 && isOAuthTokenRejectionError(err)) {
+				await provider.invalidateCredentials("tokens");
+				await transport.close().catch(() => {});
+				transport = await createInteractiveTransport(config, provider);
+				continue;
+			}
+			await client.close().catch(() => {});
+			throw err;
+		}
+		if (needsAuth) {
+			const { code } = await raceLoginCallback(handle, options.timeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS, options.signal);
+			await transport.finishAuth(code);
+			await transport.close().catch(() => {});
+			const freshTransport = await createInteractiveTransport(config, provider);
+			await raceAbort(client.connect(freshTransport), options.signal, connectTimeoutMs, `MCP OAuth: "${config.name}" did not respond after the token exchange (within ${connectTimeoutMs}ms)`);
+		}
+		const { tools } = await raceAbort(client.listTools(), options.signal, connectTimeoutMs, `MCP OAuth: "${config.name}" did not return its tool list within ${connectTimeoutMs}ms`);
+		await client.close();
+		const tokens = provider.tokens();
+		if (!tokens) throw new Error(`MCP OAuth: login for "${config.name}" returned no tokens (server may have rejected the exchange silently)`);
+		await hooks?.callHook("mcp:auth:success", { name: config.name });
+		return {
+			tokens,
+			tools
+		};
+	} catch (err) {
+		const error = err instanceof Error ? err : new Error(String(err));
+		await hooks?.callHook("mcp:auth:error", {
+			name: config.name,
+			error
+		});
+		throw error;
+	} finally {
+		settled = true;
+		await callback?.close();
+	}
+}
+/**
+* Build an `sse` / `streamable-http` transport pre-wired with `authProvider`.
+* Mirrors the bootstrap-side `createTransport` shape but inlined here so the
+* login flow doesn't depend on the bootstrap module's private export.
+*/
+async function createInteractiveTransport(rawConfig, authProvider) {
+	const config = expandMcpConfigEnv(rawConfig);
+	if (config.transport === "sse") {
+		const { SSEClientTransport } = await import("@modelcontextprotocol/sdk/client/sse.js");
+		return new SSEClientTransport(new URL(config.url), {
+			requestInit: config.headers ? { headers: config.headers } : void 0,
+			authProvider
+		});
+	}
+	const { StreamableHTTPClientTransport } = await import("@modelcontextprotocol/sdk/client/streamableHttp.js");
+	return new StreamableHTTPClientTransport(new URL(config.url), {
+		requestInit: config.headers ? { headers: config.headers } : void 0,
+		fetch: sseToJsonFetchIfNeeded(),
+		authProvider
+	});
+}
+function isUnauthorizedError(err) {
+	if (!err || typeof err !== "object") return false;
+	const e = err;
+	if (e.name === "UnauthorizedError" || e.constructor?.name === "UnauthorizedError") return true;
+	return typeof e.message === "string" && e.message.toLowerCase().startsWith("unauthorized");
+}
+/**
+* Race `promise` against the external abort signal and a hard timeout.
+*
+* Used for phases we can't cancel from the inside (the SDK's `connect()`
+* accepts no signal). The underlying work isn't stopped — it's abandoned —
+* so callers must treat a rejection as "this attempt is over" and close
+* whatever they own. Rejects with `'OAuth login aborted'` on abort so the
+* host can tell a user cancel apart from a genuine failure.
+*/
+async function raceAbort(promise, signal, timeoutMs, timeoutMessage) {
+	if (signal?.aborted) throw new Error("OAuth login aborted");
+	promise.catch(() => {});
+	let timer;
+	let onAbort;
+	try {
+		return await new Promise((resolve, reject) => {
+			timer = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+			if (signal) {
+				onAbort = () => reject(/* @__PURE__ */ new Error("OAuth login aborted"));
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+			promise.then(resolve, reject);
+		});
+	} finally {
+		if (timer) clearTimeout(timer);
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+/**
+* Wait on the callback handle, with a hard timeout AND honor the external
+* abort signal. Unlike `callback.promise` alone, this provides a deterministic
+* failure mode for "user opened the browser then walked away" — the modal
+* doesn't hang forever waiting for a redirect that may never come.
+*/
+async function raceLoginCallback(handle, timeoutMs, signal) {
+	if (signal?.aborted) throw new Error("OAuth login aborted");
+	let timer;
+	let onAbort;
+	try {
+		return await new Promise((resolve, reject) => {
+			timer = setTimeout(() => reject(/* @__PURE__ */ new Error(`OAuth login timed out after ${timeoutMs}ms`)), timeoutMs);
+			if (signal) {
+				onAbort = () => reject(/* @__PURE__ */ new Error("OAuth login aborted"));
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+			handle.promise.then(resolve, reject);
+		});
+	} finally {
+		if (timer) clearTimeout(timer);
+		if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+//#region src/metrics.ts
+function prefixed$1(prefix, name) {
+	return prefix ? `${prefix}${name}` : name;
+}
+/**
+* Drop `undefined` entries before handing attributes to a metrics
+* backend. OTel's `@opentelemetry/api` rejects `undefined` attribute
+* values (and Prometheus / StatsD adapters silently mis-label them); the
+* helper's own API surface allows `undefined` for ergonomic call sites
+* (`{...(cond ? { foo } : {})}`-style spreads), so we strip here at the
+* boundary.
+*/
+function mergeAttrs(base, extra) {
+	const out = {};
+	if (base) {
+		for (const [k, v] of Object.entries(base)) if (v !== void 0) out[k] = v;
+	}
+	for (const [k, v] of Object.entries(extra)) if (v !== void 0) out[k] = v;
+	return out;
+}
+/**
+* Build a set of metrics hook handlers that can be installed on an agent.
+*
+* @example OpenTelemetry
+* ```ts
+* import { metrics } from '@opentelemetry/api'
+* const meter = metrics.getMeter('zidane')
+* const m = createMetricsHooks({ meter, baseAttributes: { service: 'tui' } })
+* const uninstall = m.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*/
+function createMetricsHooks(options) {
+	const ns = options.namespace;
+	const base = options.baseAttributes;
+	const onError = options.onError ?? (() => {});
+	const make = {
+		counter: (name, opts) => safeFactory(() => options.meter.createCounter(prefixed$1(ns, name), opts), name, onError),
+		histogram: (name, opts) => safeFactory(() => options.meter.createHistogram(prefixed$1(ns, name), opts), name, onError),
+		upDown: (name, opts) => safeFactory(() => options.meter.createUpDownCounter(prefixed$1(ns, name), opts), name, onError)
+	};
+	const turnDuration = make.histogram("gen_ai.client.operation.duration", {
+		unit: "ms",
+		description: "Per-turn LLM operation duration."
+	});
+	const tokenUsage = make.histogram("gen_ai.client.token.usage", {
+		unit: "tokens",
+		description: "Per-turn token usage (tagged by gen_ai.token.type)."
+	});
+	const ttft = make.histogram("gen_ai.client.time_to_first_token", {
+		unit: "ms",
+		description: "Per-turn time to first token."
+	});
+	const toolDuration = make.histogram("gen_ai.tool.duration", {
+		unit: "ms",
+		description: "Native tool execution wall clock."
+	});
+	const toolOutput = make.histogram("gen_ai.tool.output_bytes", {
+		unit: "By",
+		description: "Native tool output bytes."
+	});
+	const mcpToolDuration = make.histogram("gen_ai.mcp.tool.duration", {
+		unit: "ms",
+		description: "MCP tool execution wall clock."
+	});
+	const mcpBootstrapDuration = make.histogram("gen_ai.mcp.bootstrap.duration", {
+		unit: "ms",
+		description: "MCP server bootstrap duration."
+	});
+	const runsStarted = make.counter("gen_ai.agent.runs", { description: "Runs started." });
+	const runsCompleted = make.counter("gen_ai.agent.runs.completed", { description: "Runs completed." });
+	const aborts = make.counter("gen_ai.agent.aborts", { description: "Run abort events." });
+	const toolCalls = make.counter("gen_ai.tool.calls", { description: "Tool dispatches (tagged by outcome)." });
+	const toolErrors = make.counter("gen_ai.tool.errors", { description: "Native tool errors." });
+	const mcpToolErrors = make.counter("gen_ai.mcp.tool.errors", { description: "MCP tool errors." });
+	const streamErrors = make.counter("gen_ai.stream.errors", { description: "Provider stream errors." });
+	const validationRejects = make.counter("gen_ai.validation.rejects", { description: "Tool input validation rejects." });
+	const validationCoercions = make.counter("gen_ai.validation.coercions", { description: "Tool input auto-coercions." });
+	const gateBlocks = make.counter("gen_ai.gate.blocks", { description: "Tool-gate refusals." });
+	const budgetExceeded = make.counter("gen_ai.budget.exceeded", { description: "Per-turn byte budget exceedances." });
+	const toolBudgetExceeded = make.counter("gen_ai.tool_budget.exceeded", { description: "Per-tool dispatch budget exceedances." });
+	const pairingRepairs = make.counter("gen_ai.pairing.repairs", { description: "Tool-pairing repair counts." });
+	const oauthRefreshes = make.counter("gen_ai.oauth.refreshes", { description: "Provider OAuth credential refreshes." });
+	const mcpErrors = make.counter("gen_ai.mcp.errors", { description: "MCP server errors." });
+	const mcpAuthRequired = make.counter("gen_ai.mcp.auth.required", { description: "MCP bootstrap blocked on missing auth." });
+	const costMeter = make.counter("gen_ai.cost_usd", {
+		unit: "USD",
+		description: "Cumulative cost across turns."
+	});
+	const runsActive = make.upDown("gen_ai.agent.runs.active", { description: "In-flight agent runs." });
+	return { install(hooks) {
+		const turnStart = /* @__PURE__ */ new Map();
+		const toolStart = /* @__PURE__ */ new Map();
+		const mcpStart = /* @__PURE__ */ new Map();
+		const unregisters = [];
+		const record = (instrument, value, attrs, kind) => {
+			if (!instrument) return;
+			try {
+				instrument.record(value, mergeAttrs(base, attrs));
+			} catch (err) {
+				try {
+					onError(kind, err);
+				} catch {}
+			}
+		};
+		const add = (instrument, value, attrs, kind) => {
+			if (!instrument) return;
+			try {
+				instrument.add(value, mergeAttrs(base, attrs));
+			} catch (err) {
+				try {
+					onError(kind, err);
+				} catch {}
+			}
+		};
+		unregisters.push(hooks.hook("agent:start", (ctx) => {
+			const attrs = {
+				"gen_ai.agent.depth": ctx.depth,
+				...ctx.agentName ? { "gen_ai.agent.name": ctx.agentName } : {}
+			};
+			add(runsStarted, 1, attrs, "runs");
+			add(runsActive, 1, attrs, "runs.active");
+		}));
+		unregisters.push(hooks.hook("agent:done", () => {
+			add(runsCompleted, 1, {}, "runs.completed");
+			add(runsActive, -1, {}, "runs.active");
+			turnStart.clear();
+			toolStart.clear();
+			mcpStart.clear();
+		}));
+		unregisters.push(hooks.hook("agent:abort", () => {
+			add(aborts, 1, {}, "aborts");
+		}));
+		unregisters.push(hooks.hook("turn:before", (ctx) => {
+			turnStart.set(ctx.turnId, Date.now());
+		}));
+		unregisters.push(hooks.hook("turn:after", (ctx) => {
+			const started = turnStart.get(ctx.turnId);
+			turnStart.delete(ctx.turnId);
+			const tagsBase = {
+				"gen_ai.operation.name": "chat",
+				...ctx.usage.modelId ? { "gen_ai.response.model": ctx.usage.modelId } : {},
+				...ctx.usage.finishReason ? { "gen_ai.response.finish_reason": ctx.usage.finishReason } : {}
+			};
+			if (typeof started === "number") record(turnDuration, Date.now() - started, tagsBase, "turn.duration");
+			if (typeof ctx.usage.timeToFirstTokenMs === "number") record(ttft, ctx.usage.timeToFirstTokenMs, tagsBase, "ttft");
+			record(tokenUsage, ctx.usage.input, {
+				...tagsBase,
+				"gen_ai.token.type": "input"
+			}, "token.input");
+			record(tokenUsage, ctx.usage.output, {
+				...tagsBase,
+				"gen_ai.token.type": "output"
+			}, "token.output");
+			if (typeof ctx.usage.cacheRead === "number" && ctx.usage.cacheRead > 0) record(tokenUsage, ctx.usage.cacheRead, {
+				...tagsBase,
+				"gen_ai.token.type": "cache_read"
+			}, "token.cache_read");
+			if (typeof ctx.usage.cacheCreation === "number" && ctx.usage.cacheCreation > 0) record(tokenUsage, ctx.usage.cacheCreation, {
+				...tagsBase,
+				"gen_ai.token.type": "cache_creation"
+			}, "token.cache_creation");
+			if (typeof ctx.usage.cost === "number" && ctx.usage.cost > 0) add(costMeter, ctx.usage.cost, tagsBase, "cost");
+		}));
+		unregisters.push(hooks.hook("stream:error", (ctx) => {
+			add(streamErrors, 1, {
+				"http.response.status_code": ctx.statusCode,
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown"
+			}, "stream.error");
+		}));
+		unregisters.push(hooks.hook("tool:before", (ctx) => {
+			toolStart.set(ctx.callId, Date.now());
+		}));
+		unregisters.push(hooks.hook("tool:after", (ctx) => {
+			const started = toolStart.get(ctx.callId);
+			toolStart.delete(ctx.callId);
+			const tags = { "gen_ai.tool.name": ctx.name };
+			if (typeof started === "number") record(toolDuration, Date.now() - started, tags, "tool.duration");
+			record(toolOutput, ctx.outputBytes, tags, "tool.output_bytes");
+		}));
+		unregisters.push(hooks.hook("tool:error", (ctx) => {
+			add(toolErrors, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"error.type": ctx.error.name
+			}, "tool.errors");
+		}));
+		unregisters.push(hooks.hook("tool:cancelled", (ctx) => {
+			toolStart.delete(ctx.callId);
+		}));
+		unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+			add(toolCalls, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"outcome": ctx.outcome
+			}, "tool.calls");
+			if (ctx.outcome === "gate-block") add(gateBlocks, 1, {
+				"gen_ai.tool.name": ctx.name,
+				...ctx.reason ? { reason: ctx.reason } : {}
+			}, "gate.blocks");
+			if (ctx.outcome === "unknown") toolStart.delete(ctx.callId);
+		}));
+		unregisters.push(hooks.hook("validation:reject", (ctx) => {
+			add(validationRejects, 1, { "gen_ai.tool.name": ctx.name }, "validation.rejects");
+		}));
+		unregisters.push(hooks.hook("validation:coerce", (ctx) => {
+			add(validationCoercions, 1, {
+				"gen_ai.tool.name": ctx.name,
+				"coercions": ctx.coercions.length
+			}, "validation.coercions");
+		}));
+		unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+			add(budgetExceeded, 1, {
+				bytes: ctx.bytes,
+				budget: ctx.budget
+			}, "budget.exceeded");
+		}));
+		unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+			add(toolBudgetExceeded, 1, {
+				"gen_ai.tool.name": ctx.tool,
+				"mode": ctx.mode,
+				"count": ctx.count,
+				"max": ctx.max
+			}, "tool_budget.exceeded");
+		}));
+		unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+			add(pairingRepairs, 1, { mode: ctx.mode }, "pairing.repairs");
+		}));
+		unregisters.push(hooks.hook("oauth:refresh", (ctx) => {
+			add(oauthRefreshes, 1, {
+				provider: ctx.provider,
+				source: ctx.source
+			}, "oauth.refreshes");
+		}));
+		unregisters.push(hooks.hook("mcp:tool:before", (ctx) => {
+			mcpStart.set(ctx.callId, Date.now());
+		}));
+		unregisters.push(hooks.hook("mcp:tool:after", (ctx) => {
+			const started = mcpStart.get(ctx.callId);
+			mcpStart.delete(ctx.callId);
+			const tags = {
+				"gen_ai.mcp.server": ctx.server,
+				"gen_ai.tool.name": ctx.displayName
+			};
+			if (typeof started === "number") record(mcpToolDuration, Date.now() - started, tags, "mcp.tool.duration");
+		}));
+		unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+			mcpStart.delete(ctx.callId);
+			add(mcpToolErrors, 1, {
+				"gen_ai.mcp.server": ctx.server,
+				"gen_ai.tool.name": ctx.displayName,
+				"error.type": ctx.error.name
+			}, "mcp.tool.errors");
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:end", (ctx) => {
+			record(mcpBootstrapDuration, ctx.durationMs, {
+				"gen_ai.mcp.server": ctx.name,
+				"ok": ctx.ok
+			}, "mcp.bootstrap.duration");
+		}));
+		unregisters.push(hooks.hook("mcp:error", (ctx) => {
+			add(mcpErrors, 1, {
+				"gen_ai.mcp.server": ctx.name,
+				"error.type": ctx.error.name
+			}, "mcp.errors");
+		}));
+		unregisters.push(hooks.hook("mcp:auth:required", (ctx) => {
+			add(mcpAuthRequired, 1, {
+				"gen_ai.mcp.server": ctx.name,
+				"transport": ctx.transport,
+				"reason": ctx.reason
+			}, "mcp.auth.required");
+		}));
+		let disposed = false;
+		return function uninstall() {
+			if (disposed) return;
+			disposed = true;
+			for (const un of unregisters) try {
+				un();
+			} catch {}
+			turnStart.clear();
+			toolStart.clear();
+			mcpStart.clear();
+		};
+	} };
+}
+/**
+* Defensive factory wrapper — returns undefined when meter creation
+* throws. Lets a half-broken meter (one unsupported instrument) still
+* give partial metrics rather than collapsing the whole install.
+*/
+function safeFactory(factory, name, onError) {
+	try {
+		return factory();
+	} catch (err) {
+		try {
+			onError(`createInstrument:${name}`, err);
+		} catch {}
+		return;
+	}
+}
+//#endregion
+//#region src/mutation-validation.ts
+function defaultFailureMessage(failure) {
+	const changed = failure.batch.mutations.map((m) => `${m.displayName} ${String(m.input.path ?? m.callId)}`).join(", ");
+	const details = failure.result.message ?? failure.result.errors?.join("\n") ?? "Validation failed after the last file mutation.";
+	return `[Mutation validation failed${failure.failureCount > 1 ? ` (failure ${failure.failureCount})` : ""}] ${changed}\n${details}\nFix the validation errors with the smallest focused change.`;
+}
+function isSuccessfulMutation(outcome) {
+	return outcome === "created" || outcome === "updated" || outcome === "edited";
+}
+/**
+* Build host-side hooks for post-mutation validation without changing the
+* built-in edit/write tools. The helper only observes successful mutations
+* reported through `tool:after.outcome`; validation commands and recovery
+* prompts remain host policy.
+*/
+function createMutationValidationHooks(options) {
+	const pending = [];
+	let failureCount = 0;
+	const maxFailures = Math.max(1, Math.floor(options.maxFailuresPerRun ?? 2));
+	return {
+		"tool:after": (ctx) => {
+			if (!isSuccessfulMutation(ctx.outcome)) return;
+			pending.push({
+				turnId: ctx.turnId,
+				callId: ctx.callId,
+				tool: ctx.name,
+				displayName: ctx.displayName,
+				input: ctx.input,
+				outcome: ctx.outcome,
+				result: ctx.result
+			});
+		},
+		"tool-results:after": async (ctx) => {
+			if (pending.length === 0) return;
+			const mutations = pending.splice(0);
+			const batch = {
+				turnId: ctx.turnId,
+				mutations
+			};
+			let result;
+			try {
+				result = await options.validate(batch);
+			} catch (err) {
+				await options.onError?.(err, batch);
+				return;
+			}
+			if (!result || result.ok) return;
+			failureCount++;
+			if (failureCount > maxFailures) return;
+			const withoutMessage = {
+				batch,
+				result,
+				failureCount
+			};
+			const message = options.buildFailureMessage?.(withoutMessage) ?? defaultFailureMessage(withoutMessage);
+			await options.onFailure?.({
+				...withoutMessage,
+				message
+			});
+		},
+		"agent:done": () => {
+			pending.length = 0;
+			failureCount = 0;
+		}
+	};
+}
+//#endregion
+//#region src/tracing.ts
+/**
+* Stable keys we emit unconditionally — present in BOTH Sentry and OTel
+* conventions with identical semantics, so no `conventions` branching is
+* needed at the call site.
+*/
+const GEN_AI = {
+	system: "gen_ai.system",
+	operationName: "gen_ai.operation.name",
+	requestModel: "gen_ai.request.model",
+	responseModel: "gen_ai.response.model",
+	responseFinishReasons: "gen_ai.response.finish_reasons",
+	responseId: "gen_ai.response.id",
+	responseStreaming: "gen_ai.response.streaming",
+	responseTokensPerSecond: "gen_ai.response.tokens_per_second",
+	responseTimeToFirstTokenSeconds: "gen_ai.response.time_to_first_token",
+	responseTimeToFirstTokenMs: "gen_ai.client.time_to_first_token",
+	usageInputTokens: "gen_ai.usage.input_tokens",
+	usageOutputTokens: "gen_ai.usage.output_tokens",
+	usageTotalTokens: "gen_ai.usage.total_tokens",
+	usageInputTokensCached: "gen_ai.usage.input_tokens.cached",
+	usageInputTokensCacheWrite: "gen_ai.usage.input_tokens.cache_write",
+	usageOutputTokensReasoning: "gen_ai.usage.output_tokens.reasoning",
+	usageCacheReadInputTokens: "gen_ai.usage.cache_read_input_tokens",
+	usageCacheCreationInputTokens: "gen_ai.usage.cache_creation_input_tokens",
+	usageReasoningTokens: "gen_ai.usage.reasoning_tokens",
+	costTotalTokens: "gen_ai.cost.total_tokens",
+	costInputTokens: "gen_ai.cost.input_tokens",
+	costOutputTokens: "gen_ai.cost.output_tokens",
+	usageCostUsd: "gen_ai.usage.cost_usd",
+	toolName: "gen_ai.tool.name",
+	toolDescription: "gen_ai.tool.description",
+	toolType: "gen_ai.tool.type",
+	toolCallId: "gen_ai.tool.call.id",
+	toolCallArguments: "gen_ai.tool.call.arguments",
+	toolCallResult: "gen_ai.tool.call.result",
+	toolMessage: "gen_ai.tool.message",
+	toolInputDeprecated: "gen_ai.tool.input",
+	toolOutputDeprecated: "gen_ai.tool.output",
+	requestMaxTokens: "gen_ai.request.max_tokens",
+	requestTemperature: "gen_ai.request.temperature",
+	requestTopP: "gen_ai.request.top_p",
+	requestTopK: "gen_ai.request.top_k",
+	requestSeed: "gen_ai.request.seed",
+	requestFrequencyPenalty: "gen_ai.request.frequency_penalty",
+	requestPresencePenalty: "gen_ai.request.presence_penalty",
+	inputMessages: "gen_ai.input.messages",
+	outputMessages: "gen_ai.output.messages",
+	systemInstructions: "gen_ai.system_instructions",
+	toolDefinitions: "gen_ai.tool.definitions",
+	agentName: "gen_ai.agent.name",
+	agentRunId: "gen_ai.agent.run.id",
+	agentParentRunId: "gen_ai.agent.parent_run.id",
+	agentDepth: "gen_ai.agent.depth",
+	pipelineName: "gen_ai.pipeline.name",
+	turn: "gen_ai.agent.turn",
+	mcpServer: "gen_ai.mcp.server",
+	mcpToolCount: "gen_ai.mcp.tool_count"
+};
+/** Compose namespace prefix once. */
+function prefixed(namespace, name) {
+	return namespace ? `${namespace}/${name}` : name;
+}
+/** Drop undefined entries — tracers vary on how they render `undefined`. */
+function compact(attrs) {
+	const out = {};
+	for (const [k, v] of Object.entries(attrs)) if (v !== void 0) out[k] = v;
+	return out;
+}
+function blockToParts(block) {
+	switch (block.type) {
+		case "text": return [{
+			type: "text",
+			content: typeof block.text === "string" ? block.text : ""
+		}];
+		case "image":
+		case "audio":
+		case "video":
+		case "document": return [{
+			type: "text",
+			content: "[Blob substitute]"
+		}];
+		case "tool_call": return [{
+			type: "tool_call",
+			...typeof block.name === "string" ? { name: block.name } : {},
+			...typeof block.id === "string" ? { call_id: block.id } : {},
+			arguments: safeJson(block.input)
+		}];
+		case "tool_result": {
+			const output = block.output;
+			const text = typeof output === "string" ? output : Array.isArray(output) ? output.map((b) => b.type === "image" || b.type === "audio" || b.type === "video" || b.type === "document" ? "[Blob substitute]" : b.text ?? "").join("\n") : "";
+			return [{
+				type: "tool_result",
+				...typeof block.callId === "string" ? { call_id: block.callId } : {},
+				content: text
+			}];
+		}
+		case "thinking": return [{
+			type: "reasoning",
+			content: typeof block.text === "string" ? block.text : ""
+		}];
+		default: return [];
+	}
+}
+function messageToSentry(msg) {
+	const parts = [];
+	for (const block of msg.content) parts.push(...blockToParts(block));
+	return {
+		role: msg.role,
+		parts
+	};
+}
+function safeJson(value) {
+	try {
+		return JSON.stringify(value ?? null);
+	} catch {
+		return "\"[unserializable]\"";
+	}
+}
+/**
+* Stringify an array of `SessionMessage`s into Sentry's `gen_ai.input.messages`
+* format. Each entry's role + content is mapped via `messageToSentry`.
+* Returns `undefined` when the input is empty or unserializable.
+*/
+function stringifyMessages(messages) {
+	if (messages.length === 0) return void 0;
+	try {
+		const sentry = messages.map((m) => messageToSentry({
+			role: m.role,
+			content: m.content
+		}));
+		return JSON.stringify(sentry);
+	} catch {
+		return;
+	}
+}
+/**
+* Stringify a `StreamOptions.tools` array into Sentry's
+* `gen_ai.tool.definitions` format: `[{name, description?, parameters?}, …]`.
+*
+* The input is `unknown[]` because `StreamOptions.tools` carries the
+* provider-formatted shape (Anthropic / OpenAI / OpenAI-compat all
+* differ). We probe the three names that overlap (`name`, `description`,
+* `inputSchema` / `parameters`) and degrade gracefully otherwise.
+*/
+function stringifyToolDefs(tools) {
+	if (!tools || tools.length === 0) return void 0;
+	try {
+		return JSON.stringify(tools.map((raw) => {
+			if (!raw || typeof raw !== "object") return { name: "anonymous" };
+			const t = raw;
+			const name = typeof t.name === "string" ? t.name : "anonymous";
+			const description = typeof t.description === "string" ? t.description : void 0;
+			const parameters = t.parameters ?? t.input_schema ?? t.inputSchema;
+			return {
+				name,
+				...description ? { description } : {},
+				...parameters !== void 0 ? { parameters } : {}
+			};
+		}));
+	} catch {
+		return;
+	}
+}
+/**
+* Build the usage attribute set per the configured conventions. Sentry
+* expects `input_tokens` to include cached, with `input_tokens.cached`
+* + `input_tokens.cache_write` subkeys; OTel splits cache into
+* separate top-level keys. `'both'` emits everything.
+*/
+function buildUsageAttrs(usage, conventions) {
+	const cacheRead = usage.cacheRead ?? 0;
+	const cacheWrite = usage.cacheCreation ?? 0;
+	const inputInclCache = usage.input + cacheRead + cacheWrite;
+	const totalTokens = inputInclCache + usage.output;
+	const wantSentry = conventions === "sentry" || conventions === "both";
+	const wantOtel = conventions === "otel" || conventions === "both";
+	const out = {
+		[GEN_AI.responseModel]: usage.modelId,
+		[GEN_AI.responseFinishReasons]: usage.finishReason ? [usage.finishReason] : void 0,
+		[GEN_AI.usageOutputTokens]: usage.output,
+		[GEN_AI.usageTotalTokens]: totalTokens
+	};
+	if (wantSentry) {
+		out[GEN_AI.usageInputTokens] = inputInclCache;
+		if (cacheRead > 0) out[GEN_AI.usageInputTokensCached] = cacheRead;
+		if (cacheWrite > 0) out[GEN_AI.usageInputTokensCacheWrite] = cacheWrite;
+		if (typeof usage.thinking === "number" && usage.thinking > 0) out[GEN_AI.usageOutputTokensReasoning] = usage.thinking;
+		if (typeof usage.cost === "number") out[GEN_AI.costTotalTokens] = usage.cost;
+		if (typeof usage.timeToFirstTokenMs === "number") out[GEN_AI.responseTimeToFirstTokenSeconds] = usage.timeToFirstTokenMs / 1e3;
+	}
+	if (wantOtel) {
+		if (!wantSentry) out[GEN_AI.usageInputTokens] = usage.input;
+		if (cacheRead > 0) out[GEN_AI.usageCacheReadInputTokens] = cacheRead;
+		if (cacheWrite > 0) out[GEN_AI.usageCacheCreationInputTokens] = cacheWrite;
+		if (typeof usage.thinking === "number" && usage.thinking > 0) out[GEN_AI.usageReasoningTokens] = usage.thinking;
+		if (typeof usage.cost === "number") out[GEN_AI.usageCostUsd] = usage.cost;
+		if (typeof usage.timeToFirstTokenMs === "number") out[GEN_AI.responseTimeToFirstTokenMs] = usage.timeToFirstTokenMs;
+	}
+	return out;
+}
+/**
+* Build a set of tracing hook handlers that can be installed on an agent.
+*
+* @example Sentry
+* ```ts
+* const tracing = createTracingHooks({
+*   startSpan: (name, attrs) => Sentry.startInactiveSpan({ name, attributes: attrs }),
+* })
+* const uninstall = tracing.install(agent.hooks)
+* try { await agent.run({ prompt }) }
+* finally { uninstall() }
+* ```
+*
+* @example OpenTelemetry with parent-context propagation
+* ```ts
+* import { trace, context, propagation } from '@opentelemetry/api'
+*
+* const tracer = trace.getTracer('zidane')
+* const tracing = createTracingHooks({
+*   startSpan: (name, attrs, parentCtx) => {
+*     const ctx = parentCtx ? propagation.extract(context.active(), parentCtx) : context.active()
+*     return tracer.startSpan(name, { attributes: attrs }, ctx)
+*   },
+*   getActiveTraceContext: () => {
+*     const carrier: Record<string, string> = {}
+*     propagation.inject(context.active(), carrier)
+*     return carrier
+*   },
+* })
+* ```
+*/
+function createTracingHooks(options) {
+	const namespace = options.namespace;
+	const legacy = options.legacyAttributes ?? true;
+	const conventions = options.conventions ?? "sentry";
+	const wantSentry = conventions === "sentry" || conventions === "both";
+	const captureContent = options.captureMessageContent !== false;
+	const onError = options.onError ?? (() => {});
+	return { install(hooks) {
+		const runSpans = /* @__PURE__ */ new Map();
+		const turnSpans = /* @__PURE__ */ new Map();
+		const toolSpans = /* @__PURE__ */ new Map();
+		const mcpSpans = /* @__PURE__ */ new Map();
+		const spawnSpans = /* @__PURE__ */ new Map();
+		const bootstrapSpans = /* @__PURE__ */ new Map();
+		let activeSystem;
+		const turnTrack = /* @__PURE__ */ new Map();
+		let activeRunSpan;
+		function safeStartSpan(name, attrs, parentContext) {
+			try {
+				return options.startSpan(prefixed(namespace, name), compact(attrs), parentContext);
+			} catch (err) {
+				try {
+					onError("startSpan", err);
+				} catch {}
+				return;
+			}
+		}
+		function safeSetAttrs(span, attrs) {
+			if (!span?.setAttributes) return;
+			try {
+				span.setAttributes(compact(attrs));
+			} catch (err) {
+				try {
+					onError("setAttributes", err);
+				} catch {}
+			}
+		}
+		function safeEnd(map, key) {
+			const span = map.get(key);
+			if (!span) return;
+			try {
+				span.end();
+			} catch (err) {
+				try {
+					onError("end", err);
+				} catch {}
+			}
+			map.delete(key);
+		}
+		function endAll(map) {
+			for (const [, span] of map) try {
+				span.end();
+			} catch (err) {
+				try {
+					onError("end", err);
+				} catch {}
+			}
+			map.clear();
+		}
+		function safeAddEvent(span, name, attrs) {
+			if (!span) return;
+			if (typeof span.addEvent === "function") {
+				try {
+					span.addEvent(name, compact(attrs));
+				} catch (err) {
+					try {
+						onError("addEvent", err);
+					} catch {}
+				}
+				return;
+			}
+			safeSetAttrs(span, Object.fromEntries(Object.entries(compact(attrs)).map(([k, v]) => [`event.${name}.${k}`, v])));
+		}
+		function redact(kind, value, meta) {
+			if (typeof options.redact !== "function") return value;
+			try {
+				return options.redact(kind, value, meta);
+			} catch (err) {
+				try {
+					onError("redact", err);
+				} catch {}
+				return value;
+			}
+		}
+		const unregisters = [];
+		unregisters.push(hooks.hook("agent:start", (ctx) => {
+			activeSystem = ctx.providerName;
+			const span = safeStartSpan(`invoke_agent ${ctx.agentName && ctx.agentName.length > 0 ? ctx.agentName : "agent"}`, {
+				[GEN_AI.operationName]: "invoke_agent",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.agentName]: ctx.agentName,
+				[GEN_AI.agentRunId]: ctx.runId,
+				[GEN_AI.agentParentRunId]: ctx.parentRunId,
+				[GEN_AI.agentDepth]: ctx.depth,
+				"sentry.op": "gen_ai.invoke_agent",
+				...legacy ? {
+					runId: ctx.runId,
+					parentRunId: ctx.parentRunId,
+					agentName: ctx.agentName,
+					depth: ctx.depth
+				} : {}
+			}, ctx.tracingContext);
+			if (span) {
+				runSpans.set(ctx.runId, span);
+				activeRunSpan = span;
+			}
+		}));
+		unregisters.push(hooks.hook("agent:done", (stats) => {
+			const usageAttrs = buildUsageAttrs({
+				input: stats.totalIn,
+				output: stats.totalOut,
+				cacheRead: stats.totalCacheRead,
+				cacheCreation: stats.totalCacheCreation,
+				cost: stats.cost,
+				timeToFirstTokenMs: stats.timeTillFirstTokenMs
+			}, conventions);
+			for (const [, span] of runSpans) safeSetAttrs(span, {
+				...usageAttrs,
+				[GEN_AI.turn]: stats.turns,
+				"gen_ai.agent.elapsed_ms": stats.elapsed,
+				...legacy ? {
+					totalIn: stats.totalIn,
+					totalOut: stats.totalOut,
+					totalCacheRead: stats.totalCacheRead,
+					totalCacheCreation: stats.totalCacheCreation,
+					cost: stats.cost,
+					turns: stats.turns,
+					elapsed: stats.elapsed
+				} : {}
+			});
+			endAll(runSpans);
+			endAll(turnSpans);
+			endAll(toolSpans);
+			endAll(mcpSpans);
+			endAll(spawnSpans);
+			endAll(bootstrapSpans);
+			activeRunSpan = void 0;
+			activeSystem = void 0;
+			turnTrack.clear();
+		}));
+		unregisters.push(hooks.hook("agent:abort", () => {
+			for (const [, span] of runSpans) safeSetAttrs(span, { "gen_ai.agent.status": "aborted" });
+		}));
+		unregisters.push(hooks.hook("turn:before", (ctx) => {
+			const requestedModel = ctx.options.model;
+			const baseAttrs = {
+				[GEN_AI.operationName]: "chat",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.requestModel]: requestedModel,
+				[GEN_AI.turn]: ctx.turn,
+				[GEN_AI.responseStreaming]: true,
+				[GEN_AI.requestMaxTokens]: ctx.options.maxTokens,
+				"sentry.op": "gen_ai.chat",
+				"gen_ai.agent.turn_id": ctx.turnId,
+				...legacy ? {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				} : {}
+			};
+			if (captureContent) {
+				const systemText = ctx.options.system;
+				if (systemText) baseAttrs[GEN_AI.systemInstructions] = redact("system", systemText, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+				const inputMsgs = stringifyMessages(ctx.options.messages);
+				if (inputMsgs) baseAttrs[GEN_AI.inputMessages] = redact("prompt", inputMsgs, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+				const toolDefs = stringifyToolDefs(ctx.options.tools);
+				if (toolDefs) baseAttrs[GEN_AI.toolDefinitions] = toolDefs;
+			}
+			const span = safeStartSpan(`chat${requestedModel ? ` ${requestedModel}` : ""}`, baseAttrs);
+			if (span) {
+				turnSpans.set(ctx.turnId, span);
+				turnTrack.set(ctx.turnId, { startedAt: Date.now() });
+			}
+		}));
+		unregisters.push(hooks.hook("stream:start", (ctx) => {
+			safeAddEvent(turnSpans.get(ctx.turnId), "gen_ai.stream.start", { startedAt: ctx.startedAt });
+		}));
+		unregisters.push(hooks.hook("turn:after", (ctx) => {
+			const span = turnSpans.get(ctx.turnId);
+			const tracked = turnTrack.get(ctx.turnId);
+			turnTrack.delete(ctx.turnId);
+			let tokensPerSecond;
+			if (tracked && ctx.usage.output > 0) {
+				const elapsedMs = Date.now() - tracked.startedAt;
+				if (elapsedMs > 0) tokensPerSecond = ctx.usage.output / elapsedMs * 1e3;
+			}
+			const usageAttrs = buildUsageAttrs(ctx.usage, conventions);
+			const cumInputTokens = wantSentry ? ctx.cumulativeUsage.input + ctx.cumulativeUsage.cacheRead + ctx.cumulativeUsage.cacheCreation : ctx.cumulativeUsage.input;
+			const attrs = {
+				...usageAttrs,
+				[GEN_AI.responseTokensPerSecond]: tokensPerSecond,
+				"gen_ai.agent.cumulative.input_tokens": cumInputTokens,
+				"gen_ai.agent.cumulative.output_tokens": ctx.cumulativeUsage.output,
+				"gen_ai.agent.cumulative.total_tokens": cumInputTokens + ctx.cumulativeUsage.output,
+				"gen_ai.agent.cumulative.cache_read_input_tokens": ctx.cumulativeUsage.cacheRead,
+				"gen_ai.agent.cumulative.cache_creation_input_tokens": ctx.cumulativeUsage.cacheCreation,
+				"gen_ai.agent.cumulative.cost_usd": ctx.cumulativeUsage.cost,
+				"gen_ai.agent.cumulative.turns": ctx.cumulativeUsage.turns,
+				...legacy ? {
+					inputTokens: ctx.usage.input,
+					outputTokens: ctx.usage.output,
+					finishReason: ctx.usage.finishReason,
+					modelId: ctx.usage.modelId
+				} : {}
+			};
+			if (captureContent && ctx.message && ctx.message.role !== "system" && ctx.message.role !== "command") {
+				const outputMsgs = stringifyMessages([{
+					role: ctx.message.role,
+					content: ctx.message.content
+				}]);
+				if (outputMsgs) attrs[GEN_AI.outputMessages] = redact("stream-text", outputMsgs, {
+					turnId: ctx.turnId,
+					turn: ctx.turn
+				});
+			}
+			safeSetAttrs(span, attrs);
+			safeEnd(turnSpans, ctx.turnId);
+		}));
+		unregisters.push(hooks.hook("stream:error", (ctx) => {
+			const span = turnSpans.get(ctx.turnId);
+			const message = ctx.err instanceof Error ? ctx.err.message : String(ctx.err);
+			safeSetAttrs(span, {
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown",
+				"error.message": message,
+				"http.response.status_code": ctx.statusCode,
+				"gen_ai.request.id": ctx.requestId
+			});
+			safeAddEvent(span, "gen_ai.stream.error", {
+				"error.type": ctx.err instanceof Error ? ctx.err.name : "unknown",
+				"error.message": message,
+				"http.response.status_code": ctx.statusCode,
+				"gen_ai.request.id": ctx.requestId
+			});
+		}));
+		unregisters.push(hooks.hook("tool:before", (ctx) => {
+			const span = safeStartSpan(`execute_tool ${ctx.displayName}`, {
+				[GEN_AI.operationName]: "execute_tool",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolType]: "function",
+				[GEN_AI.toolCallId]: ctx.callId,
+				"sentry.op": "gen_ai.execute_tool",
+				"gen_ai.tool.display_name": ctx.displayName,
+				"gen_ai.agent.turn_id": ctx.turnId,
+				"gen_ai.agent.depth": ctx.depth,
+				"gen_ai.agent.run.id": ctx.runId,
+				"gen_ai.agent.parent_run.id": ctx.parentRunId,
+				...legacy ? {
+					toolName: ctx.name,
+					displayName: ctx.displayName,
+					turnId: ctx.turnId,
+					callId: ctx.callId
+				} : {}
+			});
+			if (span) {
+				toolSpans.set(ctx.callId, span);
+				if (captureContent) try {
+					const redacted = redact("tool-input", JSON.stringify(ctx.input), {
+						toolName: ctx.name,
+						displayName: ctx.displayName,
+						callId: ctx.callId,
+						turnId: ctx.turnId
+					});
+					const attrs = {};
+					if (wantSentry) attrs[GEN_AI.toolCallArguments] = redacted;
+					if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolInputDeprecated] = redacted;
+					safeSetAttrs(span, attrs);
+				} catch {}
+			}
+		}));
+		unregisters.push(hooks.hook("tool:after", (ctx) => {
+			const span = toolSpans.get(ctx.callId);
+			safeSetAttrs(span, {
+				"gen_ai.tool.output_bytes": ctx.outputBytes,
+				"gen_ai.tool.coercions": ctx.coercions?.length ?? 0
+			});
+			if (captureContent && typeof ctx.result === "string") {
+				const redacted = redact("tool-result", ctx.result, {
+					toolName: ctx.name,
+					callId: ctx.callId
+				});
+				const attrs = {};
+				if (wantSentry) attrs[GEN_AI.toolCallResult] = redacted;
+				if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolOutputDeprecated] = redacted;
+				safeSetAttrs(span, attrs);
+			}
+			safeEnd(toolSpans, ctx.callId);
+		}));
+		unregisters.push(hooks.hook("tool:error", (ctx) => {
+			safeSetAttrs(toolSpans.get(ctx.callId), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(toolSpans, ctx.callId);
+		}));
+		unregisters.push(hooks.hook("tool:dispatched", (ctx) => {
+			if (ctx.outcome === "gate-block") safeAddEvent(activeRunSpan, "gen_ai.gate.block", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				reason: ctx.reason
+			});
+			else if (ctx.outcome === "gate-substitute") safeAddEvent(activeRunSpan, "gen_ai.gate.substitute", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+			else if (ctx.outcome === "unknown") safeAddEvent(activeRunSpan, "gen_ai.tool.unknown", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+			else if (ctx.outcome === "invalid-input") safeAddEvent(activeRunSpan, "gen_ai.tool.invalid_input", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId
+			});
+		}));
+		unregisters.push(hooks.hook("validation:reject", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.validation.reject", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("validation:coerce", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.validation.coerce", {
+				[GEN_AI.toolName]: ctx.name,
+				[GEN_AI.toolCallId]: ctx.callId,
+				coercions: ctx.coercions
+			});
+		}));
+		unregisters.push(hooks.hook("budget:exceeded", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.budget.exceeded", {
+				turnId: ctx.turnId,
+				bytes: ctx.bytes,
+				budget: ctx.budget
+			});
+		}));
+		unregisters.push(hooks.hook("tool-budget:exceeded", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.tool_budget.exceeded", {
+				[GEN_AI.toolName]: ctx.tool,
+				turnId: ctx.turnId,
+				count: ctx.count,
+				max: ctx.max,
+				mode: ctx.mode
+			});
+		}));
+		unregisters.push(hooks.hook("pairing:repair", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.pairing.repair", {
+				mode: ctx.mode,
+				callId: ctx.callId,
+				turnId: ctx.turnId
+			});
+		}));
+		unregisters.push(hooks.hook("oauth:refresh", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.oauth.refresh", {
+				provider: ctx.provider,
+				providerId: ctx.providerId,
+				source: ctx.source
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:tool:before", (ctx) => {
+			const span = safeStartSpan(`execute_tool ${ctx.server}.${ctx.tool}`, {
+				[GEN_AI.operationName]: "execute_tool",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.toolName]: ctx.displayName,
+				[GEN_AI.toolType]: "extension",
+				[GEN_AI.toolCallId]: ctx.callId,
+				[GEN_AI.mcpServer]: ctx.server,
+				"sentry.op": "gen_ai.execute_tool",
+				"gen_ai.mcp.tool": ctx.tool,
+				"gen_ai.agent.turn_id": ctx.turnId,
+				"gen_ai.agent.run.id": ctx.runId,
+				...legacy ? {
+					server: ctx.server,
+					tool: ctx.tool,
+					displayName: ctx.displayName,
+					turnId: ctx.turnId,
+					callId: ctx.callId
+				} : {}
+			});
+			if (span) {
+				mcpSpans.set(ctx.callId, span);
+				if (captureContent) try {
+					const redacted = redact("mcp-tool-input", JSON.stringify(ctx.input), {
+						server: ctx.server,
+						tool: ctx.tool,
+						callId: ctx.callId
+					});
+					const attrs = {};
+					if (wantSentry) attrs[GEN_AI.toolCallArguments] = redacted;
+					if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolInputDeprecated] = redacted;
+					safeSetAttrs(span, attrs);
+				} catch {}
+			}
+		}));
+		unregisters.push(hooks.hook("mcp:tool:after", (ctx) => {
+			const span = mcpSpans.get(ctx.callId);
+			safeSetAttrs(span, { "gen_ai.tool.output_bytes": ctx.outputBytes });
+			if (captureContent && typeof ctx.result === "string") {
+				const redacted = redact("mcp-tool-result", ctx.result, {
+					server: ctx.server,
+					tool: ctx.tool,
+					callId: ctx.callId
+				});
+				const attrs = {};
+				if (wantSentry) attrs[GEN_AI.toolCallResult] = redacted;
+				if (conventions === "otel" || conventions === "both") attrs[GEN_AI.toolOutputDeprecated] = redacted;
+				safeSetAttrs(span, attrs);
+			}
+			safeEnd(mcpSpans, ctx.callId);
+		}));
+		unregisters.push(hooks.hook("mcp:tool:error", (ctx) => {
+			safeSetAttrs(mcpSpans.get(ctx.callId), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(mcpSpans, ctx.callId);
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:start", (ctx) => {
+			const span = safeStartSpan(`mcp.bootstrap ${ctx.name}`, {
+				[GEN_AI.operationName]: "mcp.bootstrap",
+				[GEN_AI.system]: activeSystem,
+				[GEN_AI.mcpServer]: ctx.name,
+				"gen_ai.mcp.transport": ctx.transport
+			});
+			if (span) bootstrapSpans.set(ctx.name, span);
+		}));
+		unregisters.push(hooks.hook("mcp:bootstrap:end", (ctx) => {
+			const span = bootstrapSpans.get(ctx.name);
+			const ok = ctx.ok;
+			safeSetAttrs(span, {
+				"gen_ai.mcp.bootstrap.duration_ms": ctx.durationMs,
+				"gen_ai.mcp.bootstrap.ok": ok,
+				...ok ? {
+					[GEN_AI.mcpToolCount]: ctx.toolCount,
+					"gen_ai.mcp.lazy": ctx.lazy,
+					"gen_ai.mcp.cached": ctx.cached
+				} : {
+					"error.type": ctx.error.name,
+					"error.message": ctx.error.message
+				}
+			});
+			safeEnd(bootstrapSpans, ctx.name);
+		}));
+		unregisters.push(hooks.hook("mcp:auth:required", (ctx) => {
+			safeAddEvent(bootstrapSpans.get(ctx.name) ?? activeRunSpan, "gen_ai.mcp.auth.required", {
+				server: ctx.name,
+				transport: ctx.transport,
+				reason: ctx.reason
+			});
+		}));
+		unregisters.push(hooks.hook("mcp:error", (ctx) => {
+			safeAddEvent(activeRunSpan, "gen_ai.mcp.error", {
+				"server": ctx.name,
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+		}));
+		unregisters.push(hooks.hook("spawn:before", (ctx) => {
+			const span = safeStartSpan(`handoff to ${ctx.task.length > 60 ? `${ctx.task.slice(0, 57)}…` : ctx.task}`, {
+				[GEN_AI.operationName]: "handoff",
+				[GEN_AI.system]: activeSystem,
+				"sentry.op": "gen_ai.handoff",
+				"gen_ai.agent.spawn.id": ctx.id,
+				"gen_ai.agent.spawn.task": ctx.task,
+				"gen_ai.agent.depth": ctx.depth
+			});
+			if (span) spawnSpans.set(ctx.id, span);
+			if (typeof options.getActiveTraceContext === "function" && ctx.tracingContext) {
+				let carrier;
+				try {
+					carrier = options.getActiveTraceContext();
+				} catch (err) {
+					try {
+						onError("getActiveTraceContext", err);
+					} catch {}
+				}
+				if (carrier) for (const [k, v] of Object.entries(carrier)) ctx.tracingContext[k] = v;
+			}
+		}));
+		unregisters.push(hooks.hook("spawn:complete", (ctx) => {
+			const span = spawnSpans.get(ctx.id);
+			const childUsage = buildUsageAttrs({
+				input: ctx.stats.totalIn,
+				output: ctx.stats.totalOut,
+				cacheRead: ctx.stats.totalCacheRead,
+				cacheCreation: ctx.stats.totalCacheCreation,
+				cost: ctx.stats.cost
+			}, conventions);
+			safeSetAttrs(span, {
+				"gen_ai.agent.spawn.status": ctx.status ?? "completed",
+				"gen_ai.agent.spawn.depth": ctx.depth,
+				...childUsage
+			});
+			safeEnd(spawnSpans, ctx.id);
+		}));
+		unregisters.push(hooks.hook("spawn:error", (ctx) => {
+			safeSetAttrs(spawnSpans.get(ctx.id), {
+				"error.type": ctx.error.name,
+				"error.message": ctx.error.message
+			});
+			safeEnd(spawnSpans, ctx.id);
+		}));
+		let disposed = false;
+		return function uninstall() {
+			if (disposed) return;
+			disposed = true;
+			for (const un of unregisters) try {
+				un();
+			} catch {}
+			endAll(runSpans);
+			endAll(turnSpans);
+			endAll(toolSpans);
+			endAll(mcpSpans);
+			endAll(spawnSpans);
+			endAll(bootstrapSpans);
+			activeRunSpan = void 0;
+		};
+	} };
+}
+/**
+* OpenTelemetry Gen AI semantic-convention attribute keys used by the
+* built-in tracer. Exported so consumers integrating with raw OTel SDKs
+* (instead of going through `createTracingHooks`) can stay aligned with
+* the names the harness itself emits.
+*/
+const GEN_AI_ATTRIBUTES = GEN_AI;
+//#endregion
+export { zodToJsonSchema as A, tokenEndingAtCursor as C, shouldAutoGenerateTitle as D, generateSessionTitle as E, parseCommandInvocation as F, localReliabilityBehavior as I, commandBlocksToContent as M, commandSteps as N, isStandardSchema as O, executeCommand as P, resolveInlineSuggestion as S, cleanTitle as T, resolveExtensionDocsDir as _, loginMcpServer as a, createPathAutocompleteProvider as b, SKILL_EDIT_METADATA_KEY as c, buildZidaneExtensionSkill as d, buildZidaneSkillEditSkill as f, readSkillEditMarker as g, extensionScaffold as h, createMetricsHooks as i, commandBlockToEvent as j, resolveSchemaInput as k, ZIDANE_EXTENSION_SKILL_NAME as l, extensionDirForCwd as m, createTracingHooks as n, startOAuthCallback as o, editSessionMetadata as p, createMutationValidationHooks as r, EXTENSION_EDIT_METADATA_KEY as s, GEN_AI_ATTRIBUTES as t, ZIDANE_SKILL_EDIT_SKILL_NAME as u, withZidaneExtensionSkill as v, generateStructuredData as w, patchInlineGhost as x, withZidaneSkillEditSkill as y };
+
+//# sourceMappingURL=src-DzzhE2YO.js.map