@robota-sdk/agent-tools 3.0.0-beta.76 → 3.0.0-beta.78

package/dist/node/index.cjs

@@ -25,6 +25,7 @@ let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 let _robota_sdk_agent_core = require("@robota-sdk/agent-core");
 let node_child_process = require("node:child_process");
+let _robota_sdk_agent_process = require("@robota-sdk/agent-process");
 let zod = require("zod");
 let node_crypto = require("node:crypto");
 let fast_glob = require("fast-glob");
@@ -445,111 +446,6 @@ function validateToolParameters(parameters, schemaRequired, schemaProperties, ad
 	};
 }
 //#endregion
-//#region src/implementations/function-tool/schema-converter.ts
-/**
-* Convert Zod schema to JSON Schema format with safe undefined handling
-*/
-function zodToJsonSchema(schema, options = {}) {
-	const properties = {};
-	const required = [];
-	const schemaDef = schema._def;
-	if (!schemaDef) throw new Error("Zod schema is missing _def; cannot convert to JSON schema.");
-	if (schemaDef.typeName === "ZodObject" && schemaDef.shape) {
-		const shape = typeof schemaDef.shape === "function" ? schemaDef.shape() : schemaDef.shape;
-		for (const [key, typeObj] of Object.entries(shape)) {
-			properties[key] = convertZodTypeToProperty(typeObj);
-			if (isRequiredField(typeObj)) required.push(key);
-		}
-	}
-	return {
-		type: "object",
-		properties,
-		required,
-		...(options.allowAdditionalProperties || schemaDef.unknownKeys === "passthrough") && { additionalProperties: true }
-	};
-}
-/**
-* Convert individual Zod type to parameter schema with safe undefined handling
-*/
-function convertZodTypeToProperty(typeObj) {
-	const typeDef = typeObj._def;
-	if (!typeDef) throw new Error("Zod type is missing _def; cannot convert to JSON schema.");
-	const base = {};
-	if (typeDef.description) base.description = typeDef.description;
-	switch (typeDef.typeName) {
-		case "ZodString": return {
-			type: "string",
-			...base
-		};
-		case "ZodNumber": return {
-			type: "number",
-			...base
-		};
-		case "ZodBoolean": return {
-			type: "boolean",
-			...base
-		};
-		case "ZodArray":
-			if (!typeDef.type) throw new Error("ZodArray is missing item type; cannot convert to JSON schema.");
-			return {
-				type: "array",
-				items: convertZodTypeToProperty(typeDef.type),
-				...base
-			};
-		case "ZodObject": return {
-			type: "object",
-			...base
-		};
-		case "ZodEnum": {
-			const enumValues = typeDef.values;
-			if (!enumValues || !Array.isArray(enumValues)) throw new Error("ZodEnum is missing enum values; cannot convert to JSON schema.");
-			return {
-				type: "string",
-				enum: enumValues,
-				...base
-			};
-		}
-		case "ZodOptional":
-			if (typeDef.innerType) return {
-				...convertZodTypeToProperty(typeDef.innerType),
-				...base
-			};
-			throw new Error("ZodOptional is missing innerType; cannot convert to JSON schema.");
-		case "ZodNullable":
-			if (typeDef.innerType) return {
-				...convertZodTypeToProperty(typeDef.innerType),
-				...base
-			};
-			throw new Error("ZodNullable is missing innerType; cannot convert to JSON schema.");
-		case "ZodDefault":
-			if (typeDef.innerType) return {
-				...convertZodTypeToProperty(typeDef.innerType),
-				...base
-			};
-			throw new Error("ZodDefault is missing innerType; cannot convert to JSON schema.");
-		case "ZodRecord":
-			if (typeDef.valueType) return {
-				type: "object",
-				additionalProperties: convertZodTypeToProperty(typeDef.valueType),
-				...base
-			};
-			return {
-				type: "object",
-				additionalProperties: { type: "string" },
-				...base
-			};
-		default: throw new Error(`Unsupported Zod type: ${String(typeDef.typeName)}`);
-	}
-}
-/**
-* Check if a Zod field is required (not optional or nullable)
-*/
-function isRequiredField(typeObj) {
-	const typeDef = typeObj._def;
-	if (!typeDef) throw new Error("Zod schema is missing _def; cannot determine required fields.");
-	return typeDef.typeName !== "ZodOptional" && typeDef.typeName !== "ZodNullable" && typeDef.typeName !== "ZodDefault";
-}
-//#endregion
 //#region src/implementations/function-tool.ts
 /**
 * Function tool implementation
@@ -653,39 +549,59 @@ function createZodFunctionTool(name, description, zodSchema, fn) {
 	const schema = {
 		name,
 		description,
-		parameters: zodToJsonSchema(zodSchema)
+		parameters: (0, _robota_sdk_agent_core.zodToJsonSchema)(zodSchema)
 	};
 	const wrappedFn = async (parameters, context) => {
 		const parseResult = zodSchema.safeParse(parameters);
 		if (!parseResult.success) throw new _robota_sdk_agent_core.ValidationError(`Zod validation failed: ${parseResult.error}`);
-		const result = await fn(parseResult.data || parameters, context);
+		const result = await fn(parseResult.data, context);
 		return typeof result === "string" ? result : JSON.stringify(result);
 	};
 	return new FunctionTool(schema, wrappedFn);
 }
 //#endregion
-//#region src/builtins/bash-tool.ts
+//#region src/builtins/shell-tool.ts
 /**
-* BashTool — execute shell commands via child_process.spawn
+* ShellTool — execute a host shell command via child_process.spawn (TERM-008).
+*
+* Cross-platform: the shell is resolved per OS through `resolvePlatformShell()` (POSIX `sh`/`bash`,
+* Windows PowerShell). The tool name is `Shell` and its description is built dynamically from the
+* resolved shell so the model is told the active shell/OS and writes the right syntax.
 *
-* Returns TToolResult JSON string. Non-zero exit is returned as success:true
-* with exitCode set, matching Claude Code behaviour (the command ran, it just
-* exited non-zero — the LLM can decide what to do with that information).
+* Returns an IToolInvocationResult JSON string. A non-zero exit is returned as success:true with
+* exitCode set (the command ran, it just exited non-zero — the LLM decides what to do with that).
 */
+/** POSIX children are spawned detached so a process-group kill reaps grandchildren (CORE-023). */
+const SPAWN_DETACHED = process.platform !== "win32";
 const DEFAULT_TIMEOUT_MS$2 = 12e4;
-const BashSchema = zod.z.object({
-	command: zod.z.string().describe("The bash command to execute"),
+const ShellSchema = zod.z.object({
+	command: zod.z.string().describe("The shell command to execute"),
 	timeout: zod.z.number().optional().describe("Optional timeout in milliseconds (max 600000). Default is 120000 (2 minutes)"),
 	workingDirectory: zod.z.string().optional().describe("Working directory for the command. Defaults to the current working directory")
 });
-/**
-* Run a shell command and return stdout + stderr.
-* Resolves with the TToolResult JSON string.
-*/
-async function runBash(args, options = {}) {
-	const { command, timeout: rawTimeout = DEFAULT_TIMEOUT_MS$2, workingDirectory } = args;
-	const timeout = Math.min(rawTimeout, 6e5);
-	if (options.sandboxClient) try {
+/** Build the OS-aware tool description so the model writes syntax the host shell can run. */
+function buildShellToolDescription(shell) {
+	return [
+		`Executes a command in the host shell and returns its output.`,
+		``,
+		`Active shell: ${shell.label}. ${shell.syntaxHint}`,
+		``,
+		`The working directory persists between commands, but shell state does not.`,
+		``,
+		`IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands. Instead, use the appropriate dedicated tool:`,
+		` - File search: Use Glob (NOT find or ls)`,
+		` - Content search: Use Grep (NOT grep or rg)`,
+		` - Read files: Use Read (NOT cat/head/tail)`,
+		` - Edit files: Use Edit (NOT sed/awk)`,
+		``,
+		`For simple commands, keep the description brief (5-10 words). For complex commands, include enough context to clarify what the command does.`,
+		``,
+		`Output is limited to 30,000 characters. Longer output will be middle-truncated.`
+	].join("\n");
+}
+/** Run a shell command through the sandbox client, surfacing failures as a structured result. */
+async function runInSandbox(command, timeout, workingDirectory, options) {
+	try {
 		const sandboxResult = await options.sandboxClient.run(command, {
 			timeoutMs: timeout,
 			workingDirectory
@@ -704,20 +620,37 @@ async function runBash(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
+}
+/**
+* Run a shell command and return stdout + stderr.
+* Resolves with the IToolInvocationResult JSON string.
+*/
+async function runShell(args, options = {}, signal) {
+	const { command, timeout: rawTimeout = DEFAULT_TIMEOUT_MS$2, workingDirectory } = args;
+	const timeout = Math.min(rawTimeout, 6e5);
+	if (options.sandboxClient) return runInSandbox(command, timeout, workingDirectory, options);
+	const shell = (0, _robota_sdk_agent_core.resolvePlatformShell)();
+	if (signal?.aborted) return JSON.stringify({
+		success: false,
+		output: "",
+		error: "Aborted before start"
+	});
 	return new Promise((resolve) => {
 		const stdoutChunks = [];
 		const stderrChunks = [];
 		let timedOut = false;
 		let settled = false;
-		const child = (0, node_child_process.spawn)("sh", ["-c", command], {
+		const child = (0, node_child_process.spawn)(shell.command, shell.commandArgs(command), {
 			cwd: workingDirectory ?? process.cwd(),
 			env: process.env,
 			stdio: [
 				"pipe",
 				"pipe",
 				"pipe"
-			]
+			],
+			detached: SPAWN_DETACHED
 		});
+		child.stdin?.end();
 		child.stdout.on("data", (chunk) => {
 			stdoutChunks.push(chunk);
 		});
@@ -726,7 +659,7 @@ async function runBash(args, options = {}) {
 		});
 		const timer = setTimeout(() => {
 			timedOut = true;
-			child.kill("SIGTERM");
+			(0, _robota_sdk_agent_process.killProcessTree)(child, { processGroup: SPAWN_DETACHED });
 			settle({
 				success: false,
 				output: Buffer.concat(stdoutChunks).toString("utf8"),
@@ -737,8 +670,18 @@ async function runBash(args, options = {}) {
 			if (settled) return;
 			settled = true;
 			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
 			resolve(JSON.stringify(result));
 		}
+		function onAbort() {
+			(0, _robota_sdk_agent_process.killProcessTree)(child, { processGroup: SPAWN_DETACHED });
+			settle({
+				success: false,
+				output: Buffer.concat(stdoutChunks).toString("utf8"),
+				error: "Aborted"
+			});
+		}
+		signal?.addEventListener("abort", onAbort, { once: true });
 		child.on("error", (err) => {
 			settle({
 				success: false,
@@ -768,21 +711,37 @@ async function runBash(args, options = {}) {
 	});
 }
 /**
-* Create a BashTool instance — register with Robota agent tools registry.
+* Build a host-shell command tool under a given registered name. Both `Shell` and the
+* model-familiar `Bash` are registered as aliases of this one OS-aware implementation
+* (TERM-008): the shell is resolved per OS and the description names the active shell so the
+* model writes the right syntax regardless of which alias it calls.
 */
-function createBashTool(options = {}) {
-	return createZodFunctionTool("Bash", "Executes a given bash command and returns its output.\n\nThe working directory persists between commands, but shell state does not.\n\nIMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands. Instead, use the appropriate dedicated tool:\n - File search: Use Glob (NOT find or ls)\n - Content search: Use Grep (NOT grep or rg)\n - Read files: Use Read (NOT cat/head/tail)\n - Edit files: Use Edit (NOT sed/awk)\n\nFor simple commands, keep the description brief (5-10 words). For complex commands, include enough context to clarify what the command does.\n\nOutput is limited to 30,000 characters. Longer output will be middle-truncated.", BashSchema, async (params) => {
-		return runBash(params, options);
+function createHostShellTool(name, options) {
+	return createZodFunctionTool(name, buildShellToolDescription((0, _robota_sdk_agent_core.resolvePlatformShell)()), ShellSchema, async (params, context) => {
+		return runShell(params, options, context?.signal);
 	});
 }
 /**
-* BashTool instance — register with Robota agent tools registry.
+* Create a `Shell` tool instance — register with the Robota agent tools registry.
+* The description is resolved at creation time for the host's active shell.
 */
+function createShellTool(options = {}) {
+	return createHostShellTool("Shell", options);
+}
+/**
+* Create a `Bash` tool instance — the model-familiar alias of the same OS-aware shell tool.
+*/
+function createBashTool(options = {}) {
+	return createHostShellTool("Bash", options);
+}
+/** `Shell` tool instance — register with the Robota agent tools registry. */
+const shellTool = createShellTool();
+/** `Bash` tool instance — model-familiar alias of {@link shellTool}. */
 const bashTool = createBashTool();
 //#endregion
 //#region src/builtins/path-guard.ts
 /**
-* Returns a JSON-serialized TToolResult error when filePath is outside cwd.
+* Returns a JSON-serialized IToolInvocationResult error when filePath is outside cwd.
 * Returns undefined when the path is within cwd or cwd is not set.
 */
 function checkPathWithinCwd(filePath, cwd) {
@@ -1317,7 +1276,7 @@ function classifyFetchError(err) {
 	if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") return `Network error: SSL certificate error (${code}). The server's certificate is invalid. Do not retry with the same URL.`;
 	return `Network error: ${err.message} Check that the URL is correct and the server is reachable.`;
 }
-async function runWebFetch(args) {
+async function runWebFetch(args, signal) {
 	const { url, headers } = args;
 	try {
 		new URL(url);
@@ -1332,12 +1291,13 @@ async function runWebFetch(args) {
 	try {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS$1);
+		const fetchSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
 		const response = await fetch(url, {
 			headers: {
 				"User-Agent": "Robota-CLI/3.0",
 				...headers ?? {}
 			},
-			signal: controller.signal,
+			signal: fetchSignal,
 			redirect: "follow"
 		});
 		clearTimeout(timeout);
@@ -1375,7 +1335,7 @@ async function runWebFetch(args) {
 		return JSON.stringify(result);
 	}
 }
-const webFetchTool = createZodFunctionTool("WebFetch", "Fetch a URL and return its content as text. HTML pages are converted to plain text.", WebFetchSchema, async (params) => runWebFetch(params));
+const webFetchTool = createZodFunctionTool("WebFetch", "Fetch a URL and return its content as text. HTML pages are converted to plain text.", WebFetchSchema, async (params, context) => runWebFetch(params, context?.signal));
 //#endregion
 //#region src/builtins/web-search-tool.ts
 /**
@@ -1390,7 +1350,7 @@ const WebSearchSchema = zod.z.object({
 	query: zod.z.string().describe("The search query"),
 	limit: zod.z.number().optional().describe(`Maximum number of results to return (default: ${DEFAULT_LIMIT})`)
 });
-async function runWebSearch(args) {
+async function runWebSearch(args, signal) {
 	const { query, limit = DEFAULT_LIMIT } = args;
 	const apiKey = process.env["BRAVE_API_KEY"];
 	if (!apiKey) return JSON.stringify({
@@ -1401,6 +1361,7 @@ async function runWebSearch(args) {
 	try {
 		const controller = new AbortController();
 		const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+		const fetchSignal = signal ? AbortSignal.any([controller.signal, signal]) : controller.signal;
 		const params = new URLSearchParams({
 			q: query,
 			count: String(Math.min(limit, 20))
@@ -1411,7 +1372,7 @@ async function runWebSearch(args) {
 				"Accept-Encoding": "gzip",
 				"X-Subscription-Token": apiKey
 			},
-			signal: controller.signal
+			signal: fetchSignal
 		});
 		clearTimeout(timeout);
 		if (!response.ok) {
@@ -1441,26 +1402,139 @@ async function runWebSearch(args) {
 		return JSON.stringify(result);
 	}
 }
-const webSearchTool = createZodFunctionTool("WebSearch", "Search the web and return results with title, URL, and snippet.", WebSearchSchema, async (params) => runWebSearch(params));
+const webSearchTool = createZodFunctionTool("WebSearch", "Search the web and return results with title, URL, and snippet.", WebSearchSchema, async (params, context) => runWebSearch(params, context?.signal));
+//#endregion
+//#region src/builtins/ask-user-question-tool.ts
+/**
+* AskUserQuestionTool — let the model ask the user structured questions mid-turn (CMD-005).
+*
+* Built on the CMD-004 ask seam: each question maps onto the `IActionRequest` SSOT and is issued
+* through the injected `IToolExecutionContext.ask` port; the attached environment renders it (Ink
+* dialog, web modal, programmatic pre-answer) and the answers return as the tool result.
+*
+* Contract points (spec CMD-005):
+* - 1–4 questions per call, asked sequentially (the channel's ask queue renders one at a time).
+* - Cancellation is data, not an exception: a dismissed question yields `{ cancelled: true }` and the
+*   remaining unasked questions of the same call are marked cancelled too (no per-item re-prompt).
+* - No `context.ask` (headless/automation): returns `{ unavailable: true, reason }` — never a silent
+*   guess, never a thrown error, so the model can continue autonomously.
+*/
+const MAX_QUESTIONS = 4;
+const QuestionSchema = zod.z.object({
+	question: zod.z.string().min(1).describe("The complete question to ask the user."),
+	header: zod.z.string().optional().describe("Very short topic label for the question (e.g. \"Auth method\")."),
+	options: zod.z.array(zod.z.union([zod.z.string().min(1).describe("Display text of this choice."), zod.z.object({
+		label: zod.z.string().min(1).describe("Display text of this choice."),
+		description: zod.z.string().optional().describe("What choosing this option means.")
+	})])).optional().describe("Predefined choices (strings or {label, description}). Omit for pure free text."),
+	multiSelect: zod.z.boolean().optional().describe("Allow selecting multiple options (default: single select)."),
+	allowFreeText: zod.z.boolean().optional().describe("Allow a typed custom answer besides the options (default: true).")
+});
+const AskUserQuestionSchema = zod.z.object({ questions: zod.z.array(QuestionSchema).min(1).max(MAX_QUESTIONS).describe(`Questions to ask the user (1-${MAX_QUESTIONS}), rendered one at a time.`) });
+const ASK_USER_QUESTION_DESCRIPTION = [
+	"Ask the user one or more structured questions and wait for their answers.",
+	"",
+	"Use this when you are blocked on a decision only the user can make — ambiguous requirements,",
+	"mutually exclusive approaches, or choices with real trade-offs. Do not use it for decisions with",
+	"a conventional default or facts you can verify yourself.",
+	"",
+	`Provide 1-${MAX_QUESTIONS} questions. Each question offers predefined options and/or free text:`,
+	" - options + default: user picks one option (or types a custom answer unless allowFreeText: false)",
+	" - multiSelect: true: user may pick several options",
+	" - no options: pure free-text entry",
+	"",
+	"The result is a JSON array with one entry per question: the selected option labels in `values`",
+	"and/or the typed answer in `text`, or `cancelled: true` if the user dismissed the question.",
+	"If no interactive user is attached (headless run), the result is `{ unavailable: true }` —",
+	"continue autonomously with your best judgment and say what you assumed."
+].join("\n");
+function toActionRequest(question) {
+	const options = (question.options ?? []).map((option) => typeof option === "string" ? { label: option } : option);
+	const multi = question.multiSelect === true && options.length > 1;
+	return {
+		id: `ask_${(0, node_crypto.randomUUID)()}`,
+		title: question.question,
+		...question.header !== void 0 ? { description: question.header } : {},
+		...options.length > 0 ? { options: options.map((o) => ({
+			value: o.label,
+			label: o.label,
+			...o.description !== void 0 ? { description: o.description } : {}
+		})) } : {},
+		minSelect: options.length > 0 ? 1 : 0,
+		maxSelect: multi ? options.length : 1,
+		allowFreeText: question.allowFreeText !== false || options.length === 0
+	};
+}
+async function askQuestions(args, ask) {
+	const answers = [];
+	let dismissed = false;
+	for (const question of args.questions) {
+		if (dismissed) {
+			answers.push({
+				question: question.question,
+				cancelled: true
+			});
+			continue;
+		}
+		const response = await ask(toActionRequest(question));
+		if (response.type === "cancelled") {
+			dismissed = true;
+			answers.push({
+				question: question.question,
+				cancelled: true
+			});
+			continue;
+		}
+		answers.push({
+			question: question.question,
+			values: [...response.values],
+			...response.text !== void 0 ? { text: response.text } : {}
+		});
+	}
+	return { answers };
+}
+/**
+* Create an `AskUserQuestion` tool instance — register with the Robota agent tools registry.
+*/
+function createAskUserQuestionTool() {
+	return createZodFunctionTool("AskUserQuestion", ASK_USER_QUESTION_DESCRIPTION, AskUserQuestionSchema, async (params, context) => {
+		const args = params;
+		const ask = context?.ask;
+		const output = ask ? await askQuestions(args, ask) : {
+			unavailable: true,
+			reason: "no interactive user attached"
+		};
+		const result = {
+			success: true,
+			output: JSON.stringify(output)
+		};
+		return JSON.stringify(result);
+	});
+}
+/** `AskUserQuestion` tool instance — register with the Robota agent tools registry. */
+const askUserQuestionTool = createAskUserQuestionTool();
 //#endregion
 exports.E2BSandboxClient = E2BSandboxClient;
 exports.FunctionTool = FunctionTool;
 exports.InMemorySandboxClient = InMemorySandboxClient;
 exports.ToolRegistry = ToolRegistry;
 exports.applyWorkspaceManifest = applyWorkspaceManifest;
+exports.askUserQuestionTool = askUserQuestionTool;
 exports.bashTool = bashTool;
+exports.createAskUserQuestionTool = createAskUserQuestionTool;
 exports.createBashTool = createBashTool;
 exports.createEditTool = createEditTool;
 exports.createFunctionTool = createFunctionTool;
 exports.createReadTool = createReadTool;
+exports.createShellTool = createShellTool;
 exports.createWriteTool = createWriteTool;
 exports.createZodFunctionTool = createZodFunctionTool;
 exports.editTool = editTool;
 exports.globTool = globTool;
 exports.grepTool = grepTool;
 exports.readTool = readTool;
+exports.shellTool = shellTool;
 exports.validateWorkspaceManifestPath = validateWorkspaceManifestPath;
 exports.webFetchTool = webFetchTool;
 exports.webSearchTool = webSearchTool;
 exports.writeTool = writeTool;
-exports.zodToJsonSchema = zodToJsonSchema;

package/dist/node/index.d.ts

@@ -1,10 +1,11 @@
 import { IEventService, IFunctionTool, IParameterValidationResult, ITool, IToolExecutionContext, IToolRegistry, IToolResult, IToolSchema, TToolExecutor, TToolParameters, TUniversalValue } from "@robota-sdk/agent-core";
+import { TypeOf, ZodType } from "zod";
 
 //#region src/types/tool-result.d.ts
 /**
  * Result returned by a CLI tool invocation
  */
-interface TToolResult {
+interface IToolInvocationResult {
   success: boolean;
   output: string;
   error?: string;
@@ -233,70 +234,6 @@ declare class ToolRegistry implements IToolRegistry {
   private validateToolSchema;
 }
 //#endregion
-//#region src/implementations/function-tool/types.d.ts
-/**
- * Zod schema compatibility types
- *
- * Widened to `unknown` so that actual Zod schemas (ZodObject<...>) are structurally
- * assignable without `as unknown as IZodSchema` casts at call sites.
- */
-interface IZodParseResult {
-  success: boolean;
-  data?: unknown;
-  error?: unknown;
-}
-interface IZodSchemaDef {
-  typeName?: string;
-  innerType?: IZodSchema;
-  valueType?: IZodSchema;
-  checks?: Array<{
-    kind: string;
-    value?: TUniversalValue;
-  }>;
-  shape?: () => Record<string, IZodSchema>;
-  type?: IZodSchema;
-  values?: TUniversalValue[];
-  description?: string;
-  unknownKeys?: 'passthrough' | 'strip' | 'strict';
-}
-interface IZodSchema {
-  parse(value: unknown): unknown;
-  safeParse(value: unknown): IZodParseResult;
-  _def?: IZodSchemaDef;
-}
-/**
- * Parameter type validation options
- */
-interface IFunctionToolValidationOptions {
-  strict?: boolean;
-  allowUnknown?: boolean;
-  validateTypes?: boolean;
-}
-/**
- * Schema conversion options
- */
-interface ISchemaConversionOptions {
-  includeDescription?: boolean;
-  strictTypes?: boolean;
-  allowAdditionalProperties?: boolean;
-}
-/**
- * Tool execution metadata
- */
-interface IFunctionToolExecutionMetadata {
-  executionTime: number;
-  toolName: string;
-  parameters: TToolParameters;
-}
-/**
- * Tool result with metadata
- */
-interface IFunctionToolResult {
-  success: boolean;
-  data: TUniversalValue;
-  metadata?: IFunctionToolExecutionMetadata;
-}
-//#endregion
 //#region src/implementations/function-tool.d.ts
 /**
  * Function tool implementation
@@ -348,22 +285,47 @@ declare function createFunctionTool(name: string, description: string, parameter
 /**
  * Helper function to create a function tool from Zod schema
  */
-declare function createZodFunctionTool(name: string, description: string, zodSchema: IZodSchema, fn: TToolExecutor): FunctionTool;
+declare function createZodFunctionTool<S extends ZodType>(name: string, description: string, zodSchema: S, fn: TToolExecutor<TypeOf<S>>): FunctionTool;
 //#endregion
-//#region src/implementations/function-tool/schema-converter.d.ts
+//#region src/implementations/function-tool/types.d.ts
+/**
+ * Parameter type validation options
+ */
+interface IFunctionToolValidationOptions {
+  strict?: boolean;
+  allowUnknown?: boolean;
+  validateTypes?: boolean;
+}
 /**
- * Convert Zod schema to JSON Schema format with safe undefined handling
+ * Tool execution metadata
  */
-declare function zodToJsonSchema(schema: IZodSchema, options?: ISchemaConversionOptions): IToolSchema['parameters'];
+interface IFunctionToolExecutionMetadata {
+  executionTime: number;
+  toolName: string;
+  parameters: TToolParameters;
+}
+/**
+ * Tool result with metadata
+ */
+interface IFunctionToolResult {
+  success: boolean;
+  data: TUniversalValue;
+  metadata?: IFunctionToolExecutionMetadata;
+}
 //#endregion
-//#region src/builtins/bash-tool.d.ts
+//#region src/builtins/shell-tool.d.ts
 /**
- * Create a BashTool instance — register with Robota agent tools registry.
+ * Create a `Shell` tool instance — register with the Robota agent tools registry.
+ * The description is resolved at creation time for the host's active shell.
  */
-declare function createBashTool(options?: ISandboxToolOptions): FunctionTool;
+declare function createShellTool(options?: ISandboxToolOptions): FunctionTool;
 /**
- * BashTool instance — register with Robota agent tools registry.
+ * Create a `Bash` tool instance — the model-familiar alias of the same OS-aware shell tool.
  */
+declare function createBashTool(options?: ISandboxToolOptions): FunctionTool;
+/** `Shell` tool instance — register with the Robota agent tools registry. */
+declare const shellTool: FunctionTool;
+/** `Bash` tool instance — model-familiar alias of {@link shellTool}. */
 declare const bashTool: FunctionTool;
 //#endregion
 //#region src/builtins/read-tool.d.ts
@@ -436,5 +398,13 @@ declare const webFetchTool: FunctionTool;
  */
 declare const webSearchTool: FunctionTool;
 //#endregion
-export { E2BSandboxClient, FunctionTool, type IE2BSandboxAdapter, type IE2BSandboxClientOptions, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type IInMemorySandboxClientOptions, type ISandboxClient, type ISandboxRunOptions, type ISandboxRunResult, type ISandboxToolOptions, type ISchemaConversionOptions, type IWorkspaceManifest, type IWorkspaceManifestAppliedEntry, type IWorkspaceManifestApplyOptions, type IWorkspaceManifestApplyResult, type IWorkspaceManifestAzureBlobMountEntry, type IWorkspaceManifestDirectoryEntry, type IWorkspaceManifestFileEntry, type IWorkspaceManifestGcsMountEntry, type IWorkspaceManifestGitRepositoryEntry, type IWorkspaceManifestLocalDirectoryEntry, type IWorkspaceManifestLocalFileEntry, type IWorkspaceManifestPermissions, type IWorkspaceManifestR2MountEntry, type IWorkspaceManifestS3MountEntry, type IZodParseResult, type IZodSchema, type IZodSchemaDef, InMemorySandboxClient, type TInMemorySandboxRunHandler, type TToolResult, type TWorkspaceManifestApplyStatus, type TWorkspaceManifestEntry, ToolRegistry, applyWorkspaceManifest, bashTool, createBashTool, createEditTool, createFunctionTool, createReadTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };
+//#region src/builtins/ask-user-question-tool.d.ts
+/**
+ * Create an `AskUserQuestion` tool instance — register with the Robota agent tools registry.
+ */
+declare function createAskUserQuestionTool(): FunctionTool;
+/** `AskUserQuestion` tool instance — register with the Robota agent tools registry. */
+declare const askUserQuestionTool: FunctionTool;
+//#endregion
+export { E2BSandboxClient, FunctionTool, type IE2BSandboxAdapter, type IE2BSandboxClientOptions, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type IInMemorySandboxClientOptions, type ISandboxClient, type ISandboxRunOptions, type ISandboxRunResult, type ISandboxToolOptions, type IToolInvocationResult, type IWorkspaceManifest, type IWorkspaceManifestAppliedEntry, type IWorkspaceManifestApplyOptions, type IWorkspaceManifestApplyResult, type IWorkspaceManifestAzureBlobMountEntry, type IWorkspaceManifestDirectoryEntry, type IWorkspaceManifestFileEntry, type IWorkspaceManifestGcsMountEntry, type IWorkspaceManifestGitRepositoryEntry, type IWorkspaceManifestLocalDirectoryEntry, type IWorkspaceManifestLocalFileEntry, type IWorkspaceManifestPermissions, type IWorkspaceManifestR2MountEntry, type IWorkspaceManifestS3MountEntry, InMemorySandboxClient, type TInMemorySandboxRunHandler, type TWorkspaceManifestApplyStatus, type TWorkspaceManifestEntry, ToolRegistry, applyWorkspaceManifest, askUserQuestionTool, bashTool, createAskUserQuestionTool, createBashTool, createEditTool, createFunctionTool, createReadTool, createShellTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, shellTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool };
 //# sourceMappingURL=index.d.ts.map