@uipath/coder-tool 1.199.0-preview.116

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@uipath/coder-tool",
+  "license": "MIT",
+  "version": "1.199.0-preview.116",
+  "description": "Interactive coding agent (Pi) with UiPath LLM Gateway and BYO provider support.",
+  "type": "module",
+  "main": "./dist/tool.js",
+  "exports": {
+    ".": "./dist/tool.js"
+  },
+  "bin": {
+    "coder-tool": "./dist/index.js"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.6"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "gitHead": "c91f4f9738502a4b1ca2849631890fcf59304484"
+}

package/src/commands/chat.spec.ts

@@ -0,0 +1,224 @@
+import { Command } from "commander";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@earendil-works/pi-coding-agent", () => ({
+    main: vi.fn(),
+}));
+
+vi.mock("../providers/uipath", () => ({
+    createUiPathProviderExtension: vi.fn(() => ({
+        name: "uipath-llm-gateway",
+        factory: vi.fn(),
+    })),
+}));
+
+let guideExists = true;
+const GUIDE_TEXT = "# UiPath CLI (`uip`) — agent guidance\n(test copy)";
+vi.mock("@uipath/filesystem", () => ({
+    getFileSystem: () => ({
+        exists: (path: string) =>
+            Promise.resolve(guideExists && path.includes("uipath-cli.md")),
+        readFile: () => Promise.resolve(GUIDE_TEXT),
+    }),
+}));
+
+import { main } from "@earendil-works/pi-coding-agent";
+import { OutputFormatter } from "@uipath/common";
+import { registerChatCommand, withAgentGuide } from "./chat";
+
+function buildProgram(context?: { exit: (code: number) => void }): Command {
+    const program = new Command();
+    program.name("coder").exitOverride();
+    registerChatCommand(program, context, vi.fn());
+    return program;
+}
+
+function piArgs(): string[] {
+    return (vi.mocked(main).mock.calls[0]?.[0] ?? []) as string[];
+}
+
+describe("uip coder", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        guideExists = true;
+        process.exitCode = undefined;
+    });
+
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+
+    it("launches pi with the UiPath agent guide appended to the system prompt", async () => {
+        const program = buildProgram();
+
+        await program.parseAsync([], { from: "user" });
+
+        expect(main).toHaveBeenCalledTimes(1);
+        const args = piArgs();
+        expect(args[0]).toBe("--append-system-prompt");
+        // The guide is passed as text, not a file path, so the injection
+        // does not depend on Pi's file-or-literal argument resolution.
+        expect(args[1]).toBe(GUIDE_TEXT);
+        expect(args).toHaveLength(2);
+    });
+
+    it("forwards positional arguments and unknown options to pi", async () => {
+        const program = buildProgram();
+
+        await program.parseAsync(
+            ["-p", "--provider", "uipath", "--model", "gpt-4o", "hello"],
+            { from: "user" },
+        );
+
+        expect(piArgs().slice(2)).toEqual([
+            "-p",
+            "--provider",
+            "uipath",
+            "--model",
+            "gpt-4o",
+            "hello",
+        ]);
+    });
+
+    it("launches pi without the guide when the template is missing", async () => {
+        guideExists = false;
+        const program = buildProgram();
+
+        await program.parseAsync(["-p", "hi"], { from: "user" });
+
+        expect(piArgs()).toEqual(["-p", "hi"]);
+    });
+
+    it("does not inject the guide before pi package-management subcommands", () => {
+        expect(withAgentGuide(["install", "some-ext"], "/guide.md")).toEqual([
+            "install",
+            "some-ext",
+        ]);
+        expect(withAgentGuide(["-p", "hi"], "/guide.md")).toEqual([
+            "--append-system-prompt",
+            "/guide.md",
+            "-p",
+            "hi",
+        ]);
+    });
+
+    it("keeps the guide for prompts whose first word matches a subcommand name", () => {
+        // Pi routes package commands on args[0] only, so an unquoted prompt
+        // like `-p update the readme` is a prompt, not `pi update`.
+        expect(
+            withAgentGuide(["-p", "update", "the", "readme"], "/guide.md"),
+        ).toEqual([
+            "--append-system-prompt",
+            "/guide.md",
+            "-p",
+            "update",
+            "the",
+            "readme",
+        ]);
+    });
+
+    it("passes the uipath provider extension to pi", async () => {
+        const program = buildProgram();
+
+        await program.parseAsync([], { from: "user" });
+
+        const [, options] = vi.mocked(main).mock.calls[0] ?? [];
+        const factories =
+            (options as { extensionFactories?: unknown[] })
+                ?.extensionFactories ?? [];
+        expect(factories).toHaveLength(1);
+        expect(factories[0]).toMatchObject({ name: "uipath-llm-gateway" });
+    });
+
+    it("turns pi's non-zero process.exit into a failure envelope", async () => {
+        const errorSpy = vi
+            .spyOn(OutputFormatter, "error")
+            .mockImplementation(() => {});
+        vi.mocked(main).mockImplementation(async () => {
+            // Pi hard-exits on its own error paths instead of throwing.
+            process.exit(2);
+        });
+        const exit = vi.fn();
+        const program = buildProgram({ exit });
+
+        await program.parseAsync(["-p", "hi"], { from: "user" });
+
+        expect(errorSpy).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("exited with code 2"),
+            }),
+        );
+        expect(exit).toHaveBeenCalledWith(2);
+    });
+
+    it("handles process.exit from a fire-and-forget shutdown without an unhandled rejection", async () => {
+        // Pi's interactive quit (Ctrl+C / Ctrl+D) calls process.exit(0) from
+        // a floating promise chain, not from main()'s awaited stack.
+        const rejections: unknown[] = [];
+        const onRejection = (reason: unknown) => rejections.push(reason);
+        process.on("unhandledRejection", onRejection);
+        vi.mocked(main).mockImplementation(
+            () =>
+                new Promise<void>(() => {
+                    // never resolves — like an interactive session
+                    setTimeout(() => {
+                        void Promise.resolve().then(() => process.exit(0));
+                    }, 0);
+                }),
+        );
+        const exit = vi.fn();
+        const program = buildProgram({ exit });
+
+        await program.parseAsync([], { from: "user" });
+        await new Promise((resolve) => setImmediate(resolve));
+
+        process.off("unhandledRejection", onRejection);
+        expect(rejections).toEqual([]);
+        expect(exit).not.toHaveBeenCalled();
+    });
+
+    it("treats pi's process.exit(0) as success", async () => {
+        const errorSpy = vi
+            .spyOn(OutputFormatter, "error")
+            .mockImplementation(() => {});
+        vi.mocked(main).mockImplementation(async () => {
+            process.exit(0);
+        });
+        const exit = vi.fn();
+        const program = buildProgram({ exit });
+
+        await program.parseAsync(["-p", "hi"], { from: "user" });
+
+        expect(errorSpy).not.toHaveBeenCalled();
+        expect(exit).not.toHaveBeenCalled();
+    });
+
+    it("restores process.exit after pi finishes", async () => {
+        const originalExit = process.exit;
+        const program = buildProgram();
+
+        await program.parseAsync([], { from: "user" });
+
+        expect(process.exit).toBe(originalExit);
+    });
+
+    it("reports a failure envelope and exits 1 when pi fails to start", async () => {
+        const errorSpy = vi
+            .spyOn(OutputFormatter, "error")
+            .mockImplementation(() => {});
+        vi.mocked(main).mockRejectedValueOnce(new Error("pi exploded"));
+        const exit = vi.fn();
+        const program = buildProgram({ exit });
+
+        await program.parseAsync([], { from: "user" });
+
+        expect(errorSpy).toHaveBeenCalledWith(
+            expect.objectContaining({
+                Result: "Failure",
+                Message: expect.stringContaining("pi exploded"),
+            }),
+        );
+        expect(exit).toHaveBeenCalledWith(1);
+    });
+});

package/src/commands/chat.ts

@@ -0,0 +1,156 @@
+import { fileURLToPath } from "node:url";
+import {
+    type CommandContext,
+    OutputFormatter,
+    processContext,
+    RESULTS,
+} from "@uipath/common";
+import { getFileSystem } from "@uipath/filesystem";
+import type { Command } from "commander";
+import { createUiPathProviderExtension } from "../providers/uipath";
+
+/**
+ * Pi package-management subcommands. They must stay the first argv token,
+ * and they don't start an agent session, so no system prompt is injected.
+ */
+const PI_SUBCOMMANDS = new Set([
+    "install",
+    "remove",
+    "uninstall",
+    "update",
+    "list",
+    "config",
+]);
+
+/**
+ * Load the bundled UiPath CLI guide appended to Pi's system prompt.
+ * Lives at dist/templates/ in the published package (copied by
+ * tools/build-tool.ts) and at the package root when running from source.
+ * Returns the guide TEXT (not the path) so the injection does not depend
+ * on Pi's file-or-literal resolution of `--append-system-prompt`.
+ */
+export async function resolveAgentGuide(): Promise<string | undefined> {
+    const fs = getFileSystem();
+    const candidates = [
+        new URL("./templates/uipath-cli.md", import.meta.url),
+        new URL("../../templates/uipath-cli.md", import.meta.url),
+    ];
+    for (const url of candidates) {
+        const path = fileURLToPath(url);
+        if (await fs.exists(path)) {
+            const text = await fs.readFile(path, "utf-8");
+            return text ?? undefined;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Prepend `--append-system-prompt <guide>` so the agent knows how to drive
+ * the UiPath platform through `uip`. Skipped for Pi's package-management
+ * subcommands, which Pi routes on the first argv token only — a prompt like
+ * `-p update the readme` must still get the guide.
+ */
+export function withAgentGuide(
+    args: string[],
+    guideText: string | undefined,
+): string[] {
+    if (!guideText) {
+        return args;
+    }
+    const first = args[0];
+    if (first !== undefined && PI_SUBCOMMANDS.has(first)) {
+        return args;
+    }
+    return ["--append-system-prompt", guideText, ...args];
+}
+
+type HardExit = (code: number) => void;
+
+/**
+ * Run Pi's CLI entry point with `process.exit` intercepted. Pi hard-exits
+ * on both success and failure (deliberately, so misbehaving extensions
+ * cannot keep one-shot commands alive); the interception turns that into a
+ * return value so failures can be reported through the CLI envelope. The
+ * hard exit is re-applied after the command finishes its bookkeeping.
+ *
+ * The interception resolves a promise instead of throwing: Pi's interactive
+ * quit paths (Ctrl+C / Ctrl+D / signal handlers) call `process.exit` from
+ * fire-and-forget shutdown chains, where a throw would surface as an
+ * unhandled rejection instead of a clean exit.
+ */
+async function runPi(args: string[], hardExit?: HardExit): Promise<number> {
+    const { main } = await import("@earendil-works/pi-coding-agent");
+    const originalExit = process.exit;
+    let requestedExitCode: number | undefined;
+    let resolveExit: (code: number) => void = () => {};
+    const exitRequested = new Promise<number>((resolve) => {
+        resolveExit = resolve;
+    });
+    process.exit = ((code?: number | string | null) => {
+        requestedExitCode =
+            typeof code === "number" ? code : (process.exitCode ?? 0);
+        resolveExit(requestedExitCode);
+        return undefined as never;
+    }) as typeof process.exit;
+    try {
+        const mainDone = main(args, {
+            extensionFactories: [createUiPathProviderExtension()],
+        }).then(() => requestedExitCode ?? 0);
+        // If main settles after an exit was already requested, that outcome
+        // has nowhere to go — swallow it so it cannot become an unhandled
+        // rejection. The raced result below already carries the exit code.
+        mainDone.catch(() => {});
+        return await Promise.race([mainDone, exitRequested]);
+    } finally {
+        process.exit = originalExit;
+        // Preserve Pi's lifecycle: force the exit once telemetry and output
+        // (which run in microtasks before I/O callbacks) have completed.
+        const exit: HardExit = hardExit ?? ((code) => originalExit(code));
+        setImmediate(() => exit(process.exitCode ?? requestedExitCode ?? 0));
+    }
+}
+
+/**
+ * `uip coder [args...]` — the UiPath coding agent, powered by Pi.
+ *
+ * All arguments are forwarded verbatim to Pi, so the full Pi CLI surface
+ * stays available: no args opens the interactive TUI; `-p "<prompt>"` runs
+ * one prompt and exits; `--list-models` shows every provider/model;
+ * `--provider uipath --model <id>` pins the UiPath LLM Gateway;
+ * `--continue` resumes the previous session. See `uip coder --help`
+ * (rendered by Pi) for everything else.
+ */
+export function registerChatCommand(
+    command: Command,
+    context: CommandContext = processContext,
+    hardExit?: HardExit,
+): void {
+    command
+        .argument(
+            "[args...]",
+            "arguments forwarded to the Pi coding agent (see 'uip coder --help')",
+        )
+        .allowUnknownOption()
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .trackedAction(
+            context,
+            async (_args: string[], _options: unknown, cmd: Command) => {
+                const guide = await resolveAgentGuide();
+                const exitCode = await runPi(
+                    withAgentGuide(cmd.args, guide),
+                    hardExit,
+                );
+                if (exitCode !== 0) {
+                    OutputFormatter.error({
+                        Result: RESULTS.Failure,
+                        Message: `The coding agent exited with code ${exitCode}.`,
+                        Instructions:
+                            "Check the agent output above for the underlying error. Run 'uip coder --help' for usage, or 'uip login' if the uipath provider is missing.",
+                    });
+                    context.exit(exitCode);
+                }
+            },
+        );
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone entry point for coder-tool
+ * This allows the tool to be run independently for testing
+ */
+
+// Side-effect import: installs Command.prototype.trackedAction on this
+// bundle's commander copy before registerCommands touches it.
+import { setPreviewBuild } from "@uipath/common";
+import { Command } from "commander";
+import { metadata, registerCommands } from "./tool.js";
+
+// The standalone bin is a dev/test surface — opt into the preview-gated
+// command unconditionally. The CLI host gates on its own release channel.
+setPreviewBuild(true);
+
+const program = new Command();
+
+program
+    .name(metadata.commandPrefix)
+    .description(metadata.description)
+    .version(metadata.version);
+
+await registerCommands(program);
+
+program.parse(process.argv);