@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/dist/core/tools/orchestration-panel.js

@@ -0,0 +1,168 @@
+import { truncateToWidth, visibleWidth } from "@caupulican/pi-tui";
+import { renderTitleBadge } from "../../modes/interactive/components/tool-title.js";
+const ROW_STYLES = {
+    pending: { icon: "○", color: "muted" },
+    queued: { icon: "◌", color: "warning" },
+    running: { icon: "●", color: "accent", bold: true },
+    in_progress: { icon: "●", color: "accent", bold: true },
+    completed: { icon: "✓", color: "success", strike: true },
+    succeeded: { icon: "✓", color: "success" },
+    blocked: { icon: "!", color: "warning", bold: true },
+    failed: { icon: "×", color: "error", bold: true },
+    timeout: { icon: "×", color: "warning" },
+    budget_exhausted: { icon: "!", color: "warning" },
+    cancelled: { icon: "–", color: "muted", strike: true },
+    canceled: { icon: "–", color: "muted", strike: true },
+    reviewed: { icon: "✓", color: "success" },
+    info: { icon: "·", color: "muted" },
+};
+const NOTICE_STYLES = {
+    info: { icon: "·", color: "muted" },
+    success: { icon: "✓", color: "success" },
+    warning: { icon: "!", color: "warning" },
+    error: { icon: "×", color: "error" },
+};
+export function taskStepPanelRow(step) {
+    const meta = [
+        step.priority === "high" ? "high priority" : undefined,
+        step.owner ? `@${step.owner}` : undefined,
+        step.requirementIds?.length
+            ? `${step.requirementIds.length} requirement${step.requirementIds.length === 1 ? "" : "s"}`
+            : undefined,
+        step.evidence.length ? `${step.evidence.length} evidence` : undefined,
+    ].filter((value) => value !== undefined);
+    const details = [
+        ...step.notes.slice(-2).map((note) => `note: ${note}`),
+        ...step.evidence.slice(-2).map((evidence) => `evidence: ${evidence}`),
+    ];
+    return {
+        status: step.status,
+        label: step.status === "in_progress" ? (step.activeForm ?? step.content) : step.content,
+        meta,
+        details,
+    };
+}
+/** Build the quiet below-editor view from native session truth. No active work means no widget. */
+export function createOrchestrationActivityModel(taskState, laneRecords) {
+    const openSteps = taskState?.steps.filter((step) => step.status !== "completed" && step.status !== "cancelled") ?? [];
+    const orderedSteps = [
+        ...openSteps.filter((step) => step.status === "in_progress"),
+        ...openSteps.filter((step) => step.status === "blocked"),
+        ...openSteps.filter((step) => step.status === "pending"),
+    ];
+    const activeLanes = laneRecords.filter((lane) => (lane.type === "worker" || lane.type === "tmux-worker") &&
+        (lane.status === "running" || lane.status === "queued"));
+    if (openSteps.length === 0 && activeLanes.length === 0)
+        return undefined;
+    const taskRows = orderedSteps.slice(0, 5).map((step) => ({ ...taskStepPanelRow(step), section: "Steps" }));
+    const laneRows = activeLanes.slice(0, 3).map((lane) => ({
+        status: lane.status,
+        label: lane.label ?? lane.laneId,
+        section: "Agents",
+        meta: [
+            lane.label ? lane.laneId : undefined,
+            lane.profileId ? `profile ${lane.profileId}` : undefined,
+            lane.type === "tmux-worker" ? "tmux" : undefined,
+        ].filter((value) => value !== undefined),
+    }));
+    const runningLanes = activeLanes.filter((lane) => lane.status === "running").length;
+    const queuedLanes = activeLanes.length - runningLanes;
+    const blockedSteps = openSteps.filter((step) => step.status === "blocked").length;
+    const workingSteps = openSteps.filter((step) => step.status === "in_progress").length;
+    const evidenceMissing = taskState?.steps.some((step) => step.status === "completed" && step.evidence.length === 0);
+    return {
+        label: "work",
+        action: workingSteps + runningLanes > 0 ? "active" : "ready",
+        status: blockedSteps > 0 ? "warning" : workingSteps + runningLanes > 0 ? "running" : "idle",
+        summary: [
+            openSteps.length ? `${openSteps.length} step${openSteps.length === 1 ? "" : "s"}` : undefined,
+            runningLanes ? `${runningLanes} agent${runningLanes === 1 ? "" : "s"}` : undefined,
+            queuedLanes ? `${queuedLanes} queued` : undefined,
+        ].filter((value) => value !== undefined),
+        rows: [...taskRows, ...laneRows],
+        hiddenRowCount: Math.max(0, openSteps.length + activeLanes.length - taskRows.length - laneRows.length),
+        notices: evidenceMissing
+            ? [{ status: "warning", text: "Completed work still needs attached evidence." }]
+            : undefined,
+    };
+}
+function renderRow(theme, row, width, expanded) {
+    const style = ROW_STYLES[row.status];
+    const prefix = `  ${theme.fg(style.color, style.icon)} `;
+    const meta = row.meta?.filter(Boolean).join(" · ") ?? "";
+    const suffix = meta ? `  ${theme.fg("dim", meta)}` : "";
+    const labelWidth = Math.max(4, width - visibleWidth(prefix) - visibleWidth(suffix));
+    const clippedLabel = truncateToWidth(row.label, labelWidth, "…");
+    let label = style.bold ? theme.bold(clippedLabel) : clippedLabel;
+    if (style.strike)
+        label = theme.strikethrough(label);
+    const lines = [`${prefix}${theme.fg(style.strike ? "dim" : "text", label)}${suffix}`];
+    if (expanded) {
+        for (const detail of row.details ?? []) {
+            lines.push(`    ${theme.fg("dim", truncateToWidth(detail, Math.max(4, width - 4), "…"))}`);
+        }
+    }
+    return lines;
+}
+export function renderOrchestrationPanelLines(theme, model, width, expanded = false) {
+    const safeWidth = Math.max(1, width);
+    const title = renderTitleBadge(theme, {
+        label: model.label,
+        action: model.action,
+        status: model.status ?? "info",
+    });
+    const summary = model.summary?.filter(Boolean).join(theme.fg("dim", " · ")) ?? "";
+    const lines = [summary ? `${title}  ${theme.fg("dim", summary)}` : title];
+    const rows = model.rows ?? [];
+    if (rows.length > 0) {
+        let section;
+        for (const row of rows) {
+            if (row.section && row.section !== section) {
+                section = row.section;
+                lines.push(`  ${theme.fg("muted", theme.bold(row.section))}`);
+            }
+            lines.push(...renderRow(theme, row, safeWidth, expanded));
+        }
+    }
+    else if (model.emptyText) {
+        lines.push(`  ${theme.fg("muted", model.emptyText)}`);
+    }
+    if ((model.hiddenRowCount ?? 0) > 0) {
+        lines.push(`  ${theme.fg("dim", `… ${model.hiddenRowCount} more`)}`);
+    }
+    for (const notice of model.notices ?? []) {
+        const style = NOTICE_STYLES[notice.status];
+        lines.push(`  ${theme.fg(style.color, style.icon)} ${theme.fg("dim", notice.text)}`);
+    }
+    return lines.map((line) => truncateToWidth(line, safeWidth, ""));
+}
+export class OrchestrationPanelComponent {
+    cachedWidth;
+    cachedLines;
+    theme;
+    model;
+    expanded;
+    constructor(theme, model, expanded = false) {
+        this.theme = theme;
+        this.model = model;
+        this.expanded = expanded;
+    }
+    render(width) {
+        if (this.cachedWidth === width && this.cachedLines)
+            return this.cachedLines;
+        this.cachedWidth = width;
+        this.cachedLines = renderOrchestrationPanelLines(this.theme, this.model, width, this.expanded);
+        return this.cachedLines;
+    }
+    invalidate() {
+        this.cachedWidth = undefined;
+        this.cachedLines = undefined;
+    }
+}
+export function emptyOrchestrationCall() {
+    return {
+        render: () => [],
+        invalidate() { },
+    };
+}
+//# sourceMappingURL=orchestration-panel.js.map

package/dist/core/tools/orchestration-panel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestration-panel.js","sourceRoot":"","sources":["../../../src/core/tools/orchestration-panel.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Component } from \"@caupulican/pi-tui\";\nimport { truncateToWidth, visibleWidth } from \"@caupulican/pi-tui\";\nimport { renderTitleBadge, type TitleBadgeStatus } from \"../../modes/interactive/components/tool-title.ts\";\nimport type { Theme, ThemeColor } from \"../../modes/interactive/theme/theme.ts\";\nimport type { LaneRecord } from \"../autonomy/lane-tracker.ts\";\nimport type { TaskStep, TaskStepsState } from \"../tasks/task-state.ts\";\n\nexport type OrchestrationRowStatus =\n\t| \"pending\"\n\t| \"queued\"\n\t| \"running\"\n\t| \"in_progress\"\n\t| \"completed\"\n\t| \"succeeded\"\n\t| \"blocked\"\n\t| \"failed\"\n\t| \"timeout\"\n\t| \"budget_exhausted\"\n\t| \"cancelled\"\n\t| \"canceled\"\n\t| \"reviewed\"\n\t| \"info\";\n\nexport interface OrchestrationPanelRow {\n\tstatus: OrchestrationRowStatus;\n\tlabel: string;\n\tsection?: string;\n\tmeta?: readonly string[];\n\tdetails?: readonly string[];\n}\n\nexport interface OrchestrationPanelNotice {\n\tstatus: \"info\" | \"success\" | \"warning\" | \"error\";\n\ttext: string;\n}\n\nexport interface OrchestrationPanelModel {\n\tlabel: string;\n\taction?: string;\n\tstatus?: TitleBadgeStatus;\n\tsummary?: readonly string[];\n\trows?: readonly OrchestrationPanelRow[];\n\tnotices?: readonly OrchestrationPanelNotice[];\n\temptyText?: string;\n\thiddenRowCount?: number;\n}\n\ninterface RowStyle {\n\ticon: string;\n\tcolor: ThemeColor;\n\tstrike?: boolean;\n\tbold?: boolean;\n}\n\nconst ROW_STYLES: Record<OrchestrationRowStatus, RowStyle> = {\n\tpending: { icon: \"○\", color: \"muted\" },\n\tqueued: { icon: \"◌\", color: \"warning\" },\n\trunning: { icon: \"●\", color: \"accent\", bold: true },\n\tin_progress: { icon: \"●\", color: \"accent\", bold: true },\n\tcompleted: { icon: \"✓\", color: \"success\", strike: true },\n\tsucceeded: { icon: \"✓\", color: \"success\" },\n\tblocked: { icon: \"!\", color: \"warning\", bold: true },\n\tfailed: { icon: \"×\", color: \"error\", bold: true },\n\ttimeout: { icon: \"×\", color: \"warning\" },\n\tbudget_exhausted: { icon: \"!\", color: \"warning\" },\n\tcancelled: { icon: \"–\", color: \"muted\", strike: true },\n\tcanceled: { icon: \"–\", color: \"muted\", strike: true },\n\treviewed: { icon: \"✓\", color: \"success\" },\n\tinfo: { icon: \"·\", color: \"muted\" },\n};\n\nconst NOTICE_STYLES: Record<OrchestrationPanelNotice[\"status\"], { icon: string; color: ThemeColor }> = {\n\tinfo: { icon: \"·\", color: \"muted\" },\n\tsuccess: { icon: \"✓\", color: \"success\" },\n\twarning: { icon: \"!\", color: \"warning\" },\n\terror: { icon: \"×\", color: \"error\" },\n};\n\nexport function taskStepPanelRow(step: TaskStep): OrchestrationPanelRow {\n\tconst meta = [\n\t\tstep.priority === \"high\" ? \"high priority\" : undefined,\n\t\tstep.owner ? `@${step.owner}` : undefined,\n\t\tstep.requirementIds?.length\n\t\t\t? `${step.requirementIds.length} requirement${step.requirementIds.length === 1 ? \"\" : \"s\"}`\n\t\t\t: undefined,\n\t\tstep.evidence.length ? `${step.evidence.length} evidence` : undefined,\n\t].filter((value): value is string => value !== undefined);\n\tconst details = [\n\t\t...step.notes.slice(-2).map((note) => `note: ${note}`),\n\t\t...step.evidence.slice(-2).map((evidence) => `evidence: ${evidence}`),\n\t];\n\treturn {\n\t\tstatus: step.status,\n\t\tlabel: step.status === \"in_progress\" ? (step.activeForm ?? step.content) : step.content,\n\t\tmeta,\n\t\tdetails,\n\t};\n}\n\n/** Build the quiet below-editor view from native session truth. No active work means no widget. */\nexport function createOrchestrationActivityModel(\n\ttaskState: TaskStepsState | undefined,\n\tlaneRecords: readonly LaneRecord[],\n): OrchestrationPanelModel | undefined {\n\tconst openSteps =\n\t\ttaskState?.steps.filter((step) => step.status !== \"completed\" && step.status !== \"cancelled\") ?? [];\n\tconst orderedSteps = [\n\t\t...openSteps.filter((step) => step.status === \"in_progress\"),\n\t\t...openSteps.filter((step) => step.status === \"blocked\"),\n\t\t...openSteps.filter((step) => step.status === \"pending\"),\n\t];\n\tconst activeLanes = laneRecords.filter(\n\t\t(lane) =>\n\t\t\t(lane.type === \"worker\" || lane.type === \"tmux-worker\") &&\n\t\t\t(lane.status === \"running\" || lane.status === \"queued\"),\n\t);\n\tif (openSteps.length === 0 && activeLanes.length === 0) return undefined;\n\n\tconst taskRows = orderedSteps.slice(0, 5).map((step) => ({ ...taskStepPanelRow(step), section: \"Steps\" }));\n\tconst laneRows: OrchestrationPanelRow[] = activeLanes.slice(0, 3).map((lane) => ({\n\t\tstatus: lane.status,\n\t\tlabel: lane.label ?? lane.laneId,\n\t\tsection: \"Agents\",\n\t\tmeta: [\n\t\t\tlane.label ? lane.laneId : undefined,\n\t\t\tlane.profileId ? `profile ${lane.profileId}` : undefined,\n\t\t\tlane.type === \"tmux-worker\" ? \"tmux\" : undefined,\n\t\t].filter((value): value is string => value !== undefined),\n\t}));\n\tconst runningLanes = activeLanes.filter((lane) => lane.status === \"running\").length;\n\tconst queuedLanes = activeLanes.length - runningLanes;\n\tconst blockedSteps = openSteps.filter((step) => step.status === \"blocked\").length;\n\tconst workingSteps = openSteps.filter((step) => step.status === \"in_progress\").length;\n\tconst evidenceMissing = taskState?.steps.some((step) => step.status === \"completed\" && step.evidence.length === 0);\n\treturn {\n\t\tlabel: \"work\",\n\t\taction: workingSteps + runningLanes > 0 ? \"active\" : \"ready\",\n\t\tstatus: blockedSteps > 0 ? \"warning\" : workingSteps + runningLanes > 0 ? \"running\" : \"idle\",\n\t\tsummary: [\n\t\t\topenSteps.length ? `${openSteps.length} step${openSteps.length === 1 ? \"\" : \"s\"}` : undefined,\n\t\t\trunningLanes ? `${runningLanes} agent${runningLanes === 1 ? \"\" : \"s\"}` : undefined,\n\t\t\tqueuedLanes ? `${queuedLanes} queued` : undefined,\n\t\t].filter((value): value is string => value !== undefined),\n\t\trows: [...taskRows, ...laneRows],\n\t\thiddenRowCount: Math.max(0, openSteps.length + activeLanes.length - taskRows.length - laneRows.length),\n\t\tnotices: evidenceMissing\n\t\t\t? [{ status: \"warning\", text: \"Completed work still needs attached evidence.\" }]\n\t\t\t: undefined,\n\t};\n}\n\nfunction renderRow(theme: Theme, row: OrchestrationPanelRow, width: number, expanded: boolean): string[] {\n\tconst style = ROW_STYLES[row.status];\n\tconst prefix = `  ${theme.fg(style.color, style.icon)} `;\n\tconst meta = row.meta?.filter(Boolean).join(\" · \") ?? \"\";\n\tconst suffix = meta ? `  ${theme.fg(\"dim\", meta)}` : \"\";\n\tconst labelWidth = Math.max(4, width - visibleWidth(prefix) - visibleWidth(suffix));\n\tconst clippedLabel = truncateToWidth(row.label, labelWidth, \"…\");\n\tlet label = style.bold ? theme.bold(clippedLabel) : clippedLabel;\n\tif (style.strike) label = theme.strikethrough(label);\n\tconst lines = [`${prefix}${theme.fg(style.strike ? \"dim\" : \"text\", label)}${suffix}`];\n\tif (expanded) {\n\t\tfor (const detail of row.details ?? []) {\n\t\t\tlines.push(`    ${theme.fg(\"dim\", truncateToWidth(detail, Math.max(4, width - 4), \"…\"))}`);\n\t\t}\n\t}\n\treturn lines;\n}\n\nexport function renderOrchestrationPanelLines(\n\ttheme: Theme,\n\tmodel: OrchestrationPanelModel,\n\twidth: number,\n\texpanded = false,\n): string[] {\n\tconst safeWidth = Math.max(1, width);\n\tconst title = renderTitleBadge(theme, {\n\t\tlabel: model.label,\n\t\taction: model.action,\n\t\tstatus: model.status ?? \"info\",\n\t});\n\tconst summary = model.summary?.filter(Boolean).join(theme.fg(\"dim\", \" · \")) ?? \"\";\n\tconst lines = [summary ? `${title}  ${theme.fg(\"dim\", summary)}` : title];\n\tconst rows = model.rows ?? [];\n\tif (rows.length > 0) {\n\t\tlet section: string | undefined;\n\t\tfor (const row of rows) {\n\t\t\tif (row.section && row.section !== section) {\n\t\t\t\tsection = row.section;\n\t\t\t\tlines.push(`  ${theme.fg(\"muted\", theme.bold(row.section))}`);\n\t\t\t}\n\t\t\tlines.push(...renderRow(theme, row, safeWidth, expanded));\n\t\t}\n\t} else if (model.emptyText) {\n\t\tlines.push(`  ${theme.fg(\"muted\", model.emptyText)}`);\n\t}\n\tif ((model.hiddenRowCount ?? 0) > 0) {\n\t\tlines.push(`  ${theme.fg(\"dim\", `… ${model.hiddenRowCount} more`)}`);\n\t}\n\tfor (const notice of model.notices ?? []) {\n\t\tconst style = NOTICE_STYLES[notice.status];\n\t\tlines.push(`  ${theme.fg(style.color, style.icon)} ${theme.fg(\"dim\", notice.text)}`);\n\t}\n\treturn lines.map((line) => truncateToWidth(line, safeWidth, \"\"));\n}\n\nexport class OrchestrationPanelComponent implements Component {\n\tprivate cachedWidth?: number;\n\tprivate cachedLines?: string[];\n\tprivate readonly theme: Theme;\n\tprivate readonly model: OrchestrationPanelModel;\n\tprivate readonly expanded: boolean;\n\n\tconstructor(theme: Theme, model: OrchestrationPanelModel, expanded = false) {\n\t\tthis.theme = theme;\n\t\tthis.model = model;\n\t\tthis.expanded = expanded;\n\t}\n\n\trender(width: number): string[] {\n\t\tif (this.cachedWidth === width && this.cachedLines) return this.cachedLines;\n\t\tthis.cachedWidth = width;\n\t\tthis.cachedLines = renderOrchestrationPanelLines(this.theme, this.model, width, this.expanded);\n\t\treturn this.cachedLines;\n\t}\n\n\tinvalidate(): void {\n\t\tthis.cachedWidth = undefined;\n\t\tthis.cachedLines = undefined;\n\t}\n}\n\nexport function emptyOrchestrationCall(): Component {\n\treturn {\n\t\trender: () => [],\n\t\tinvalidate() {},\n\t};\n}\n"]}

package/dist/core/tools/run-process.d.ts

@@ -0,0 +1,26 @@
+import type { AgentTool } from "@caupulican/pi-agent-core";
+import { type Static, Type } from "typebox";
+import { spawnProcess } from "../../utils/child-process.ts";
+import type { ToolDefinition } from "../extensions/types.ts";
+import type { OrchestrationExecutionPolicy } from "../orchestration/contracts.ts";
+declare const runProcessSchema: Type.TObject<{
+    executable: Type.TString;
+    args: Type.TOptional<Type.TArray<Type.TString>>;
+}>;
+export type RunProcessInput = Static<typeof runProcessSchema>;
+export interface RunProcessDetails {
+    outcome: "exited" | "failed" | "aborted" | "timeout" | "output_limit";
+    executable: string;
+    exitCode: number | null;
+    durationMs: number;
+    truncated: boolean;
+}
+export interface RunProcessToolOptions {
+    policy: OrchestrationExecutionPolicy;
+    maxWallClockMs: number;
+    spawn?: typeof spawnProcess;
+}
+export declare function createRunProcessToolDefinition(cwd: string, options: RunProcessToolOptions): ToolDefinition;
+export declare function createRunProcessTool(cwd: string, options: RunProcessToolOptions): AgentTool;
+export {};
+//# sourceMappingURL=run-process.d.ts.map

package/dist/core/tools/run-process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-process.d.ts","sourceRoot":"","sources":["../../../src/core/tools/run-process.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAsC,MAAM,8BAA8B,CAAC;AAChG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAGlF,QAAA,MAAM,gBAAgB;;;EAMrB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE9D,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,cAAc,CAAC;IACtE,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,4BAA4B,CAAC;IACrC,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,YAAY,CAAC;CAC5B;AAuDD,wBAAgB,8BAA8B,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,cAAc,CA8E1G;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAE3F","sourcesContent":["import type { ChildProcess } from \"node:child_process\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport type { OrchestrationExecutionPolicy } from \"../orchestration/contracts.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst runProcessSchema = Type.Object(\n\t{\n\t\texecutable: Type.String({ description: \"Exact owner-allowed executable name or path.\" }),\n\t\targs: Type.Optional(Type.Array(Type.String(), { description: \"Direct argv entries. No shell parsing occurs.\" })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type RunProcessInput = Static<typeof runProcessSchema>;\n\nexport interface RunProcessDetails {\n\toutcome: \"exited\" | \"failed\" | \"aborted\" | \"timeout\" | \"output_limit\";\n\texecutable: string;\n\texitCode: number | null;\n\tdurationMs: number;\n\ttruncated: boolean;\n}\n\nexport interface RunProcessToolOptions {\n\tpolicy: OrchestrationExecutionPolicy;\n\tmaxWallClockMs: number;\n\tspawn?: typeof spawnProcess;\n}\n\nconst SAFE_ENVIRONMENT_VARIABLES = [\n\t\"PATH\",\n\t\"PATHEXT\",\n\t\"SystemRoot\",\n\t\"WINDIR\",\n\t\"COMSPEC\",\n\t\"TMPDIR\",\n\t\"TMP\",\n\t\"TEMP\",\n] as const;\n\nfunction scopedEnvironment(allowedNames: readonly string[]): NodeJS.ProcessEnv {\n\tconst names = new Set<string>([...SAFE_ENVIRONMENT_VARIABLES, ...allowedNames]);\n\tconst environment: NodeJS.ProcessEnv = {};\n\tfor (const name of names) {\n\t\tconst value = process.env[name];\n\t\tif (value !== undefined) environment[name] = value;\n\t}\n\treturn environment;\n}\n\nfunction collectBoundedOutput(\n\tchild: ChildProcess,\n\tmaxBytes: number,\n\tabort: () => void,\n): {\n\tread(): { stdout: string; stderr: string; truncated: boolean };\n} {\n\tlet remaining = maxBytes;\n\tlet truncated = false;\n\tconst stdout: Buffer[] = [];\n\tconst stderr: Buffer[] = [];\n\tconst collect = (target: Buffer[]) => (chunk: Buffer) => {\n\t\tif (remaining <= 0) return;\n\t\tconst retained = chunk.subarray(0, remaining);\n\t\ttarget.push(retained);\n\t\tremaining -= retained.length;\n\t\tif (retained.length < chunk.length || remaining === 0) {\n\t\t\ttruncated = true;\n\t\t\tabort();\n\t\t}\n\t};\n\tchild.stdout?.on(\"data\", collect(stdout));\n\tchild.stderr?.on(\"data\", collect(stderr));\n\treturn {\n\t\tread: () => ({\n\t\t\tstdout: Buffer.concat(stdout).toString(\"utf-8\"),\n\t\t\tstderr: Buffer.concat(stderr).toString(\"utf-8\"),\n\t\t\ttruncated,\n\t\t}),\n\t};\n}\n\nexport function createRunProcessToolDefinition(cwd: string, options: RunProcessToolOptions): ToolDefinition {\n\tconst allowedExecutables = new Set(options.policy.allowedExecutables);\n\treturn {\n\t\tname: \"run_process\",\n\t\tlabel: \"Run Process\",\n\t\tdescription: `Run one owner-allowed executable using direct argv without a shell. Allowed: ${options.policy.allowedExecutables.join(\", \")}.`,\n\t\tpromptSnippet: \"Run an owner-allowed executable through a constrained direct-argv launcher (not OS isolation).\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use only an executable listed by the profile. Arguments are passed literally; shell operators and interpolation are unavailable.\",\n\t\t\t\"Treat a non-zero exit code, timeout, abort, or output-limit termination as failure.\",\n\t\t],\n\t\tparameters: runProcessSchema,\n\t\tasync execute(_toolCallId, input: RunProcessInput, signal) {\n\t\t\tif (!allowedExecutables.has(input.executable)) {\n\t\t\t\tthrow new Error(`process_executable_denied: '${input.executable}' is not owner-allowed.`);\n\t\t\t}\n\t\t\tconst args = input.args ?? [];\n\t\t\tif (input.executable.includes(\"\\0\") || args.some((argument) => argument.includes(\"\\0\"))) {\n\t\t\t\tthrow new Error(\"process_argument_invalid: executable and argv must not contain NUL bytes.\");\n\t\t\t}\n\t\t\tconst startedAt = Date.now();\n\t\t\tconst outputLimitAbort = new AbortController();\n\t\t\tlet outputLimitReached = false;\n\t\t\tconst child = (options.spawn ?? spawnProcess)(input.executable, [...args], {\n\t\t\t\tcwd,\n\t\t\t\tenv: scopedEnvironment(options.policy.allowedEnvironmentVariables),\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\twindowsHide: true,\n\t\t\t});\n\t\t\tconst output = collectBoundedOutput(child, options.policy.maxOutputBytes, () => {\n\t\t\t\toutputLimitReached = true;\n\t\t\t\toutputLimitAbort.abort();\n\t\t\t});\n\t\t\tconst combinedAbort = new AbortController();\n\t\t\tconst abort = () => combinedAbort.abort();\n\t\t\tif (signal?.aborted || outputLimitAbort.signal.aborted) abort();\n\t\t\telse {\n\t\t\t\tsignal?.addEventListener(\"abort\", abort, { once: true });\n\t\t\t\toutputLimitAbort.signal.addEventListener(\"abort\", abort, { once: true });\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal: combinedAbort.signal,\n\t\t\t\t\ttimeoutMs: options.maxWallClockMs > 0 ? options.maxWallClockMs : undefined,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tconst captured = output.read();\n\t\t\t\tconst outcome: RunProcessDetails[\"outcome\"] = outputLimitReached\n\t\t\t\t\t? \"output_limit\"\n\t\t\t\t\t: terminal.reason === \"timeout\"\n\t\t\t\t\t\t? \"timeout\"\n\t\t\t\t\t\t: terminal.reason === \"aborted\"\n\t\t\t\t\t\t\t? \"aborted\"\n\t\t\t\t\t\t\t: terminal.code === 0\n\t\t\t\t\t\t\t\t? \"exited\"\n\t\t\t\t\t\t\t\t: \"failed\";\n\t\t\t\tconst body = [\n\t\t\t\t\t`outcome: ${outcome}`,\n\t\t\t\t\t`exitCode: ${terminal.code ?? \"null\"}`,\n\t\t\t\t\tcaptured.stdout ? `stdout:\\n${captured.stdout}` : \"stdout: (empty)\",\n\t\t\t\t\tcaptured.stderr ? `stderr:\\n${captured.stderr}` : \"stderr: (empty)\",\n\t\t\t\t].join(\"\\n\");\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\" as const, text: body }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\toutcome,\n\t\t\t\t\t\texecutable: input.executable,\n\t\t\t\t\t\texitCode: terminal.code,\n\t\t\t\t\t\tdurationMs: Date.now() - startedAt,\n\t\t\t\t\t\ttruncated: captured.truncated,\n\t\t\t\t\t} satisfies RunProcessDetails,\n\t\t\t\t};\n\t\t\t} finally {\n\t\t\t\tsignal?.removeEventListener(\"abort\", abort);\n\t\t\t\toutputLimitAbort.signal.removeEventListener(\"abort\", abort);\n\t\t\t}\n\t\t},\n\t};\n}\n\nexport function createRunProcessTool(cwd: string, options: RunProcessToolOptions): AgentTool {\n\treturn wrapToolDefinition(createRunProcessToolDefinition(cwd, options));\n}\n"]}

package/dist/core/tools/run-process.js

@@ -0,0 +1,138 @@
+import { Type } from "typebox";
+import { spawnProcess, waitForChildProcessWithTermination } from "../../utils/child-process.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const runProcessSchema = Type.Object({
+    executable: Type.String({ description: "Exact owner-allowed executable name or path." }),
+    args: Type.Optional(Type.Array(Type.String(), { description: "Direct argv entries. No shell parsing occurs." })),
+}, { additionalProperties: false });
+const SAFE_ENVIRONMENT_VARIABLES = [
+    "PATH",
+    "PATHEXT",
+    "SystemRoot",
+    "WINDIR",
+    "COMSPEC",
+    "TMPDIR",
+    "TMP",
+    "TEMP",
+];
+function scopedEnvironment(allowedNames) {
+    const names = new Set([...SAFE_ENVIRONMENT_VARIABLES, ...allowedNames]);
+    const environment = {};
+    for (const name of names) {
+        const value = process.env[name];
+        if (value !== undefined)
+            environment[name] = value;
+    }
+    return environment;
+}
+function collectBoundedOutput(child, maxBytes, abort) {
+    let remaining = maxBytes;
+    let truncated = false;
+    const stdout = [];
+    const stderr = [];
+    const collect = (target) => (chunk) => {
+        if (remaining <= 0)
+            return;
+        const retained = chunk.subarray(0, remaining);
+        target.push(retained);
+        remaining -= retained.length;
+        if (retained.length < chunk.length || remaining === 0) {
+            truncated = true;
+            abort();
+        }
+    };
+    child.stdout?.on("data", collect(stdout));
+    child.stderr?.on("data", collect(stderr));
+    return {
+        read: () => ({
+            stdout: Buffer.concat(stdout).toString("utf-8"),
+            stderr: Buffer.concat(stderr).toString("utf-8"),
+            truncated,
+        }),
+    };
+}
+export function createRunProcessToolDefinition(cwd, options) {
+    const allowedExecutables = new Set(options.policy.allowedExecutables);
+    return {
+        name: "run_process",
+        label: "Run Process",
+        description: `Run one owner-allowed executable using direct argv without a shell. Allowed: ${options.policy.allowedExecutables.join(", ")}.`,
+        promptSnippet: "Run an owner-allowed executable through a constrained direct-argv launcher (not OS isolation).",
+        promptGuidelines: [
+            "Use only an executable listed by the profile. Arguments are passed literally; shell operators and interpolation are unavailable.",
+            "Treat a non-zero exit code, timeout, abort, or output-limit termination as failure.",
+        ],
+        parameters: runProcessSchema,
+        async execute(_toolCallId, input, signal) {
+            if (!allowedExecutables.has(input.executable)) {
+                throw new Error(`process_executable_denied: '${input.executable}' is not owner-allowed.`);
+            }
+            const args = input.args ?? [];
+            if (input.executable.includes("\0") || args.some((argument) => argument.includes("\0"))) {
+                throw new Error("process_argument_invalid: executable and argv must not contain NUL bytes.");
+            }
+            const startedAt = Date.now();
+            const outputLimitAbort = new AbortController();
+            let outputLimitReached = false;
+            const child = (options.spawn ?? spawnProcess)(input.executable, [...args], {
+                cwd,
+                env: scopedEnvironment(options.policy.allowedEnvironmentVariables),
+                stdio: ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+            const output = collectBoundedOutput(child, options.policy.maxOutputBytes, () => {
+                outputLimitReached = true;
+                outputLimitAbort.abort();
+            });
+            const combinedAbort = new AbortController();
+            const abort = () => combinedAbort.abort();
+            if (signal?.aborted || outputLimitAbort.signal.aborted)
+                abort();
+            else {
+                signal?.addEventListener("abort", abort, { once: true });
+                outputLimitAbort.signal.addEventListener("abort", abort, { once: true });
+            }
+            try {
+                const terminal = await waitForChildProcessWithTermination(child, {
+                    signal: combinedAbort.signal,
+                    timeoutMs: options.maxWallClockMs > 0 ? options.maxWallClockMs : undefined,
+                    killGraceMs: 2_000,
+                });
+                const captured = output.read();
+                const outcome = outputLimitReached
+                    ? "output_limit"
+                    : terminal.reason === "timeout"
+                        ? "timeout"
+                        : terminal.reason === "aborted"
+                            ? "aborted"
+                            : terminal.code === 0
+                                ? "exited"
+                                : "failed";
+                const body = [
+                    `outcome: ${outcome}`,
+                    `exitCode: ${terminal.code ?? "null"}`,
+                    captured.stdout ? `stdout:\n${captured.stdout}` : "stdout: (empty)",
+                    captured.stderr ? `stderr:\n${captured.stderr}` : "stderr: (empty)",
+                ].join("\n");
+                return {
+                    content: [{ type: "text", text: body }],
+                    details: {
+                        outcome,
+                        executable: input.executable,
+                        exitCode: terminal.code,
+                        durationMs: Date.now() - startedAt,
+                        truncated: captured.truncated,
+                    },
+                };
+            }
+            finally {
+                signal?.removeEventListener("abort", abort);
+                outputLimitAbort.signal.removeEventListener("abort", abort);
+            }
+        },
+    };
+}
+export function createRunProcessTool(cwd, options) {
+    return wrapToolDefinition(createRunProcessToolDefinition(cwd, options));
+}
+//# sourceMappingURL=run-process.js.map

package/dist/core/tools/run-process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-process.js","sourceRoot":"","sources":["../../../src/core/tools/run-process.ts"],"names":[],"mappings":"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","sourcesContent":["import type { ChildProcess } from \"node:child_process\";\nimport type { AgentTool } from \"@caupulican/pi-agent-core\";\nimport { type Static, Type } from \"typebox\";\nimport { spawnProcess, waitForChildProcessWithTermination } from \"../../utils/child-process.ts\";\nimport type { ToolDefinition } from \"../extensions/types.ts\";\nimport type { OrchestrationExecutionPolicy } from \"../orchestration/contracts.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\nconst runProcessSchema = Type.Object(\n\t{\n\t\texecutable: Type.String({ description: \"Exact owner-allowed executable name or path.\" }),\n\t\targs: Type.Optional(Type.Array(Type.String(), { description: \"Direct argv entries. No shell parsing occurs.\" })),\n\t},\n\t{ additionalProperties: false },\n);\n\nexport type RunProcessInput = Static<typeof runProcessSchema>;\n\nexport interface RunProcessDetails {\n\toutcome: \"exited\" | \"failed\" | \"aborted\" | \"timeout\" | \"output_limit\";\n\texecutable: string;\n\texitCode: number | null;\n\tdurationMs: number;\n\ttruncated: boolean;\n}\n\nexport interface RunProcessToolOptions {\n\tpolicy: OrchestrationExecutionPolicy;\n\tmaxWallClockMs: number;\n\tspawn?: typeof spawnProcess;\n}\n\nconst SAFE_ENVIRONMENT_VARIABLES = [\n\t\"PATH\",\n\t\"PATHEXT\",\n\t\"SystemRoot\",\n\t\"WINDIR\",\n\t\"COMSPEC\",\n\t\"TMPDIR\",\n\t\"TMP\",\n\t\"TEMP\",\n] as const;\n\nfunction scopedEnvironment(allowedNames: readonly string[]): NodeJS.ProcessEnv {\n\tconst names = new Set<string>([...SAFE_ENVIRONMENT_VARIABLES, ...allowedNames]);\n\tconst environment: NodeJS.ProcessEnv = {};\n\tfor (const name of names) {\n\t\tconst value = process.env[name];\n\t\tif (value !== undefined) environment[name] = value;\n\t}\n\treturn environment;\n}\n\nfunction collectBoundedOutput(\n\tchild: ChildProcess,\n\tmaxBytes: number,\n\tabort: () => void,\n): {\n\tread(): { stdout: string; stderr: string; truncated: boolean };\n} {\n\tlet remaining = maxBytes;\n\tlet truncated = false;\n\tconst stdout: Buffer[] = [];\n\tconst stderr: Buffer[] = [];\n\tconst collect = (target: Buffer[]) => (chunk: Buffer) => {\n\t\tif (remaining <= 0) return;\n\t\tconst retained = chunk.subarray(0, remaining);\n\t\ttarget.push(retained);\n\t\tremaining -= retained.length;\n\t\tif (retained.length < chunk.length || remaining === 0) {\n\t\t\ttruncated = true;\n\t\t\tabort();\n\t\t}\n\t};\n\tchild.stdout?.on(\"data\", collect(stdout));\n\tchild.stderr?.on(\"data\", collect(stderr));\n\treturn {\n\t\tread: () => ({\n\t\t\tstdout: Buffer.concat(stdout).toString(\"utf-8\"),\n\t\t\tstderr: Buffer.concat(stderr).toString(\"utf-8\"),\n\t\t\ttruncated,\n\t\t}),\n\t};\n}\n\nexport function createRunProcessToolDefinition(cwd: string, options: RunProcessToolOptions): ToolDefinition {\n\tconst allowedExecutables = new Set(options.policy.allowedExecutables);\n\treturn {\n\t\tname: \"run_process\",\n\t\tlabel: \"Run Process\",\n\t\tdescription: `Run one owner-allowed executable using direct argv without a shell. Allowed: ${options.policy.allowedExecutables.join(\", \")}.`,\n\t\tpromptSnippet: \"Run an owner-allowed executable through a constrained direct-argv launcher (not OS isolation).\",\n\t\tpromptGuidelines: [\n\t\t\t\"Use only an executable listed by the profile. Arguments are passed literally; shell operators and interpolation are unavailable.\",\n\t\t\t\"Treat a non-zero exit code, timeout, abort, or output-limit termination as failure.\",\n\t\t],\n\t\tparameters: runProcessSchema,\n\t\tasync execute(_toolCallId, input: RunProcessInput, signal) {\n\t\t\tif (!allowedExecutables.has(input.executable)) {\n\t\t\t\tthrow new Error(`process_executable_denied: '${input.executable}' is not owner-allowed.`);\n\t\t\t}\n\t\t\tconst args = input.args ?? [];\n\t\t\tif (input.executable.includes(\"\\0\") || args.some((argument) => argument.includes(\"\\0\"))) {\n\t\t\t\tthrow new Error(\"process_argument_invalid: executable and argv must not contain NUL bytes.\");\n\t\t\t}\n\t\t\tconst startedAt = Date.now();\n\t\t\tconst outputLimitAbort = new AbortController();\n\t\t\tlet outputLimitReached = false;\n\t\t\tconst child = (options.spawn ?? spawnProcess)(input.executable, [...args], {\n\t\t\t\tcwd,\n\t\t\t\tenv: scopedEnvironment(options.policy.allowedEnvironmentVariables),\n\t\t\t\tstdio: [\"ignore\", \"pipe\", \"pipe\"],\n\t\t\t\twindowsHide: true,\n\t\t\t});\n\t\t\tconst output = collectBoundedOutput(child, options.policy.maxOutputBytes, () => {\n\t\t\t\toutputLimitReached = true;\n\t\t\t\toutputLimitAbort.abort();\n\t\t\t});\n\t\t\tconst combinedAbort = new AbortController();\n\t\t\tconst abort = () => combinedAbort.abort();\n\t\t\tif (signal?.aborted || outputLimitAbort.signal.aborted) abort();\n\t\t\telse {\n\t\t\t\tsignal?.addEventListener(\"abort\", abort, { once: true });\n\t\t\t\toutputLimitAbort.signal.addEventListener(\"abort\", abort, { once: true });\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst terminal = await waitForChildProcessWithTermination(child, {\n\t\t\t\t\tsignal: combinedAbort.signal,\n\t\t\t\t\ttimeoutMs: options.maxWallClockMs > 0 ? options.maxWallClockMs : undefined,\n\t\t\t\t\tkillGraceMs: 2_000,\n\t\t\t\t});\n\t\t\t\tconst captured = output.read();\n\t\t\t\tconst outcome: RunProcessDetails[\"outcome\"] = outputLimitReached\n\t\t\t\t\t? \"output_limit\"\n\t\t\t\t\t: terminal.reason === \"timeout\"\n\t\t\t\t\t\t? \"timeout\"\n\t\t\t\t\t\t: terminal.reason === \"aborted\"\n\t\t\t\t\t\t\t? \"aborted\"\n\t\t\t\t\t\t\t: terminal.code === 0\n\t\t\t\t\t\t\t\t? \"exited\"\n\t\t\t\t\t\t\t\t: \"failed\";\n\t\t\t\tconst body = [\n\t\t\t\t\t`outcome: ${outcome}`,\n\t\t\t\t\t`exitCode: ${terminal.code ?? \"null\"}`,\n\t\t\t\t\tcaptured.stdout ? `stdout:\\n${captured.stdout}` : \"stdout: (empty)\",\n\t\t\t\t\tcaptured.stderr ? `stderr:\\n${captured.stderr}` : \"stderr: (empty)\",\n\t\t\t\t].join(\"\\n\");\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\" as const, text: body }],\n\t\t\t\t\tdetails: {\n\t\t\t\t\t\toutcome,\n\t\t\t\t\t\texecutable: input.executable,\n\t\t\t\t\t\texitCode: terminal.code,\n\t\t\t\t\t\tdurationMs: Date.now() - startedAt,\n\t\t\t\t\t\ttruncated: captured.truncated,\n\t\t\t\t\t} satisfies RunProcessDetails,\n\t\t\t\t};\n\t\t\t} finally {\n\t\t\t\tsignal?.removeEventListener(\"abort\", abort);\n\t\t\t\toutputLimitAbort.signal.removeEventListener(\"abort\", abort);\n\t\t\t}\n\t\t},\n\t};\n}\n\nexport function createRunProcessTool(cwd: string, options: RunProcessToolOptions): AgentTool {\n\treturn wrapToolDefinition(createRunProcessToolDefinition(cwd, options));\n}\n"]}

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

@@ -5,9 +5,14 @@ export type ShellContractRoute = {
     kind: "powershell";
     command: string;
     argv: readonly string[];
+} | {
+    kind: "python-engine";
+    command: string;
 } | {
     kind: "unsupported";
     error: string;
 };
-export declare function routeShellContract(command: string, platform?: NodeJS.Platform): ShellContractRoute;
+export declare function routeShellContract(command: string, platform?: NodeJS.Platform, options?: {
+    pythonEngine?: boolean;
+}): ShellContractRoute;
 //# sourceMappingURL=shell-contract-router.d.ts.map

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

@@ -1 +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;AAqS1C,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\tconst source = command.trim();\n\tfor (let index = 0; index < source.length; index++) {\n\t\tconst character = source[index];\n\t\tconst nextCharacter = source[index + 1];\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\tif (nextCharacter && '\"$`\\\\'.includes(nextCharacter)) {\n\t\t\t\t\ttoken += nextCharacter;\n\t\t\t\t\ttokenStarted = true;\n\t\t\t\t\tindex++;\n\t\t\t\t} else {\n\t\t\t\t\ttoken += character;\n\t\t\t\t\ttokenStarted = true;\n\t\t\t\t}\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\tif (/^[A-Za-z]:/u.test(token) || token.startsWith(\"\\\\\\\\\")) {\n\t\t\t\ttoken += character;\n\t\t\t\ttokenStarted = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (token === \"\" && nextCharacter === \"\\\\\") {\n\t\t\t\ttoken = \"\\\\\\\\\";\n\t\t\t\ttokenStarted = true;\n\t\t\t\tindex++;\n\t\t\t\tcontinue;\n\t\t\t}\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 === \"#\" || (character === \"~\" && token === \"\")) {\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\tconst includeHidden = [...parsed.flags].some((flag) => flag.includes(\"a\") || flag.includes(\"A\"));\n\tconst hiddenFilter = includeHidden ? \"\" : \" | Where-Object { -not $_.Name.StartsWith('.') }\";\n\treturn `[string[]]$items = @(Get-ChildItem -LiteralPath ${quotePowerShell(target)}${includeHidden ? \" -Force\" : \"\"} -ErrorAction Stop${hiddenFilter} | 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 `foreach ($path in ${powershellArray(parsed.operands)}) { [Console]::Out.Write([IO.File]::ReadAllText($path)) }`;\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 `[string[]]$matches = @(Select-String -LiteralPath ${quotePowerShell(argv[2])} -Pattern ${quotePowerShell(argv[1])} -CaseSensitive -ErrorAction Stop | ForEach-Object { $_.Line }); if ($matches.Count -eq 0) { exit 1 }; $matches`;\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\tconst force = [...parsed.flags].some((flag) => flag.includes(\"f\"));\n\treturn `foreach ($path in ${powershellArray(parsed.operands)}) { if (Test-Path -LiteralPath $path) { Remove-Item -LiteralPath $path -Force${recursive ? \" -Recurse\" : \"\"} -ErrorAction Stop }${force ? \"\" : ' else { throw \"rm: path not found: $path\" }'} }`;\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\tconst rejectDirectoryWithoutRecursion =\n\t\t!move && parsed.flags.size === 0\n\t\t\t? `$sourceItem = Get-Item -LiteralPath ${quotePowerShell(source)} -Force -ErrorAction Stop; if ($sourceItem.PSIsContainer) { throw 'cp: source is a directory; use -r' }; `\n\t\t\t: \"\";\n\treturn `${rejectDirectoryWithoutRecursion}${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 $_${parsed.flags.has(\"-p\") ? \" -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\") {\n\t\tlet valueIndex = 1;\n\t\twhile (/^-n+$/u.test(argv[valueIndex] ?? \"\")) valueIndex++;\n\t\tif (/^-[neE]+$/u.test(argv[valueIndex] ?? \"\") && /[eE]/u.test(argv[valueIndex] ?? \"\")) return undefined;\n\t\tconst method = valueIndex > 1 ? \"Write\" : \"WriteLine\";\n\t\treturn `[Console]::Out.${method}((${powershellArray(argv.slice(valueIndex))} -join ' '))`;\n\t}\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"]}
+{"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,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAuS1C,wBAAgB,kBAAkB,CACjC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,CAAC,QAA2B,EAC5C,OAAO,CAAC,EAAE;IAAE,YAAY,CAAC,EAAE,OAAO,CAAA;CAAE,GAClC,kBAAkB,CAwDpB","sourcesContent":["export type ShellContractRoute =\n\t| { kind: \"passthrough\"; command: string }\n\t| { kind: \"powershell\"; command: string; argv: readonly string[] }\n\t| { kind: \"python-engine\"; command: string }\n\t| { kind: \"unsupported\"; error: string };\n\nconst STATE_MUTATOR_BUILTINS = new Set([\"cd\", \"export\", \"unset\"]);\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\tconst source = command.trim();\n\tfor (let index = 0; index < source.length; index++) {\n\t\tconst character = source[index];\n\t\tconst nextCharacter = source[index + 1];\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\tif (nextCharacter && '\"$`\\\\'.includes(nextCharacter)) {\n\t\t\t\t\ttoken += nextCharacter;\n\t\t\t\t\ttokenStarted = true;\n\t\t\t\t\tindex++;\n\t\t\t\t} else {\n\t\t\t\t\ttoken += character;\n\t\t\t\t\ttokenStarted = true;\n\t\t\t\t}\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\tif (/^[A-Za-z]:/u.test(token) || token.startsWith(\"\\\\\\\\\")) {\n\t\t\t\ttoken += character;\n\t\t\t\ttokenStarted = true;\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tif (token === \"\" && nextCharacter === \"\\\\\") {\n\t\t\t\ttoken = \"\\\\\\\\\";\n\t\t\t\ttokenStarted = true;\n\t\t\t\tindex++;\n\t\t\t\tcontinue;\n\t\t\t}\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 === \"#\" || (character === \"~\" && token === \"\")) {\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\tconst includeHidden = [...parsed.flags].some((flag) => flag.includes(\"a\") || flag.includes(\"A\"));\n\tconst hiddenFilter = includeHidden ? \"\" : \" | Where-Object { -not $_.Name.StartsWith('.') }\";\n\treturn `[string[]]$items = @(Get-ChildItem -LiteralPath ${quotePowerShell(target)}${includeHidden ? \" -Force\" : \"\"} -ErrorAction Stop${hiddenFilter} | 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 `foreach ($path in ${powershellArray(parsed.operands)}) { [Console]::Out.Write([IO.File]::ReadAllText($path)) }`;\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 `[string[]]$matches = @(Select-String -LiteralPath ${quotePowerShell(argv[2])} -Pattern ${quotePowerShell(argv[1])} -CaseSensitive -ErrorAction Stop | ForEach-Object { $_.Line }); if ($matches.Count -eq 0) { exit 1 }; $matches`;\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\tconst force = [...parsed.flags].some((flag) => flag.includes(\"f\"));\n\treturn `foreach ($path in ${powershellArray(parsed.operands)}) { if (Test-Path -LiteralPath $path) { Remove-Item -LiteralPath $path -Force${recursive ? \" -Recurse\" : \"\"} -ErrorAction Stop }${force ? \"\" : ' else { throw \"rm: path not found: $path\" }'} }`;\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\tconst rejectDirectoryWithoutRecursion =\n\t\t!move && parsed.flags.size === 0\n\t\t\t? `$sourceItem = Get-Item -LiteralPath ${quotePowerShell(source)} -Force -ErrorAction Stop; if ($sourceItem.PSIsContainer) { throw 'cp: source is a directory; use -r' }; `\n\t\t\t: \"\";\n\treturn `${rejectDirectoryWithoutRecursion}${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 $_${parsed.flags.has(\"-p\") ? \" -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\") {\n\t\tlet valueIndex = 1;\n\t\twhile (/^-n+$/u.test(argv[valueIndex] ?? \"\")) valueIndex++;\n\t\tif (/^-[neE]+$/u.test(argv[valueIndex] ?? \"\") && /[eE]/u.test(argv[valueIndex] ?? \"\")) return undefined;\n\t\tconst method = valueIndex > 1 ? \"Write\" : \"WriteLine\";\n\t\treturn `[Console]::Out.${method}((${powershellArray(argv.slice(valueIndex))} -join ' '))`;\n\t}\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(\n\tcommand: string,\n\tplatform: NodeJS.Platform = process.platform,\n\toptions?: { pythonEngine?: boolean },\n): ShellContractRoute {\n\tif (platform !== \"win32\") return { kind: \"passthrough\", command };\n\tconst pythonEngine = options?.pythonEngine === true;\n\tconst tokenized = tokenizePortableCommand(command);\n\n\t// Complex constructs (pipelines, redirection, expansion, quoting the tokenizer refuses, …) are\n\t// exactly the grammar the Python engine owns; with the engine off this is the original\n\t// fail-closed floor verbatim.\n\tif (!tokenized.ok || !tokenized.argv) {\n\t\tif (pythonEngine) return { kind: \"python-engine\", command };\n\t\treturn { kind: \"unsupported\", error: tokenized.error ?? UNSUPPORTED_OPERATOR_MESSAGE };\n\t}\n\n\tconst argv = tokenized.argv;\n\tconst commandName = argv[0].toLowerCase();\n\n\t// Inline env assignments (`NAME=value [cmd]`) are a state-mutating/expansion form the engine\n\t// supports (§2.1); with the engine off this is the original fail-closed floor verbatim.\n\tif (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(argv[0])) {\n\t\tif (pythonEngine) return { kind: \"python-engine\", command };\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\n\t// State mutators route to the engine unconditionally when it is enabled: the engine is the\n\t// sole state owner (D4), so `cd`/`export`/`unset` never execute against the PS floor.\n\tif (pythonEngine && STATE_MUTATOR_BUILTINS.has(commandName)) {\n\t\treturn { kind: \"python-engine\", command };\n\t}\n\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\t// The PS floor rejected the FORM (flags/argument shape); the engine supports the fuller\n\t\t// flag set for the same builtin (§2.2).\n\t\tif (pythonEngine) return { kind: \"python-engine\", command };\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"]}

package/dist/core/tools/shell-contract-router.js

@@ -1,3 +1,4 @@
+const STATE_MUTATOR_BUILTINS = new Set(["cd", "export", "unset"]);
 const BLOCKED_NESTED_SHELLS = new Set([
     "bash",
     "sh",
@@ -290,20 +291,36 @@ const ROUTED_BUILTIN_NAMES = new Set([
     "mkdir",
     "touch",
 ]);
-export function routeShellContract(command, platform = process.platform) {
+export function routeShellContract(command, platform = process.platform, options) {
     if (platform !== "win32")
         return { kind: "passthrough", command };
+    const pythonEngine = options?.pythonEngine === true;
     const tokenized = tokenizePortableCommand(command);
-    if (!tokenized.ok || !tokenized.argv)
+    // Complex constructs (pipelines, redirection, expansion, quoting the tokenizer refuses, …) are
+    // exactly the grammar the Python engine owns; with the engine off this is the original
+    // fail-closed floor verbatim.
+    if (!tokenized.ok || !tokenized.argv) {
+        if (pythonEngine)
+            return { kind: "python-engine", command };
         return { kind: "unsupported", error: tokenized.error ?? UNSUPPORTED_OPERATOR_MESSAGE };
+    }
     const argv = tokenized.argv;
     const commandName = argv[0].toLowerCase();
+    // Inline env assignments (`NAME=value [cmd]`) are a state-mutating/expansion form the engine
+    // supports (§2.1); with the engine off this is the original fail-closed floor verbatim.
     if (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(argv[0])) {
+        if (pythonEngine)
+            return { kind: "python-engine", command };
         return {
             kind: "unsupported",
             error: "Inline environment assignments are not supported. Configure the environment outside the shell command.",
         };
     }
+    // State mutators route to the engine unconditionally when it is enabled: the engine is the
+    // sole state owner (D4), so `cd`/`export`/`unset` never execute against the PS floor.
+    if (pythonEngine && STATE_MUTATOR_BUILTINS.has(commandName)) {
+        return { kind: "python-engine", command };
+    }
     if (BLOCKED_NESTED_SHELLS.has(commandName)) {
         return {
             kind: "unsupported",
@@ -314,6 +331,10 @@ export function routeShellContract(command, platform = process.platform) {
     if (builtIn)
         return { kind: "powershell", command: builtIn, argv };
     if (ROUTED_BUILTIN_NAMES.has(commandName)) {
+        // The PS floor rejected the FORM (flags/argument shape); the engine supports the fuller
+        // flag set for the same builtin (§2.2).
+        if (pythonEngine)
+            return { kind: "python-engine", command };
         return {
             kind: "unsupported",
             error: `Unsupported ${argv[0]} form on Windows. Use a simpler Bash-like form or Pi's dedicated read/search/edit tools.`,