@caupulican/pi-adaptative 0.81.35 → 0.81.37

package/dist/core/tools/python.d.ts

@@ -0,0 +1,64 @@
+import type { AgentTool } from "@caupulican/pi-agent-core";
+import type { TruncationResult } from "@caupulican/pi-agent-core/node";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+import { type PythonRuntimeOutcome } from "../python-runtime.ts";
+export declare const DEFAULT_PYTHON_TIMEOUT_SECONDS = 30;
+export declare const MAX_PYTHON_TIMEOUT_SECONDS = 300;
+export declare const MAX_PYTHON_OUTPUT_BYTES = 200000;
+declare const pythonSchema: Type.TObject<{
+    code: Type.TOptional<Type.TString>;
+    scriptPath: Type.TOptional<Type.TString>;
+    args: Type.TOptional<Type.TArray<Type.TString>>;
+    cwd: Type.TOptional<Type.TString>;
+    timeoutSeconds: Type.TOptional<Type.TNumber>;
+    maxOutputBytes: Type.TOptional<Type.TNumber>;
+}>;
+export type PythonToolInput = Static<typeof pythonSchema>;
+export interface PythonToolDetails {
+    mode: "code" | "script";
+    cwd: string;
+    uvPath: string;
+    pythonPath: string;
+    scriptPath?: string;
+    args: string[];
+    exitCode: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    stdoutTruncation?: TruncationResult;
+    stderrTruncation?: TruncationResult;
+    stdoutOutputPath?: string;
+    stderrOutputPath?: string;
+    stdoutOutputError?: string;
+    stderrOutputError?: string;
+}
+export interface PythonExecutionRequest {
+    python: string;
+    args: string[];
+    cwd: string;
+    stdin?: string;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    env: NodeJS.ProcessEnv;
+    onStdout: (chunk: Buffer) => void;
+    onStderr: (chunk: Buffer) => void;
+}
+export interface PythonExecutionResult {
+    exitCode: number | null;
+    reason: "exited" | "aborted" | "timeout";
+    signal: string | null;
+}
+export interface PythonOperations {
+    exec(request: PythonExecutionRequest): Promise<PythonExecutionResult>;
+}
+export interface PythonToolOptions {
+    resolveRuntime?: () => Promise<PythonRuntimeOutcome>;
+    operations?: PythonOperations;
+    /** Override only for tests or embedded runtimes; production uses the process work directory. */
+    outputDirectory?: string;
+}
+export declare function resolvePythonToolPath(base: string, requested: string, platform?: NodeJS.Platform): string;
+export declare function createPythonToolDefinition(baseCwd: string, options?: PythonToolOptions): ToolDefinition<typeof pythonSchema, PythonToolDetails>;
+export declare function createPythonTool(baseCwd: string, options?: PythonToolOptions): AgentTool<typeof pythonSchema>;
+export {};
+//# sourceMappingURL=python.d.ts.map

package/dist/core/tools/python.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.d.ts","sourceRoot":"","sources":["../../../src/core/tools/python.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAuB,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAKtF,eAAO,MAAM,8BAA8B,KAAK,CAAC;AACjD,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAC9C,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAI/C,QAAA,MAAM,YAAY;;;;;;;EAsCjB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,YAAY,CAAC,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,QAAQ,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACrC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,CAAC,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACtE;AAED,MAAM,WAAW,iBAAiB;IACjC,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACrD,UAAU,CAAC,EAAE,gBAAgB,CAAC;IAC9B,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;CACzB;AAMD,wBAAgB,qBAAqB,CACpC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC1C,MAAM,CAER;AAsDD,wBAAgB,0BAA0B,CACzC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,iBAAsB,GAC7B,cAAc,CAAC,OAAO,YAAY,EAAE,iBAAiB,CAAC,CAoJxD;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,SAAS,CAAC,OAAO,YAAY,CAAC,CAE7G","sourcesContent":["import { stat } from \"node:fs/promises\";\nimport { posix, win32 } from \"node:path\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport type { TruncationResult } from \"@caupulican/pi-agent-core/node\";\nimport { Text } from \"@caupulican/pi-tui\";\nimport { type Static, Type } from \"typebox\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"../python-runtime.ts\";\nimport { withExclusiveMutationBarrier } from \"./file-mutation-queue.ts\";\nimport { OutputAccumulator } from \"./output-accumulator.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nexport const DEFAULT_PYTHON_TIMEOUT_SECONDS = 30;\nexport const MAX_PYTHON_TIMEOUT_SECONDS = 300;\nexport const MAX_PYTHON_OUTPUT_BYTES = 200_000;\nconst MIN_PYTHON_OUTPUT_BYTES = 1_000;\nconst PYTHON_KILL_GRACE_MS = 2_000;\n\nconst pythonSchema = Type.Object(\n\t{\n\t\tcode: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Python code to execute on stdin. Provide exactly one of code or scriptPath.\",\n\t\t\t\tmaxLength: 200_000,\n\t\t\t}),\n\t\t),\n\t\tscriptPath: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Python script path. Relative paths resolve from cwd; one leading @ is ignored.\",\n\t\t\t\tmaxLength: 32_768,\n\t\t\t}),\n\t\t),\n\t\targs: Type.Optional(\n\t\t\tType.Array(Type.String({ maxLength: 16_384 }), {\n\t\t\t\tdescription: \"Arguments passed directly to Python after '-' or scriptPath; no shell interpolation.\",\n\t\t\t\tmaxItems: 256,\n\t\t\t}),\n\t\t),\n\t\tcwd: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Working directory. Defaults to Pi's cwd; relative paths resolve from Pi's cwd.\",\n\t\t\t\tmaxLength: 32_768,\n\t\t\t}),\n\t\t),\n\t\ttimeoutSeconds: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tdescription: `Wall-clock timeout. Defaults to ${DEFAULT_PYTHON_TIMEOUT_SECONDS} seconds and is capped at ${MAX_PYTHON_TIMEOUT_SECONDS}.`,\n\t\t\t}),\n\t\t),\n\t\tmaxOutputBytes: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tdescription: `Maximum returned bytes per stream before full output spills to a work artifact. Maximum ${MAX_PYTHON_OUTPUT_BYTES}.`,\n\t\t\t}),\n\t\t),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type PythonToolInput = Static<typeof pythonSchema>;\n\nexport interface PythonToolDetails {\n\tmode: \"code\" | \"script\";\n\tcwd: string;\n\tuvPath: string;\n\tpythonPath: string;\n\tscriptPath?: string;\n\targs: string[];\n\texitCode: number | null;\n\tsignal: string | null;\n\ttimedOut: boolean;\n\tstdoutTruncation?: TruncationResult;\n\tstderrTruncation?: TruncationResult;\n\tstdoutOutputPath?: string;\n\tstderrOutputPath?: string;\n\tstdoutOutputError?: string;\n\tstderrOutputError?: string;\n}\n\nexport interface PythonExecutionRequest {\n\tpython: string;\n\targs: string[];\n\tcwd: string;\n\tstdin?: string;\n\ttimeoutMs: number;\n\tsignal?: AbortSignal;\n\tenv: NodeJS.ProcessEnv;\n\tonStdout: (chunk: Buffer) => void;\n\tonStderr: (chunk: Buffer) => void;\n}\n\nexport interface PythonExecutionResult {\n\texitCode: number | null;\n\treason: \"exited\" | \"aborted\" | \"timeout\";\n\tsignal: string | null;\n}\n\nexport interface PythonOperations {\n\texec(request: PythonExecutionRequest): Promise<PythonExecutionResult>;\n}\n\nexport interface PythonToolOptions {\n\tresolveRuntime?: () => Promise<PythonRuntimeOutcome>;\n\toperations?: PythonOperations;\n\t/** Override only for tests or embedded runtimes; production uses the process work directory. */\n\toutputDirectory?: string;\n}\n\nfunction stripAtPrefix(value: string): string {\n\treturn value.startsWith(\"@\") ? value.slice(1) : value;\n}\n\nexport function resolvePythonToolPath(\n\tbase: string,\n\trequested: string,\n\tplatform: NodeJS.Platform = process.platform,\n): string {\n\treturn (platform === \"win32\" ? win32 : posix).resolve(base, stripAtPrefix(requested));\n}\n\nasync function resolveWorkingDirectory(baseCwd: string, requested?: string): Promise<string> {\n\tconst cwd = requested ? resolvePythonToolPath(baseCwd, requested) : baseCwd;\n\tconst entry = await stat(cwd).catch(() => {\n\t\tthrow new Error(`cwd does not exist: ${cwd}`);\n\t});\n\tif (!entry.isDirectory()) throw new Error(`cwd is not a directory: ${cwd}`);\n\treturn cwd;\n}\n\nasync function resolveScriptPath(cwd: string, requested: string): Promise<string> {\n\tconst scriptPath = resolvePythonToolPath(cwd, requested);\n\tconst entry = await stat(scriptPath).catch(() => {\n\t\tthrow new Error(`scriptPath does not exist: ${scriptPath}`);\n\t});\n\tif (!entry.isFile()) throw new Error(`scriptPath is not a file: ${scriptPath}`);\n\treturn scriptPath;\n}\n\nfunction clampInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) return fallback;\n\treturn Math.max(minimum, Math.min(maximum, Math.trunc(value)));\n}\n\nfunction createLocalPythonOperations(): PythonOperations {\n\treturn {\n\t\tasync exec(request) {\n\t\t\tif (request.signal?.aborted) throw new Error(\"Python execution aborted before start\");\n\t\t\tconst child = spawnProcess(request.python, request.args, {\n\t\t\t\tcwd: request.cwd,\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tenv: request.env,\n\t\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\t});\n\t\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => request.onStdout(chunk));\n\t\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => request.onStderr(chunk));\n\t\t\tchild.stdin?.end(request.stdin ?? \"\");\n\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\tkillGraceMs: PYTHON_KILL_GRACE_MS,\n\t\t\t\tsignal: request.signal,\n\t\t\t\ttimeoutMs: request.timeoutMs,\n\t\t\t});\n\t\t\treturn { exitCode: terminal.code, reason: terminal.reason, signal: child.signalCode };\n\t\t},\n\t};\n}\n\nfunction renderStreamNotice(label: string, path: string | undefined, error: string | undefined): string | undefined {\n\tif (path) return `[${label} truncated; full output: ${path}]`;\n\tif (error) return `[${label} truncated; full-output artifact failed: ${error}]`;\n\treturn undefined;\n}\n\nexport function createPythonToolDefinition(\n\tbaseCwd: string,\n\toptions: PythonToolOptions = {},\n): ToolDefinition<typeof pythonSchema, PythonToolDetails> {\n\tconst resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));\n\tconst operations = options.operations ?? createLocalPythonOperations();\n\treturn {\n\t\tname: \"python\",\n\t\tlabel: \"python\",\n\t\tdescription: `Run a bounded Python snippet or script without a shell. Pi resolves Python through uv, defaults to a ${DEFAULT_PYTHON_TIMEOUT_SECONDS}-second wall-clock timeout (maximum ${MAX_PYTHON_TIMEOUT_SECONDS}), streams bounded stdout/stderr, and spills truncated full output to the process work directory rather than the repository.`,\n\t\tpromptSnippet: \"Run bounded Python snippets or scripts through Pi's uv-managed runtime.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Prefer python for bounded scripts, data shaping, structured transformations, and cross-platform logic when it is clearer than a shell pipeline.\",\n\t\t\t\"Prefer read/edit/write for small exact source edits. For Python file transformations, preserve encoding and newline style, write atomically, and verify the resulting diff.\",\n\t\t\t\"Keep work scoped: avoid recursive home/filesystem scans, pass explicit roots and filters, and request a larger timeout only when the bounded workload justifies it.\",\n\t\t\t\"Do not use python for destructive deletion, credentials, publish/push/release, or long-running services without explicit user approval.\",\n\t\t],\n\t\tparameters: pythonSchema,\n\t\tasync execute(_toolCallId, input, signal) {\n\t\t\tconst hasCode = typeof input.code === \"string\";\n\t\t\tconst hasScript = typeof input.scriptPath === \"string\" && input.scriptPath.trim().length > 0;\n\t\t\tif (hasCode === hasScript) throw new Error(\"Provide exactly one of code or scriptPath.\");\n\t\t\tconst cwd = await resolveWorkingDirectory(baseCwd, input.cwd);\n\t\t\tconst scriptPath = hasScript ? await resolveScriptPath(cwd, input.scriptPath as string) : undefined;\n\t\t\tconst runtime = await resolveRuntime();\n\t\t\tif (runtime.status !== \"ready\") throw new Error(runtime.reason);\n\t\t\tconst args = input.args ? [...input.args] : [];\n\t\t\tconst timeoutSeconds = clampInteger(\n\t\t\t\tinput.timeoutSeconds,\n\t\t\t\tDEFAULT_PYTHON_TIMEOUT_SECONDS,\n\t\t\t\t1,\n\t\t\t\tMAX_PYTHON_TIMEOUT_SECONDS,\n\t\t\t);\n\t\t\tconst maxOutputBytes = clampInteger(\n\t\t\t\tinput.maxOutputBytes,\n\t\t\t\t50 * 1024,\n\t\t\t\tMIN_PYTHON_OUTPUT_BYTES,\n\t\t\t\tMAX_PYTHON_OUTPUT_BYTES,\n\t\t\t);\n\t\t\tconst accumulatorOptions = {\n\t\t\t\tmaxBytes: maxOutputBytes,\n\t\t\t\t...(options.outputDirectory ? { tempDirectory: options.outputDirectory } : {}),\n\t\t\t};\n\t\t\tconst stdout = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: \"pi-python-stdout\" });\n\t\t\tconst stderr = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: \"pi-python-stderr\" });\n\t\t\tconst finishStreams = () => {\n\t\t\t\tstdout.finish();\n\t\t\t\tstderr.finish();\n\t\t\t\treturn {\n\t\t\t\t\tstdout: stdout.snapshot({ persistIfTruncated: true }),\n\t\t\t\t\tstderr: stderr.snapshot({ persistIfTruncated: true }),\n\t\t\t\t};\n\t\t\t};\n\t\t\tlet execution: PythonExecutionResult;\n\t\t\ttry {\n\t\t\t\texecution = await withExclusiveMutationBarrier(() =>\n\t\t\t\t\toperations.exec({\n\t\t\t\t\t\tpython: runtime.pythonPath,\n\t\t\t\t\t\targs: scriptPath ? [\"-B\", scriptPath, ...args] : [\"-B\", \"-\", ...args],\n\t\t\t\t\t\tcwd,\n\t\t\t\t\t\tstdin: hasCode ? input.code : undefined,\n\t\t\t\t\t\ttimeoutMs: timeoutSeconds * 1000,\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\tenv: {\n\t\t\t\t\t\t\t...process.env,\n\t\t\t\t\t\t\tPI_PYTHON_TOOL: \"1\",\n\t\t\t\t\t\t\tPYTHONDONTWRITEBYTECODE: \"1\",\n\t\t\t\t\t\t\tPYTHONIOENCODING: \"utf-8\",\n\t\t\t\t\t\t\tPYTHONUNBUFFERED: \"1\",\n\t\t\t\t\t\t\tPYTHONUTF8: \"1\",\n\t\t\t\t\t\t},\n\t\t\t\t\t\tonStdout: (chunk) => stdout.append(chunk),\n\t\t\t\t\t\tonStderr: (chunk) => stderr.append(chunk),\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\tconst snapshots = finishStreams();\n\t\t\t\tconst sections: string[] = [];\n\t\t\t\tif (snapshots.stdout.content) sections.push(snapshots.stdout.content.trimEnd());\n\t\t\t\tif (snapshots.stderr.content) sections.push(`[stderr]\\n${snapshots.stderr.content.trimEnd()}`);\n\t\t\t\tconst stdoutNotice = renderStreamNotice(\n\t\t\t\t\t\"stdout\",\n\t\t\t\t\tsnapshots.stdout.fullOutputPath,\n\t\t\t\t\tsnapshots.stdout.fullOutputError,\n\t\t\t\t);\n\t\t\t\tconst stderrNotice = renderStreamNotice(\n\t\t\t\t\t\"stderr\",\n\t\t\t\t\tsnapshots.stderr.fullOutputPath,\n\t\t\t\t\tsnapshots.stderr.fullOutputError,\n\t\t\t\t);\n\t\t\t\tif (stdoutNotice) sections.push(stdoutNotice);\n\t\t\t\tif (stderrNotice) sections.push(stderrNotice);\n\t\t\t\tconst status = `[python exitCode=${execution.exitCode ?? \"null\"}${execution.signal ? `; signal=${execution.signal}` : \"\"}]`;\n\t\t\t\tsections.push(status);\n\t\t\t\tconst text = sections.join(\"\\n\\n\");\n\t\t\t\tif (execution.reason === \"timeout\")\n\t\t\t\t\tthrow new Error(`${text}\\n\\nPython timed out after ${timeoutSeconds} seconds`);\n\t\t\t\tif (execution.reason === \"aborted\") throw new Error(`${text}\\n\\nPython execution aborted`);\n\t\t\t\tif (execution.exitCode !== 0) {\n\t\t\t\t\tconst termination = execution.signal\n\t\t\t\t\t\t? `signal ${execution.signal}`\n\t\t\t\t\t\t: `code ${execution.exitCode ?? \"unknown\"}`;\n\t\t\t\t\tthrow new Error(`${text}\\n\\nPython exited with ${termination}`);\n\t\t\t\t}\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\tmode: scriptPath ? \"script\" : \"code\",\n\t\t\t\t\t\tcwd,\n\t\t\t\t\t\tuvPath: runtime.uvPath,\n\t\t\t\t\t\tpythonPath: runtime.pythonPath,\n\t\t\t\t\t\tscriptPath,\n\t\t\t\t\t\targs,\n\t\t\t\t\t\texitCode: execution.exitCode,\n\t\t\t\t\t\tsignal: execution.signal,\n\t\t\t\t\t\ttimedOut: false,\n\t\t\t\t\t\t...(snapshots.stdout.truncation.truncated ? { stdoutTruncation: snapshots.stdout.truncation } : {}),\n\t\t\t\t\t\t...(snapshots.stderr.truncation.truncated ? { stderrTruncation: snapshots.stderr.truncation } : {}),\n\t\t\t\t\t\tstdoutOutputPath: snapshots.stdout.fullOutputPath,\n\t\t\t\t\t\tstderrOutputPath: snapshots.stderr.fullOutputPath,\n\t\t\t\t\t\tstdoutOutputError: snapshots.stdout.fullOutputError,\n\t\t\t\t\t\tstderrOutputError: snapshots.stderr.fullOutputError,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t} finally {\n\t\t\t\tawait Promise.all([stdout.closeTempFile(), stderr.closeTempFile()]);\n\t\t\t}\n\t\t},\n\t\trenderCall(args, theme) {\n\t\t\tconst mode = args.scriptPath ? args.scriptPath : \"code\";\n\t\t\treturn new Text(`${theme.fg(\"toolTitle\", theme.bold(\"python\"))} ${theme.fg(\"muted\", mode)}`, 0, 0);\n\t\t},\n\t\trenderResult(result, { expanded, isPartial }, theme) {\n\t\t\tif (isPartial) return new Text(theme.fg(\"warning\", \"python running\"), 0, 0);\n\t\t\tconst details = result.details as PythonToolDetails | undefined;\n\t\t\tif (!details) return new Text(theme.fg(\"dim\", \"python done\"), 0, 0);\n\t\t\tconst status =\n\t\t\t\tdetails.exitCode === 0 && !details.timedOut ? \"python ok\" : `python exit ${details.exitCode ?? \"unknown\"}`;\n\t\t\tlet text = theme.fg(details.exitCode === 0 ? \"success\" : \"warning\", status);\n\t\t\tif (expanded) {\n\t\t\t\tconst content = result.content[0];\n\t\t\t\tif (content?.type === \"text\") {\n\t\t\t\t\tconst lines = content.text.split(\"\\n\").slice(-20);\n\t\t\t\t\tfor (const line of lines) text += `\\n${theme.fg(\"dim\", line)}`;\n\t\t\t\t}\n\t\t\t\tfor (const outputPath of [details.stdoutOutputPath, details.stderrOutputPath]) {\n\t\t\t\t\tif (outputPath) text += `\\n${theme.fg(\"muted\", `full output: ${outputPath}`)}`;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\t};\n}\n\nexport function createPythonTool(baseCwd: string, options?: PythonToolOptions): AgentTool<typeof pythonSchema> {\n\treturn wrapToolDefinition(createPythonToolDefinition(baseCwd, options));\n}\n"]}

package/dist/core/tools/python.js

@@ -0,0 +1,241 @@
+import { stat } from "node:fs/promises";
+import { posix, win32 } from "node:path";
+import { Text } from "@caupulican/pi-tui";
+import { Type } from "typebox";
+import { spawnProcess, waitForChildProcessWithTermination } from "../../utils/child-process.js";
+import { ensurePythonRuntime } from "../python-runtime.js";
+import { withExclusiveMutationBarrier } from "./file-mutation-queue.js";
+import { OutputAccumulator } from "./output-accumulator.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+export const DEFAULT_PYTHON_TIMEOUT_SECONDS = 30;
+export const MAX_PYTHON_TIMEOUT_SECONDS = 300;
+export const MAX_PYTHON_OUTPUT_BYTES = 200_000;
+const MIN_PYTHON_OUTPUT_BYTES = 1_000;
+const PYTHON_KILL_GRACE_MS = 2_000;
+const pythonSchema = Type.Object({
+    code: Type.Optional(Type.String({
+        description: "Python code to execute on stdin. Provide exactly one of code or scriptPath.",
+        maxLength: 200_000,
+    })),
+    scriptPath: Type.Optional(Type.String({
+        description: "Python script path. Relative paths resolve from cwd; one leading @ is ignored.",
+        maxLength: 32_768,
+    })),
+    args: Type.Optional(Type.Array(Type.String({ maxLength: 16_384 }), {
+        description: "Arguments passed directly to Python after '-' or scriptPath; no shell interpolation.",
+        maxItems: 256,
+    })),
+    cwd: Type.Optional(Type.String({
+        description: "Working directory. Defaults to Pi's cwd; relative paths resolve from Pi's cwd.",
+        maxLength: 32_768,
+    })),
+    timeoutSeconds: Type.Optional(Type.Number({
+        description: `Wall-clock timeout. Defaults to ${DEFAULT_PYTHON_TIMEOUT_SECONDS} seconds and is capped at ${MAX_PYTHON_TIMEOUT_SECONDS}.`,
+    })),
+    maxOutputBytes: Type.Optional(Type.Number({
+        description: `Maximum returned bytes per stream before full output spills to a work artifact. Maximum ${MAX_PYTHON_OUTPUT_BYTES}.`,
+    })),
+}, { additionalProperties: false });
+function stripAtPrefix(value) {
+    return value.startsWith("@") ? value.slice(1) : value;
+}
+export function resolvePythonToolPath(base, requested, platform = process.platform) {
+    return (platform === "win32" ? win32 : posix).resolve(base, stripAtPrefix(requested));
+}
+async function resolveWorkingDirectory(baseCwd, requested) {
+    const cwd = requested ? resolvePythonToolPath(baseCwd, requested) : baseCwd;
+    const entry = await stat(cwd).catch(() => {
+        throw new Error(`cwd does not exist: ${cwd}`);
+    });
+    if (!entry.isDirectory())
+        throw new Error(`cwd is not a directory: ${cwd}`);
+    return cwd;
+}
+async function resolveScriptPath(cwd, requested) {
+    const scriptPath = resolvePythonToolPath(cwd, requested);
+    const entry = await stat(scriptPath).catch(() => {
+        throw new Error(`scriptPath does not exist: ${scriptPath}`);
+    });
+    if (!entry.isFile())
+        throw new Error(`scriptPath is not a file: ${scriptPath}`);
+    return scriptPath;
+}
+function clampInteger(value, fallback, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return fallback;
+    return Math.max(minimum, Math.min(maximum, Math.trunc(value)));
+}
+function createLocalPythonOperations() {
+    return {
+        async exec(request) {
+            if (request.signal?.aborted)
+                throw new Error("Python execution aborted before start");
+            const child = spawnProcess(request.python, request.args, {
+                cwd: request.cwd,
+                detached: process.platform !== "win32",
+                env: request.env,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            child.stdout?.on("data", (chunk) => request.onStdout(chunk));
+            child.stderr?.on("data", (chunk) => request.onStderr(chunk));
+            child.stdin?.end(request.stdin ?? "");
+            const terminal = await waitForChildProcessWithTermination(child, {
+                killGraceMs: PYTHON_KILL_GRACE_MS,
+                signal: request.signal,
+                timeoutMs: request.timeoutMs,
+            });
+            return { exitCode: terminal.code, reason: terminal.reason, signal: child.signalCode };
+        },
+    };
+}
+function renderStreamNotice(label, path, error) {
+    if (path)
+        return `[${label} truncated; full output: ${path}]`;
+    if (error)
+        return `[${label} truncated; full-output artifact failed: ${error}]`;
+    return undefined;
+}
+export function createPythonToolDefinition(baseCwd, options = {}) {
+    const resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));
+    const operations = options.operations ?? createLocalPythonOperations();
+    return {
+        name: "python",
+        label: "python",
+        description: `Run a bounded Python snippet or script without a shell. Pi resolves Python through uv, defaults to a ${DEFAULT_PYTHON_TIMEOUT_SECONDS}-second wall-clock timeout (maximum ${MAX_PYTHON_TIMEOUT_SECONDS}), streams bounded stdout/stderr, and spills truncated full output to the process work directory rather than the repository.`,
+        promptSnippet: "Run bounded Python snippets or scripts through Pi's uv-managed runtime.",
+        promptGuidelines: [
+            "Prefer python for bounded scripts, data shaping, structured transformations, and cross-platform logic when it is clearer than a shell pipeline.",
+            "Prefer read/edit/write for small exact source edits. For Python file transformations, preserve encoding and newline style, write atomically, and verify the resulting diff.",
+            "Keep work scoped: avoid recursive home/filesystem scans, pass explicit roots and filters, and request a larger timeout only when the bounded workload justifies it.",
+            "Do not use python for destructive deletion, credentials, publish/push/release, or long-running services without explicit user approval.",
+        ],
+        parameters: pythonSchema,
+        async execute(_toolCallId, input, signal) {
+            const hasCode = typeof input.code === "string";
+            const hasScript = typeof input.scriptPath === "string" && input.scriptPath.trim().length > 0;
+            if (hasCode === hasScript)
+                throw new Error("Provide exactly one of code or scriptPath.");
+            const cwd = await resolveWorkingDirectory(baseCwd, input.cwd);
+            const scriptPath = hasScript ? await resolveScriptPath(cwd, input.scriptPath) : undefined;
+            const runtime = await resolveRuntime();
+            if (runtime.status !== "ready")
+                throw new Error(runtime.reason);
+            const args = input.args ? [...input.args] : [];
+            const timeoutSeconds = clampInteger(input.timeoutSeconds, DEFAULT_PYTHON_TIMEOUT_SECONDS, 1, MAX_PYTHON_TIMEOUT_SECONDS);
+            const maxOutputBytes = clampInteger(input.maxOutputBytes, 50 * 1024, MIN_PYTHON_OUTPUT_BYTES, MAX_PYTHON_OUTPUT_BYTES);
+            const accumulatorOptions = {
+                maxBytes: maxOutputBytes,
+                ...(options.outputDirectory ? { tempDirectory: options.outputDirectory } : {}),
+            };
+            const stdout = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: "pi-python-stdout" });
+            const stderr = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: "pi-python-stderr" });
+            const finishStreams = () => {
+                stdout.finish();
+                stderr.finish();
+                return {
+                    stdout: stdout.snapshot({ persistIfTruncated: true }),
+                    stderr: stderr.snapshot({ persistIfTruncated: true }),
+                };
+            };
+            let execution;
+            try {
+                execution = await withExclusiveMutationBarrier(() => operations.exec({
+                    python: runtime.pythonPath,
+                    args: scriptPath ? ["-B", scriptPath, ...args] : ["-B", "-", ...args],
+                    cwd,
+                    stdin: hasCode ? input.code : undefined,
+                    timeoutMs: timeoutSeconds * 1000,
+                    signal,
+                    env: {
+                        ...process.env,
+                        PI_PYTHON_TOOL: "1",
+                        PYTHONDONTWRITEBYTECODE: "1",
+                        PYTHONIOENCODING: "utf-8",
+                        PYTHONUNBUFFERED: "1",
+                        PYTHONUTF8: "1",
+                    },
+                    onStdout: (chunk) => stdout.append(chunk),
+                    onStderr: (chunk) => stderr.append(chunk),
+                }));
+                const snapshots = finishStreams();
+                const sections = [];
+                if (snapshots.stdout.content)
+                    sections.push(snapshots.stdout.content.trimEnd());
+                if (snapshots.stderr.content)
+                    sections.push(`[stderr]\n${snapshots.stderr.content.trimEnd()}`);
+                const stdoutNotice = renderStreamNotice("stdout", snapshots.stdout.fullOutputPath, snapshots.stdout.fullOutputError);
+                const stderrNotice = renderStreamNotice("stderr", snapshots.stderr.fullOutputPath, snapshots.stderr.fullOutputError);
+                if (stdoutNotice)
+                    sections.push(stdoutNotice);
+                if (stderrNotice)
+                    sections.push(stderrNotice);
+                const status = `[python exitCode=${execution.exitCode ?? "null"}${execution.signal ? `; signal=${execution.signal}` : ""}]`;
+                sections.push(status);
+                const text = sections.join("\n\n");
+                if (execution.reason === "timeout")
+                    throw new Error(`${text}\n\nPython timed out after ${timeoutSeconds} seconds`);
+                if (execution.reason === "aborted")
+                    throw new Error(`${text}\n\nPython execution aborted`);
+                if (execution.exitCode !== 0) {
+                    const termination = execution.signal
+                        ? `signal ${execution.signal}`
+                        : `code ${execution.exitCode ?? "unknown"}`;
+                    throw new Error(`${text}\n\nPython exited with ${termination}`);
+                }
+                return {
+                    content: [{ type: "text", text }],
+                    details: {
+                        mode: scriptPath ? "script" : "code",
+                        cwd,
+                        uvPath: runtime.uvPath,
+                        pythonPath: runtime.pythonPath,
+                        scriptPath,
+                        args,
+                        exitCode: execution.exitCode,
+                        signal: execution.signal,
+                        timedOut: false,
+                        ...(snapshots.stdout.truncation.truncated ? { stdoutTruncation: snapshots.stdout.truncation } : {}),
+                        ...(snapshots.stderr.truncation.truncated ? { stderrTruncation: snapshots.stderr.truncation } : {}),
+                        stdoutOutputPath: snapshots.stdout.fullOutputPath,
+                        stderrOutputPath: snapshots.stderr.fullOutputPath,
+                        stdoutOutputError: snapshots.stdout.fullOutputError,
+                        stderrOutputError: snapshots.stderr.fullOutputError,
+                    },
+                };
+            }
+            finally {
+                await Promise.all([stdout.closeTempFile(), stderr.closeTempFile()]);
+            }
+        },
+        renderCall(args, theme) {
+            const mode = args.scriptPath ? args.scriptPath : "code";
+            return new Text(`${theme.fg("toolTitle", theme.bold("python"))} ${theme.fg("muted", mode)}`, 0, 0);
+        },
+        renderResult(result, { expanded, isPartial }, theme) {
+            if (isPartial)
+                return new Text(theme.fg("warning", "python running"), 0, 0);
+            const details = result.details;
+            if (!details)
+                return new Text(theme.fg("dim", "python done"), 0, 0);
+            const status = details.exitCode === 0 && !details.timedOut ? "python ok" : `python exit ${details.exitCode ?? "unknown"}`;
+            let text = theme.fg(details.exitCode === 0 ? "success" : "warning", status);
+            if (expanded) {
+                const content = result.content[0];
+                if (content?.type === "text") {
+                    const lines = content.text.split("\n").slice(-20);
+                    for (const line of lines)
+                        text += `\n${theme.fg("dim", line)}`;
+                }
+                for (const outputPath of [details.stdoutOutputPath, details.stderrOutputPath]) {
+                    if (outputPath)
+                        text += `\n${theme.fg("muted", `full output: ${outputPath}`)}`;
+                }
+            }
+            return new Text(text, 0, 0);
+        },
+    };
+}
+export function createPythonTool(baseCwd, options) {
+    return wrapToolDefinition(createPythonToolDefinition(baseCwd, options));
+}
+//# sourceMappingURL=python.js.map

package/dist/core/tools/python.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"python.js","sourceRoot":"","sources":["../../../src/core/tools/python.ts"],"names":[],"mappings":"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","sourcesContent":["import { stat } from \"node:fs/promises\";\nimport { posix, win32 } from \"node:path\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport type { TruncationResult } from \"@caupulican/pi-agent-core/node\";\nimport { Text } from \"@caupulican/pi-tui\";\nimport { type Static, Type } from \"typebox\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport { ensurePythonRuntime, type PythonRuntimeOutcome } from \"../python-runtime.ts\";\nimport { withExclusiveMutationBarrier } from \"./file-mutation-queue.ts\";\nimport { OutputAccumulator } from \"./output-accumulator.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nexport const DEFAULT_PYTHON_TIMEOUT_SECONDS = 30;\nexport const MAX_PYTHON_TIMEOUT_SECONDS = 300;\nexport const MAX_PYTHON_OUTPUT_BYTES = 200_000;\nconst MIN_PYTHON_OUTPUT_BYTES = 1_000;\nconst PYTHON_KILL_GRACE_MS = 2_000;\n\nconst pythonSchema = Type.Object(\n\t{\n\t\tcode: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Python code to execute on stdin. Provide exactly one of code or scriptPath.\",\n\t\t\t\tmaxLength: 200_000,\n\t\t\t}),\n\t\t),\n\t\tscriptPath: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Python script path. Relative paths resolve from cwd; one leading @ is ignored.\",\n\t\t\t\tmaxLength: 32_768,\n\t\t\t}),\n\t\t),\n\t\targs: Type.Optional(\n\t\t\tType.Array(Type.String({ maxLength: 16_384 }), {\n\t\t\t\tdescription: \"Arguments passed directly to Python after '-' or scriptPath; no shell interpolation.\",\n\t\t\t\tmaxItems: 256,\n\t\t\t}),\n\t\t),\n\t\tcwd: Type.Optional(\n\t\t\tType.String({\n\t\t\t\tdescription: \"Working directory. Defaults to Pi's cwd; relative paths resolve from Pi's cwd.\",\n\t\t\t\tmaxLength: 32_768,\n\t\t\t}),\n\t\t),\n\t\ttimeoutSeconds: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tdescription: `Wall-clock timeout. Defaults to ${DEFAULT_PYTHON_TIMEOUT_SECONDS} seconds and is capped at ${MAX_PYTHON_TIMEOUT_SECONDS}.`,\n\t\t\t}),\n\t\t),\n\t\tmaxOutputBytes: Type.Optional(\n\t\t\tType.Number({\n\t\t\t\tdescription: `Maximum returned bytes per stream before full output spills to a work artifact. Maximum ${MAX_PYTHON_OUTPUT_BYTES}.`,\n\t\t\t}),\n\t\t),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type PythonToolInput = Static<typeof pythonSchema>;\n\nexport interface PythonToolDetails {\n\tmode: \"code\" | \"script\";\n\tcwd: string;\n\tuvPath: string;\n\tpythonPath: string;\n\tscriptPath?: string;\n\targs: string[];\n\texitCode: number | null;\n\tsignal: string | null;\n\ttimedOut: boolean;\n\tstdoutTruncation?: TruncationResult;\n\tstderrTruncation?: TruncationResult;\n\tstdoutOutputPath?: string;\n\tstderrOutputPath?: string;\n\tstdoutOutputError?: string;\n\tstderrOutputError?: string;\n}\n\nexport interface PythonExecutionRequest {\n\tpython: string;\n\targs: string[];\n\tcwd: string;\n\tstdin?: string;\n\ttimeoutMs: number;\n\tsignal?: AbortSignal;\n\tenv: NodeJS.ProcessEnv;\n\tonStdout: (chunk: Buffer) => void;\n\tonStderr: (chunk: Buffer) => void;\n}\n\nexport interface PythonExecutionResult {\n\texitCode: number | null;\n\treason: \"exited\" | \"aborted\" | \"timeout\";\n\tsignal: string | null;\n}\n\nexport interface PythonOperations {\n\texec(request: PythonExecutionRequest): Promise<PythonExecutionResult>;\n}\n\nexport interface PythonToolOptions {\n\tresolveRuntime?: () => Promise<PythonRuntimeOutcome>;\n\toperations?: PythonOperations;\n\t/** Override only for tests or embedded runtimes; production uses the process work directory. */\n\toutputDirectory?: string;\n}\n\nfunction stripAtPrefix(value: string): string {\n\treturn value.startsWith(\"@\") ? value.slice(1) : value;\n}\n\nexport function resolvePythonToolPath(\n\tbase: string,\n\trequested: string,\n\tplatform: NodeJS.Platform = process.platform,\n): string {\n\treturn (platform === \"win32\" ? win32 : posix).resolve(base, stripAtPrefix(requested));\n}\n\nasync function resolveWorkingDirectory(baseCwd: string, requested?: string): Promise<string> {\n\tconst cwd = requested ? resolvePythonToolPath(baseCwd, requested) : baseCwd;\n\tconst entry = await stat(cwd).catch(() => {\n\t\tthrow new Error(`cwd does not exist: ${cwd}`);\n\t});\n\tif (!entry.isDirectory()) throw new Error(`cwd is not a directory: ${cwd}`);\n\treturn cwd;\n}\n\nasync function resolveScriptPath(cwd: string, requested: string): Promise<string> {\n\tconst scriptPath = resolvePythonToolPath(cwd, requested);\n\tconst entry = await stat(scriptPath).catch(() => {\n\t\tthrow new Error(`scriptPath does not exist: ${scriptPath}`);\n\t});\n\tif (!entry.isFile()) throw new Error(`scriptPath is not a file: ${scriptPath}`);\n\treturn scriptPath;\n}\n\nfunction clampInteger(value: number | undefined, fallback: number, minimum: number, maximum: number): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value) || value <= 0) return fallback;\n\treturn Math.max(minimum, Math.min(maximum, Math.trunc(value)));\n}\n\nfunction createLocalPythonOperations(): PythonOperations {\n\treturn {\n\t\tasync exec(request) {\n\t\t\tif (request.signal?.aborted) throw new Error(\"Python execution aborted before start\");\n\t\t\tconst child = spawnProcess(request.python, request.args, {\n\t\t\t\tcwd: request.cwd,\n\t\t\t\tdetached: process.platform !== \"win32\",\n\t\t\t\tenv: request.env,\n\t\t\t\tstdio: [\"pipe\", \"pipe\", \"pipe\"],\n\t\t\t});\n\t\t\tchild.stdout?.on(\"data\", (chunk: Buffer) => request.onStdout(chunk));\n\t\t\tchild.stderr?.on(\"data\", (chunk: Buffer) => request.onStderr(chunk));\n\t\t\tchild.stdin?.end(request.stdin ?? \"\");\n\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\tkillGraceMs: PYTHON_KILL_GRACE_MS,\n\t\t\t\tsignal: request.signal,\n\t\t\t\ttimeoutMs: request.timeoutMs,\n\t\t\t});\n\t\t\treturn { exitCode: terminal.code, reason: terminal.reason, signal: child.signalCode };\n\t\t},\n\t};\n}\n\nfunction renderStreamNotice(label: string, path: string | undefined, error: string | undefined): string | undefined {\n\tif (path) return `[${label} truncated; full output: ${path}]`;\n\tif (error) return `[${label} truncated; full-output artifact failed: ${error}]`;\n\treturn undefined;\n}\n\nexport function createPythonToolDefinition(\n\tbaseCwd: string,\n\toptions: PythonToolOptions = {},\n): ToolDefinition<typeof pythonSchema, PythonToolDetails> {\n\tconst resolveRuntime = options.resolveRuntime ?? (() => ensurePythonRuntime({ silent: true }));\n\tconst operations = options.operations ?? createLocalPythonOperations();\n\treturn {\n\t\tname: \"python\",\n\t\tlabel: \"python\",\n\t\tdescription: `Run a bounded Python snippet or script without a shell. Pi resolves Python through uv, defaults to a ${DEFAULT_PYTHON_TIMEOUT_SECONDS}-second wall-clock timeout (maximum ${MAX_PYTHON_TIMEOUT_SECONDS}), streams bounded stdout/stderr, and spills truncated full output to the process work directory rather than the repository.`,\n\t\tpromptSnippet: \"Run bounded Python snippets or scripts through Pi's uv-managed runtime.\",\n\t\tpromptGuidelines: [\n\t\t\t\"Prefer python for bounded scripts, data shaping, structured transformations, and cross-platform logic when it is clearer than a shell pipeline.\",\n\t\t\t\"Prefer read/edit/write for small exact source edits. For Python file transformations, preserve encoding and newline style, write atomically, and verify the resulting diff.\",\n\t\t\t\"Keep work scoped: avoid recursive home/filesystem scans, pass explicit roots and filters, and request a larger timeout only when the bounded workload justifies it.\",\n\t\t\t\"Do not use python for destructive deletion, credentials, publish/push/release, or long-running services without explicit user approval.\",\n\t\t],\n\t\tparameters: pythonSchema,\n\t\tasync execute(_toolCallId, input, signal) {\n\t\t\tconst hasCode = typeof input.code === \"string\";\n\t\t\tconst hasScript = typeof input.scriptPath === \"string\" && input.scriptPath.trim().length > 0;\n\t\t\tif (hasCode === hasScript) throw new Error(\"Provide exactly one of code or scriptPath.\");\n\t\t\tconst cwd = await resolveWorkingDirectory(baseCwd, input.cwd);\n\t\t\tconst scriptPath = hasScript ? await resolveScriptPath(cwd, input.scriptPath as string) : undefined;\n\t\t\tconst runtime = await resolveRuntime();\n\t\t\tif (runtime.status !== \"ready\") throw new Error(runtime.reason);\n\t\t\tconst args = input.args ? [...input.args] : [];\n\t\t\tconst timeoutSeconds = clampInteger(\n\t\t\t\tinput.timeoutSeconds,\n\t\t\t\tDEFAULT_PYTHON_TIMEOUT_SECONDS,\n\t\t\t\t1,\n\t\t\t\tMAX_PYTHON_TIMEOUT_SECONDS,\n\t\t\t);\n\t\t\tconst maxOutputBytes = clampInteger(\n\t\t\t\tinput.maxOutputBytes,\n\t\t\t\t50 * 1024,\n\t\t\t\tMIN_PYTHON_OUTPUT_BYTES,\n\t\t\t\tMAX_PYTHON_OUTPUT_BYTES,\n\t\t\t);\n\t\t\tconst accumulatorOptions = {\n\t\t\t\tmaxBytes: maxOutputBytes,\n\t\t\t\t...(options.outputDirectory ? { tempDirectory: options.outputDirectory } : {}),\n\t\t\t};\n\t\t\tconst stdout = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: \"pi-python-stdout\" });\n\t\t\tconst stderr = new OutputAccumulator({ ...accumulatorOptions, tempFilePrefix: \"pi-python-stderr\" });\n\t\t\tconst finishStreams = () => {\n\t\t\t\tstdout.finish();\n\t\t\t\tstderr.finish();\n\t\t\t\treturn {\n\t\t\t\t\tstdout: stdout.snapshot({ persistIfTruncated: true }),\n\t\t\t\t\tstderr: stderr.snapshot({ persistIfTruncated: true }),\n\t\t\t\t};\n\t\t\t};\n\t\t\tlet execution: PythonExecutionResult;\n\t\t\ttry {\n\t\t\t\texecution = await withExclusiveMutationBarrier(() =>\n\t\t\t\t\toperations.exec({\n\t\t\t\t\t\tpython: runtime.pythonPath,\n\t\t\t\t\t\targs: scriptPath ? [\"-B\", scriptPath, ...args] : [\"-B\", \"-\", ...args],\n\t\t\t\t\t\tcwd,\n\t\t\t\t\t\tstdin: hasCode ? input.code : undefined,\n\t\t\t\t\t\ttimeoutMs: timeoutSeconds * 1000,\n\t\t\t\t\t\tsignal,\n\t\t\t\t\t\tenv: {\n\t\t\t\t\t\t\t...process.env,\n\t\t\t\t\t\t\tPI_PYTHON_TOOL: \"1\",\n\t\t\t\t\t\t\tPYTHONDONTWRITEBYTECODE: \"1\",\n\t\t\t\t\t\t\tPYTHONIOENCODING: \"utf-8\",\n\t\t\t\t\t\t\tPYTHONUNBUFFERED: \"1\",\n\t\t\t\t\t\t\tPYTHONUTF8: \"1\",\n\t\t\t\t\t\t},\n\t\t\t\t\t\tonStdout: (chunk) => stdout.append(chunk),\n\t\t\t\t\t\tonStderr: (chunk) => stderr.append(chunk),\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t\tconst snapshots = finishStreams();\n\t\t\t\tconst sections: string[] = [];\n\t\t\t\tif (snapshots.stdout.content) sections.push(snapshots.stdout.content.trimEnd());\n\t\t\t\tif (snapshots.stderr.content) sections.push(`[stderr]\\n${snapshots.stderr.content.trimEnd()}`);\n\t\t\t\tconst stdoutNotice = renderStreamNotice(\n\t\t\t\t\t\"stdout\",\n\t\t\t\t\tsnapshots.stdout.fullOutputPath,\n\t\t\t\t\tsnapshots.stdout.fullOutputError,\n\t\t\t\t);\n\t\t\t\tconst stderrNotice = renderStreamNotice(\n\t\t\t\t\t\"stderr\",\n\t\t\t\t\tsnapshots.stderr.fullOutputPath,\n\t\t\t\t\tsnapshots.stderr.fullOutputError,\n\t\t\t\t);\n\t\t\t\tif (stdoutNotice) sections.push(stdoutNotice);\n\t\t\t\tif (stderrNotice) sections.push(stderrNotice);\n\t\t\t\tconst status = `[python exitCode=${execution.exitCode ?? \"null\"}${execution.signal ? `; signal=${execution.signal}` : \"\"}]`;\n\t\t\t\tsections.push(status);\n\t\t\t\tconst text = sections.join(\"\\n\\n\");\n\t\t\t\tif (execution.reason === \"timeout\")\n\t\t\t\t\tthrow new Error(`${text}\\n\\nPython timed out after ${timeoutSeconds} seconds`);\n\t\t\t\tif (execution.reason === \"aborted\") throw new Error(`${text}\\n\\nPython execution aborted`);\n\t\t\t\tif (execution.exitCode !== 0) {\n\t\t\t\t\tconst termination = execution.signal\n\t\t\t\t\t\t? `signal ${execution.signal}`\n\t\t\t\t\t\t: `code ${execution.exitCode ?? \"unknown\"}`;\n\t\t\t\t\tthrow new Error(`${text}\\n\\nPython exited with ${termination}`);\n\t\t\t\t}\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\tmode: scriptPath ? \"script\" : \"code\",\n\t\t\t\t\t\tcwd,\n\t\t\t\t\t\tuvPath: runtime.uvPath,\n\t\t\t\t\t\tpythonPath: runtime.pythonPath,\n\t\t\t\t\t\tscriptPath,\n\t\t\t\t\t\targs,\n\t\t\t\t\t\texitCode: execution.exitCode,\n\t\t\t\t\t\tsignal: execution.signal,\n\t\t\t\t\t\ttimedOut: false,\n\t\t\t\t\t\t...(snapshots.stdout.truncation.truncated ? { stdoutTruncation: snapshots.stdout.truncation } : {}),\n\t\t\t\t\t\t...(snapshots.stderr.truncation.truncated ? { stderrTruncation: snapshots.stderr.truncation } : {}),\n\t\t\t\t\t\tstdoutOutputPath: snapshots.stdout.fullOutputPath,\n\t\t\t\t\t\tstderrOutputPath: snapshots.stderr.fullOutputPath,\n\t\t\t\t\t\tstdoutOutputError: snapshots.stdout.fullOutputError,\n\t\t\t\t\t\tstderrOutputError: snapshots.stderr.fullOutputError,\n\t\t\t\t\t},\n\t\t\t\t};\n\t\t\t} finally {\n\t\t\t\tawait Promise.all([stdout.closeTempFile(), stderr.closeTempFile()]);\n\t\t\t}\n\t\t},\n\t\trenderCall(args, theme) {\n\t\t\tconst mode = args.scriptPath ? args.scriptPath : \"code\";\n\t\t\treturn new Text(`${theme.fg(\"toolTitle\", theme.bold(\"python\"))} ${theme.fg(\"muted\", mode)}`, 0, 0);\n\t\t},\n\t\trenderResult(result, { expanded, isPartial }, theme) {\n\t\t\tif (isPartial) return new Text(theme.fg(\"warning\", \"python running\"), 0, 0);\n\t\t\tconst details = result.details as PythonToolDetails | undefined;\n\t\t\tif (!details) return new Text(theme.fg(\"dim\", \"python done\"), 0, 0);\n\t\t\tconst status =\n\t\t\t\tdetails.exitCode === 0 && !details.timedOut ? \"python ok\" : `python exit ${details.exitCode ?? \"unknown\"}`;\n\t\t\tlet text = theme.fg(details.exitCode === 0 ? \"success\" : \"warning\", status);\n\t\t\tif (expanded) {\n\t\t\t\tconst content = result.content[0];\n\t\t\t\tif (content?.type === \"text\") {\n\t\t\t\t\tconst lines = content.text.split(\"\\n\").slice(-20);\n\t\t\t\t\tfor (const line of lines) text += `\\n${theme.fg(\"dim\", line)}`;\n\t\t\t\t}\n\t\t\t\tfor (const outputPath of [details.stdoutOutputPath, details.stderrOutputPath]) {\n\t\t\t\t\tif (outputPath) text += `\\n${theme.fg(\"muted\", `full output: ${outputPath}`)}`;\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn new Text(text, 0, 0);\n\t\t},\n\t};\n}\n\nexport function createPythonTool(baseCwd: string, options?: PythonToolOptions): AgentTool<typeof pythonSchema> {\n\treturn wrapToolDefinition(createPythonToolDefinition(baseCwd, options));\n}\n"]}

package/dist/core/tools/shell-contract-router.d.ts

@@ -0,0 +1,13 @@
+export type ShellContractRoute = {
+    kind: "passthrough";
+    command: string;
+} | {
+    kind: "powershell";
+    command: string;
+    argv: readonly string[];
+} | {
+    kind: "unsupported";
+    error: string;
+};
+export declare function routeShellContract(command: string, platform?: NodeJS.Platform): ShellContractRoute;
+//# sourceMappingURL=shell-contract-router.d.ts.map

package/dist/core/tools/shell-contract-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-contract-router.d.ts","sourceRoot":"","sources":["../../../src/core/tools/shell-contract-router.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,kBAAkB,GAC3B;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAmQ1C,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAAG,kBAAkB,CAkCpH","sourcesContent":["export type ShellContractRoute =\n\t| { kind: \"passthrough\"; command: string }\n\t| { kind: \"powershell\"; command: string; argv: readonly string[] }\n\t| { kind: \"unsupported\"; error: string };\n\ninterface TokenizeResult {\n\tok: boolean;\n\targv?: string[];\n\terror?: string;\n}\n\nconst BLOCKED_NESTED_SHELLS = new Set([\n\t\"bash\",\n\t\"sh\",\n\t\"zsh\",\n\t\"fish\",\n\t\"cmd\",\n\t\"cmd.exe\",\n\t\"powershell\",\n\t\"powershell.exe\",\n\t\"pwsh\",\n\t\"pwsh.exe\",\n\t\"wsl\",\n\t\"wsl.exe\",\n]);\nconst UNSUPPORTED_OPERATOR_MESSAGE =\n\t\"Unsupported Bash construct on Windows. Use one simple command per call; pipelines, redirection, command substitution, variable expansion, shell chaining, and nested shells are not translated.\";\n\nfunction tokenizePortableCommand(command: string): TokenizeResult {\n\tconst argv: string[] = [];\n\tlet token = \"\";\n\tlet tokenStarted = false;\n\tlet quote: \"single\" | \"double\" | undefined;\n\tlet escaping = false;\n\n\tconst finishToken = () => {\n\t\tif (!tokenStarted) return;\n\t\targv.push(token);\n\t\ttoken = \"\";\n\t\ttokenStarted = false;\n\t};\n\n\tfor (const character of command.trim()) {\n\t\tif (escaping) {\n\t\t\ttoken += character;\n\t\t\ttokenStarted = true;\n\t\t\tescaping = false;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote === \"single\") {\n\t\t\tif (character === \"'\") quote = undefined;\n\t\t\telse token += character;\n\t\t\ttokenStarted = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (quote === \"double\") {\n\t\t\tif (character === '\"') {\n\t\t\t\tquote = undefined;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"\\\\\") {\n\t\t\t\tescaping = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (character === \"$\" || character === \"`\") {\n\t\t\t\treturn { ok: false, error: UNSUPPORTED_OPERATOR_MESSAGE };\n\t\t\t}\n\t\t\ttoken += character;\n\t\t\ttokenStarted = true;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (character === \"'\") {\n\t\t\tquote = \"single\";\n\t\t\ttokenStarted = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (character === '\"') {\n\t\t\tquote = \"double\";\n\t\t\ttokenStarted = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (character === \"\\\\\") {\n\t\t\tescaping = true;\n\t\t\ttokenStarted = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (/\\s/u.test(character)) {\n\t\t\tfinishToken();\n\t\t\tcontinue;\n\t\t}\n\t\tif (\"|><&;\\n\\r$`()\".includes(character) || character === \"#\") {\n\t\t\treturn { ok: false, error: UNSUPPORTED_OPERATOR_MESSAGE };\n\t\t}\n\t\ttoken += character;\n\t\ttokenStarted = true;\n\t}\n\n\tif (escaping) return { ok: false, error: \"Unsupported trailing escape in Bash-like command.\" };\n\tif (quote) return { ok: false, error: \"Unclosed quote in Bash-like command.\" };\n\tfinishToken();\n\treturn argv.length > 0 ? { ok: true, argv } : { ok: false, error: \"Shell command is empty.\" };\n}\n\nfunction quotePowerShell(value: string): string {\n\treturn `'${value.replaceAll(\"'\", \"''\")}'`;\n}\n\nfunction powershellArray(values: readonly string[]): string {\n\treturn `@(${values.map(quotePowerShell).join(\", \")})`;\n}\n\nfunction externalCommand(argv: readonly string[]): string {\n\tconst invocation = `& ${argv.map(quotePowerShell).join(\" \")}`;\n\treturn `${invocation}\\nif ($null -ne $LASTEXITCODE) { exit $LASTEXITCODE }\\nif (-not $?) { exit 1 }`;\n}\n\nfunction parseFlags(\n\targv: readonly string[],\n\tallowedFlags: ReadonlySet<string>,\n): { flags: Set<string>; operands: string[] } | undefined {\n\tconst flags = new Set<string>();\n\tconst operands: string[] = [];\n\tlet optionsEnded = false;\n\tfor (const value of argv) {\n\t\tif (!optionsEnded && value === \"--\") {\n\t\t\toptionsEnded = true;\n\t\t\tcontinue;\n\t\t}\n\t\tif (!optionsEnded && value.startsWith(\"-\") && value !== \"-\") {\n\t\t\tif (!allowedFlags.has(value)) return undefined;\n\t\t\tflags.add(value);\n\t\t\tcontinue;\n\t\t}\n\t\toperands.push(value);\n\t}\n\treturn { flags, operands };\n}\n\nfunction routeLs(argv: readonly string[]): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), new Set([\"-a\", \"-A\", \"-l\", \"-1\", \"-la\", \"-al\"]));\n\tif (!parsed || parsed.operands.length > 1) return undefined;\n\tconst target = parsed.operands[0] ?? \".\";\n\treturn `[string[]]$items = @(Get-ChildItem -LiteralPath ${quotePowerShell(target)} -Force -ErrorAction Stop | ForEach-Object { if ($_.PSIsContainer) { $_.Name + '/' } else { $_.Name } }); [Array]::Sort($items, [StringComparer]::Ordinal); $items`;\n}\n\nfunction routeCat(argv: readonly string[]): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), new Set([\"--\"]));\n\tif (!parsed || parsed.operands.length === 0) return undefined;\n\treturn `Get-Content -LiteralPath ${powershellArray(parsed.operands)} -Raw -ErrorAction Stop`;\n}\n\nfunction routeHeadOrTail(argv: readonly string[], tail: boolean): string | undefined {\n\tlet count = 10;\n\tlet operands = argv.slice(1);\n\tif (operands[0] === \"-n\") {\n\t\tconst parsedCount = Number(operands[1]);\n\t\tif (!Number.isInteger(parsedCount) || parsedCount < 0) return undefined;\n\t\tcount = parsedCount;\n\t\toperands = operands.slice(2);\n\t}\n\tif (operands.length !== 1 || operands[0].startsWith(\"-\")) return undefined;\n\treturn `Get-Content -LiteralPath ${quotePowerShell(operands[0])} ${tail ? \"-Tail\" : \"-TotalCount\"} ${count} -ErrorAction Stop`;\n}\n\nfunction routeGrep(argv: readonly string[]): string | undefined {\n\tif (argv.length !== 3 || argv[1].startsWith(\"-\") || argv[2].startsWith(\"-\")) return undefined;\n\treturn `Select-String -LiteralPath ${quotePowerShell(argv[2])} -SimpleMatch -Pattern ${quotePowerShell(argv[1])} -ErrorAction Stop | ForEach-Object { $_.Line }`;\n}\n\nfunction routeFind(argv: readonly string[]): string | undefined {\n\tlet searchPath = \".\";\n\tlet type: \"File\" | \"Directory\" | undefined;\n\tlet filter: string | undefined;\n\tlet index = 1;\n\tif (argv[index] && !argv[index].startsWith(\"-\")) searchPath = argv[index++];\n\twhile (index < argv.length) {\n\t\tconst option = argv[index++];\n\t\tif (option === \"-type\" && (argv[index] === \"f\" || argv[index] === \"d\")) {\n\t\t\ttype = argv[index++] === \"f\" ? \"File\" : \"Directory\";\n\t\t\tcontinue;\n\t\t}\n\t\tif (option === \"-name\" && argv[index]) {\n\t\t\tfilter = argv[index++];\n\t\t\tcontinue;\n\t\t}\n\t\treturn undefined;\n\t}\n\tconst typeFlag = type ? ` -${type}` : \"\";\n\tconst filterFlag = filter ? ` -Filter ${quotePowerShell(filter)}` : \"\";\n\treturn `[string[]]$paths = @(Get-ChildItem -LiteralPath ${quotePowerShell(searchPath)} -Recurse -Force${typeFlag}${filterFlag} -ErrorAction Stop | ForEach-Object { $_.FullName.Replace('\\\\', '/') }); [Array]::Sort($paths, [StringComparer]::Ordinal); $paths`;\n}\n\nfunction routeRemove(argv: readonly string[]): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), new Set([\"-f\", \"-r\", \"-rf\", \"-fr\"]));\n\tif (!parsed || parsed.operands.length === 0) return undefined;\n\tconst recursive = [...parsed.flags].some((flag) => flag.includes(\"r\"));\n\treturn `Remove-Item -LiteralPath ${powershellArray(parsed.operands)} -Force${recursive ? \" -Recurse\" : \"\"} -ErrorAction Stop`;\n}\n\nfunction routeCopyOrMove(argv: readonly string[], move: boolean): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), move ? new Set<string>() : new Set([\"-r\", \"-R\"]));\n\tif (!parsed || parsed.operands.length !== 2) return undefined;\n\tconst [source, destination] = parsed.operands;\n\tconst recurse = !move && parsed.flags.size > 0 ? \" -Recurse\" : \"\";\n\treturn `${move ? \"Move-Item\" : \"Copy-Item\"} -LiteralPath ${quotePowerShell(source)} -Destination ${quotePowerShell(destination)}${recurse} -ErrorAction Stop`;\n}\n\nfunction routeMkdir(argv: readonly string[]): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), new Set([\"-p\"]));\n\tif (!parsed || parsed.operands.length === 0) return undefined;\n\treturn `${powershellArray(parsed.operands)} | ForEach-Object { New-Item -ItemType Directory -Path $_ -Force -ErrorAction Stop | Out-Null }`;\n}\n\nfunction routeTouch(argv: readonly string[]): string | undefined {\n\tconst parsed = parseFlags(argv.slice(1), new Set());\n\tif (!parsed || parsed.operands.length === 0) return undefined;\n\treturn `${powershellArray(parsed.operands)} | ForEach-Object { if (Test-Path -LiteralPath $_) { (Get-Item -LiteralPath $_ -ErrorAction Stop).LastWriteTime = Get-Date } else { New-Item -ItemType File -Path $_ -ErrorAction Stop | Out-Null } }`;\n}\n\nfunction routeBuiltIn(argv: readonly string[]): string | undefined {\n\tconst command = argv[0].toLowerCase();\n\tif (command === \"pwd\" && argv.length === 1) return \"(Get-Location).Path\";\n\tif (command === \"echo\") return `[Console]::Out.WriteLine((${powershellArray(argv.slice(1))} -join ' '))`;\n\tif (command === \"true\" && argv.length === 1) return \"exit 0\";\n\tif (command === \"false\" && argv.length === 1) return \"exit 1\";\n\tif (command === \"which\" && argv.length === 2) {\n\t\treturn `(Get-Command -Name ${quotePowerShell(argv[1])} -CommandType Application -ErrorAction Stop).Source`;\n\t}\n\tif (command === \"ls\") return routeLs(argv);\n\tif (command === \"cat\") return routeCat(argv);\n\tif (command === \"head\") return routeHeadOrTail(argv, false);\n\tif (command === \"tail\") return routeHeadOrTail(argv, true);\n\tif (command === \"grep\") return routeGrep(argv);\n\tif (command === \"find\") return routeFind(argv);\n\tif (command === \"rm\") return routeRemove(argv);\n\tif (command === \"cp\") return routeCopyOrMove(argv, false);\n\tif (command === \"mv\") return routeCopyOrMove(argv, true);\n\tif (command === \"mkdir\") return routeMkdir(argv);\n\tif (command === \"touch\") return routeTouch(argv);\n\treturn undefined;\n}\n\nconst ROUTED_BUILTIN_NAMES = new Set([\n\t\"pwd\",\n\t\"echo\",\n\t\"true\",\n\t\"false\",\n\t\"which\",\n\t\"ls\",\n\t\"cat\",\n\t\"head\",\n\t\"tail\",\n\t\"grep\",\n\t\"find\",\n\t\"rm\",\n\t\"cp\",\n\t\"mv\",\n\t\"mkdir\",\n\t\"touch\",\n]);\n\nexport function routeShellContract(command: string, platform: NodeJS.Platform = process.platform): ShellContractRoute {\n\tif (platform !== \"win32\") return { kind: \"passthrough\", command };\n\tconst tokenized = tokenizePortableCommand(command);\n\tif (!tokenized.ok || !tokenized.argv)\n\t\treturn { kind: \"unsupported\", error: tokenized.error ?? UNSUPPORTED_OPERATOR_MESSAGE };\n\tconst argv = tokenized.argv;\n\tconst commandName = argv[0].toLowerCase();\n\tif (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(argv[0])) {\n\t\treturn {\n\t\t\tkind: \"unsupported\",\n\t\t\terror: \"Inline environment assignments are not supported. Configure the environment outside the shell command.\",\n\t\t};\n\t}\n\tif (BLOCKED_NESTED_SHELLS.has(commandName)) {\n\t\treturn {\n\t\t\tkind: \"unsupported\",\n\t\t\terror: \"Nested shell execution is not supported by the Windows shell contract router.\",\n\t\t};\n\t}\n\tconst builtIn = routeBuiltIn(argv);\n\tif (builtIn) return { kind: \"powershell\", command: builtIn, argv };\n\tif (ROUTED_BUILTIN_NAMES.has(commandName)) {\n\t\treturn {\n\t\t\tkind: \"unsupported\",\n\t\t\terror: `Unsupported ${argv[0]} form on Windows. Use a simpler Bash-like form or Pi's dedicated read/search/edit tools.`,\n\t\t};\n\t}\n\tif (commandName.endsWith(\".sh\") || commandName.includes(\"/bin/\")) {\n\t\treturn {\n\t\t\tkind: \"unsupported\",\n\t\t\terror: \"POSIX shell scripts are not supported by the Windows shell contract router.\",\n\t\t};\n\t}\n\treturn { kind: \"powershell\", command: externalCommand(argv), argv };\n}\n"]}