@uipath/coder-tool 1.199.0-preview.116

package/src/providers/uipath.spec.ts

@@ -0,0 +1,296 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@uipath/auth", () => ({
+    getLoginStatusAsync: vi.fn(),
+}));
+
+vi.mock("@uipath/common", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("@uipath/common")>();
+    return {
+        ...actual,
+        logger: { debug: vi.fn(), warn: vi.fn(), error: vi.fn() },
+    };
+});
+
+import { getLoginStatusAsync } from "@uipath/auth";
+import { createUiPathProviderExtension, UIPATH_PROVIDER_ID } from "./uipath";
+
+type EventHandler = (event: unknown) => Promise<unknown>;
+
+function buildFakePi() {
+    const handlers = new Map<string, EventHandler>();
+    return {
+        registerProvider: vi.fn(),
+        on: vi.fn((event: string, handler: EventHandler) => {
+            handlers.set(event, handler);
+        }),
+        handlers,
+    };
+}
+
+function loggedInStatus(expiresInMs: number) {
+    return {
+        loginStatus: "Logged in" as const,
+        accessToken: "header.payload.signature",
+        baseUrl: "https://cloud.uipath.com",
+        organizationId: "org-id",
+        organizationName: "myorg",
+        tenantName: "mytenant",
+        expiration: new Date(Date.now() + expiresInMs),
+    };
+}
+
+describe("createUiPathProviderExtension", () => {
+    beforeEach(() => {
+        vi.resetAllMocks();
+        vi.unstubAllGlobals();
+    });
+
+    it("skips registration when not logged in", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue({
+            loginStatus: "Not logged in",
+        });
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        expect(pi.registerProvider).not.toHaveBeenCalled();
+        expect(pi.on).not.toHaveBeenCalled();
+    });
+
+    it("registers discovered models against the agenthub_ gateway route", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                json: () =>
+                    Promise.resolve({
+                        supportedModels: [
+                            {
+                                model: "gpt-4o-2024-11-20",
+                                contextWindow: 128000,
+                            },
+                            "gpt-4o-mini-2024-07-18",
+                        ],
+                    }),
+            }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        expect(pi.registerProvider).toHaveBeenCalledWith(
+            UIPATH_PROVIDER_ID,
+            expect.objectContaining({
+                name: "UiPath LLM Gateway",
+                api: "openai-completions",
+                apiKey: "header.payload.signature",
+                baseUrl:
+                    "https://cloud.uipath.com/org-id/mytenant/agenthub_/llm/openai",
+            }),
+        );
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string; baseUrl: string }>;
+        };
+        expect(config.models).toHaveLength(2);
+        expect(config.models[0]?.baseUrl).toBe(
+            "https://cloud.uipath.com/org-id/mytenant/agenthub_/llm/openai/deployments/gpt-4o-2024-11-20",
+        );
+    });
+
+    it("accepts a bare-array discovery response", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(["gpt-4o-2024-11-20"]),
+            }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string }>;
+        };
+        expect(config.models.map((m) => m.id)).toEqual(["gpt-4o-2024-11-20"]);
+    });
+
+    it("falls back to default models when discovery returns null", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve(null),
+            }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string }>;
+        };
+        expect(config.models.length).toBeGreaterThan(0);
+    });
+
+    it("passes a timeout signal to the discovery request", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        const fetchMock = vi.fn().mockResolvedValue({ ok: false, status: 404 });
+        vi.stubGlobal("fetch", fetchMock);
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const init = fetchMock.mock.calls[0]?.[1] as { signal?: AbortSignal };
+        expect(init.signal).toBeInstanceOf(AbortSignal);
+    });
+
+    it("falls back to default models when discovery fails", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({ ok: false, status: 404 }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string }>;
+        };
+        expect(config.models.length).toBeGreaterThan(0);
+    });
+
+    it("encodes model ids when building deployment routes", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                json: () =>
+                    Promise.resolve({ supportedModels: ["openai/gpt-4o"] }),
+            }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string; baseUrl: string }>;
+        };
+        expect(config.models[0]?.id).toBe("openai/gpt-4o");
+        expect(config.models[0]?.baseUrl).toBe(
+            "https://cloud.uipath.com/org-id/mytenant/agenthub_/llm/openai/deployments/openai%2Fgpt-4o",
+        );
+    });
+
+    it("skips registration when resolving the login status fails", async () => {
+        vi.mocked(getLoginStatusAsync).mockRejectedValue(
+            new Error("auth file unreadable"),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        expect(pi.registerProvider).not.toHaveBeenCalled();
+    });
+
+    it("falls back to default models when discovery returns an unusable shape", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({
+                ok: true,
+                json: () => Promise.resolve({ unexpected: true }),
+            }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            models: Array<{ id: string }>;
+        };
+        expect(config.models.length).toBeGreaterThan(0);
+    });
+
+    it("uses organizationName in the gateway path when organizationId is missing", async () => {
+        const status = loggedInStatus(60 * 60 * 1000);
+        vi.mocked(getLoginStatusAsync).mockResolvedValue({
+            ...status,
+            organizationId: undefined,
+        });
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({ ok: false, status: 404 }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+
+        const config = vi.mocked(pi.registerProvider).mock.calls[0]?.[1] as {
+            baseUrl: string;
+        };
+        expect(config.baseUrl).toBe(
+            "https://cloud.uipath.com/myorg/mytenant/agenthub_/llm/openai",
+        );
+    });
+
+    it("does not re-register on agent_start while the token is fresh", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({ ok: false, status: 404 }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+        expect(pi.registerProvider).toHaveBeenCalledTimes(1);
+
+        await pi.handlers.get("agent_start")?.({ type: "agent_start" });
+
+        expect(pi.registerProvider).toHaveBeenCalledTimes(1);
+        expect(getLoginStatusAsync).toHaveBeenCalledTimes(1);
+    });
+
+    it("re-registers with a fresh token on agent_start when close to expiry", async () => {
+        vi.mocked(getLoginStatusAsync).mockResolvedValue(
+            loggedInStatus(60 * 1000),
+        );
+        vi.stubGlobal(
+            "fetch",
+            vi.fn().mockResolvedValue({ ok: false, status: 404 }),
+        );
+        const pi = buildFakePi();
+
+        await createUiPathProviderExtension().factory(pi as never);
+        expect(pi.registerProvider).toHaveBeenCalledTimes(1);
+
+        const handler = pi.handlers.get("agent_start");
+        expect(handler).toBeDefined();
+        await handler?.({ type: "agent_start" });
+
+        expect(pi.registerProvider).toHaveBeenCalledTimes(2);
+        expect(getLoginStatusAsync).toHaveBeenCalledTimes(2);
+    });
+});

package/src/providers/uipath.ts

@@ -0,0 +1,195 @@
+import type {
+    ExtensionAPI,
+    ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+import { getLoginStatusAsync, type LoginStatus } from "@uipath/auth";
+import { catchError, logger } from "@uipath/common";
+
+export const UIPATH_PROVIDER_ID = "uipath";
+
+const TOKEN_VALIDITY_MINUTES = 30;
+const REFRESH_THRESHOLD_MS = 5 * 60 * 1000;
+const DEFAULT_CONTEXT_WINDOW = 128000;
+const DEFAULT_MAX_TOKENS = 16384;
+// Pi waits for extension factories before startup, so a stalled gateway
+// must not block `uip coder` — cap discovery and fall back to the curated list.
+const MODEL_DISCOVERY_TIMEOUT_MS = 5000;
+
+/** Used when the LLM Gateway model discovery endpoint is unreachable. */
+const FALLBACK_MODEL_IDS = ["gpt-4o-2024-11-20", "gpt-4o-mini-2024-07-18"];
+
+interface DiscoveredModel {
+    id: string;
+    contextWindow?: number;
+    maxTokens?: number;
+}
+
+interface ReadyLoginStatus {
+    accessToken: string;
+    gatewayBase: string;
+    expiration?: Date;
+}
+
+const asReadyStatus = (status: LoginStatus): ReadyLoginStatus | undefined => {
+    // Same org/tenant path segments as @uipath/agenthub-sdk's client factory.
+    const organization = status.organizationId ?? status.organizationName;
+    const tenant = status.tenantName ?? status.tenantId;
+    if (
+        status.loginStatus !== "Logged in" ||
+        !status.accessToken ||
+        !status.baseUrl ||
+        !organization ||
+        !tenant
+    ) {
+        return undefined;
+    }
+    return {
+        accessToken: status.accessToken,
+        gatewayBase: `${status.baseUrl}/${organization}/${tenant}/agenthub_/llm`,
+        expiration: status.expiration,
+    };
+};
+
+/**
+ * Model discovery via the gateway-normalized endpoint. The response shape is
+ * tolerated loosely (array of ids or objects) since the contract is evolving.
+ */
+const discoverModels = async (
+    ready: ReadyLoginStatus,
+): Promise<DiscoveredModel[] | undefined> => {
+    const [error, response] = await catchError(
+        fetch(`${ready.gatewayBase}/api/chat/completions`, {
+            headers: { Authorization: `Bearer ${ready.accessToken}` },
+            signal: AbortSignal.timeout(MODEL_DISCOVERY_TIMEOUT_MS),
+        }),
+    );
+    if (error || !response.ok) {
+        logger.debug(
+            `[coder-tool] LLM Gateway model discovery failed: ${error?.message ?? response?.status}`,
+        );
+        return undefined;
+    }
+    const [parseError, parsed] = await catchError(
+        response.json() as Promise<unknown>,
+    );
+    if (parseError) {
+        return undefined;
+    }
+    const body =
+        parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? (parsed as Record<string, unknown>)
+            : undefined;
+    const rawModels = Array.isArray(parsed)
+        ? parsed
+        : (body?.supportedModels ?? body?.models ?? body?.data);
+    if (!Array.isArray(rawModels)) {
+        return undefined;
+    }
+    const models = rawModels
+        .map((entry: unknown): DiscoveredModel | undefined => {
+            if (typeof entry === "string") {
+                return { id: entry };
+            }
+            if (entry && typeof entry === "object") {
+                const record = entry as Record<string, unknown>;
+                const id = record.model ?? record.name ?? record.id;
+                if (typeof id === "string" && id.length > 0) {
+                    return {
+                        id,
+                        contextWindow:
+                            typeof record.contextWindow === "number"
+                                ? record.contextWindow
+                                : undefined,
+                        maxTokens:
+                            typeof record.maxTokens === "number"
+                                ? record.maxTokens
+                                : undefined,
+                    };
+                }
+            }
+            return undefined;
+        })
+        .filter((model): model is DiscoveredModel => model !== undefined);
+    return models.length > 0 ? models : undefined;
+};
+
+const toProviderModels = (
+    ready: ReadyLoginStatus,
+    models: DiscoveredModel[],
+): ProviderModelConfig[] =>
+    models.map((model) => ({
+        id: model.id,
+        name: `${model.id} (UiPath)`,
+        // Azure-style route: the OpenAI client appends /chat/completions.
+        // The id is encoded so provider-qualified ids (e.g. "openai/gpt-4o")
+        // stay a single path segment.
+        baseUrl: `${ready.gatewayBase}/openai/deployments/${encodeURIComponent(model.id)}`,
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: model.contextWindow ?? DEFAULT_CONTEXT_WINDOW,
+        maxTokens: model.maxTokens ?? DEFAULT_MAX_TOKENS,
+    }));
+
+/**
+ * Registers the "uipath" provider backed by the LLM Gateway front door
+ * (agenthub_). Skipped silently when no `uip login` session exists so the
+ * other providers keep working.
+ */
+export const createUiPathProviderExtension = () => {
+    let cachedModels: DiscoveredModel[] | undefined;
+    let tokenExpiration: Date | undefined;
+
+    const register = async (pi: ExtensionAPI): Promise<boolean> => {
+        const [error, status] = await catchError(
+            getLoginStatusAsync({
+                ensureTokenValidityMinutes: TOKEN_VALIDITY_MINUTES,
+            }),
+        );
+        if (error) {
+            logger.debug(
+                `[coder-tool] Could not resolve UiPath login: ${error.message}`,
+            );
+            return false;
+        }
+        const ready = asReadyStatus(status);
+        if (!ready) {
+            logger.debug(
+                "[coder-tool] Not logged in to UiPath — 'uipath' provider not registered. Run 'uip login' to enable it.",
+            );
+            return false;
+        }
+        tokenExpiration = ready.expiration;
+        cachedModels ??= await discoverModels(ready);
+        const models = cachedModels ?? FALLBACK_MODEL_IDS.map((id) => ({ id }));
+        pi.registerProvider(UIPATH_PROVIDER_ID, {
+            name: "UiPath LLM Gateway",
+            baseUrl: `${ready.gatewayBase}/openai`,
+            apiKey: ready.accessToken,
+            api: "openai-completions",
+            models: toProviderModels(ready, models),
+        });
+        return true;
+    };
+
+    return {
+        name: "uipath-llm-gateway",
+        factory: async (pi: ExtensionAPI): Promise<void> => {
+            const registered = await register(pi);
+            if (!registered) {
+                return;
+            }
+            // UiPath access tokens are short-lived; re-register with a fresh
+            // token when the current one is close to expiry.
+            pi.on("agent_start", async () => {
+                const expiresSoon =
+                    tokenExpiration === undefined ||
+                    tokenExpiration.getTime() - Date.now() <
+                        REFRESH_THRESHOLD_MS;
+                if (expiresSoon) {
+                    await register(pi);
+                }
+            });
+        },
+    };
+};

package/src/tool.spec.ts

@@ -0,0 +1,38 @@
+import { setPreviewBuild } from "@uipath/common";
+import { Command } from "commander";
+import { afterEach, describe, expect, it } from "vitest";
+import { metadata, registerCommands } from "./tool";
+
+describe("coder-tool", () => {
+    afterEach(() => {
+        setPreviewBuild(false);
+    });
+
+    it("exposes the expected metadata", () => {
+        expect(metadata.name).toBe("coder-tool");
+        expect(metadata.commandPrefix).toBe("coder");
+        expect(metadata.version).toMatch(/^\d+\.\d+\.\d+/);
+    });
+
+    it("registers a passthrough action on preview builds", async () => {
+        setPreviewBuild(true);
+        const program = new Command();
+        program.name("coder").exitOverride();
+        await registerCommands(program);
+
+        // The action lives on the tool command itself so `uip coder [args...]`
+        // forwards everything to Pi.
+        const usage = program.usage();
+        expect(usage).toContain("[args...]");
+    });
+
+    it("registers nothing on stable builds", async () => {
+        setPreviewBuild(false);
+        const program = new Command();
+        program.name("coder").exitOverride();
+        await registerCommands(program);
+
+        expect(program.usage()).not.toContain("[args...]");
+        expect(program.registeredArguments).toHaveLength(0);
+    });
+});

package/src/tool.ts

@@ -0,0 +1,20 @@
+import { previewOnly } from "@uipath/common";
+import type { Command } from "commander";
+import pkg from "../package.json" with { type: "json" };
+import { registerChatCommand } from "./commands/chat";
+
+export const metadata = {
+    name: "coder-tool",
+    version: pkg.version,
+    description:
+        "Build UiPath automations with an AI agent (Pi) that drives uip — via UiPath LLM Gateway or your own model keys.",
+    commandPrefix: "coder",
+};
+
+export const registerCommands = async (program: Command): Promise<void> => {
+    // Preview builds only until the tool-permission posture for an
+    // autonomous agent in customer environments is settled (PR #3011
+    // review): Pi executes tool calls without per-call approval, so the
+    // command stays off stable builds for now.
+    previewOnly(() => registerChatCommand(program));
+};

package/templates/uipath-cli.md

@@ -0,0 +1,38 @@
+# UiPath CLI (`uip`) — agent guidance
+
+You are running inside `uip coder`, the UiPath automation-building agent of the UiPath CLI. Your purpose is helping users build, ship, and operate **UiPath automations** — agent projects, processes, Orchestrator resources, platform data — not general-purpose software development. When a request is unrelated to UiPath work, help briefly but steer toward the automation task at hand.
+
+The `uip` command line tool is available in this environment and is your primary way to work with the UiPath platform: build and run automations, manage agents and processes, and query platform resources. Prefer `uip` over raw REST calls — it handles auth, tenant routing, and pagination for you.
+
+## Ground rules
+
+- Discover before guessing: `uip --help` lists tools; `uip <tool> --help` and `uip <tool> <command> --help` list commands and options. Command surfaces evolve — trust `--help` over memory.
+- Every command prints a JSON envelope: `{"Result": "Success", "Code": ..., "Data": ...}` on success (exit 0) or `{"Result": "Failure" | "AuthenticationError" | "ValidationError" | ..., "Message": ..., "Instructions": ...}` on error (exit 1-4). Parse `Data` for results; `Instructions` tells you how to recover.
+- Check auth first when platform calls fail: `uip login status`. If expired or missing, ask the user to run `uip login` — never handle credentials yourself.
+- Commands run against the logged-in org/tenant. `uip login status` shows which one.
+- Be careful with destructive commands (delete, undeploy, job stop). Confirm with the user before running them against shared tenants.
+
+## Common tools (run `uip <tool> --help` for the full surface)
+
+| Tool | Purpose |
+| --- | --- |
+| `uip agent` | UiPath Agents: init, pack, publish, deploy, run, evaluate agent projects |
+| `uip maestro` | Maestro process orchestration: BPMN, flows, deployments, instances |
+| `uip or` | Orchestrator: folders, assets, queues, processes, jobs, buckets |
+| `uip df` | Data Fabric: entities, records, queries, CSV import |
+| `uip is` | Integration Service: connections, connectors, triggers |
+| `uip context-grounding` | Context Grounding (ECS) indexes and semantic search |
+| `uip solution` | Solution packages: init, publish, resync |
+| `uip tm` | Test Manager: projects, test cases, requirements |
+| `uip tasks` | Action Center tasks |
+| `uip platform` | Cross-platform resources (orgs, tenants, services) |
+
+Not every tool is installed by default — a missing tool auto-installs on first use, or run `uip tools install <name>`.
+
+## Typical automation workflows
+
+- Build and ship an agent: `uip agent init` → edit → `uip agent pack` → `uip agent publish` → `uip agent deploy` → `uip agent run`.
+- Operate Orchestrator: `uip or jobs list --status Failed`, `uip or assets list`, `uip or queues items list`.
+- Work with data: `uip df entities list`, `uip df records query <entity> --filter ...`, `uip df records import <entity> --file data.csv`.
+
+When a task involves UiPath resources, reach for the matching `uip` tool before writing custom scripts.

package/tests/coding-agent.e2e.test.ts

@@ -0,0 +1,17 @@
+// E2E coverage for scenarios/coder-tool/coding-agent.md.
+//
+// All scenarios need either a live LLM Gateway session (S3/S4), a BYO
+// provider key (S5), or a packed-CLI harness run with network access
+// (S1/S2/S6) — none of which the offline CI e2e lane provides today.
+// They were verified manually against alpha (see the PR description);
+// the placeholders below keep the mandatory scenario ↔ e2e mapping.
+import { describe, it } from "vitest";
+
+describe("coding-agent", () => {
+    it.skip("S1: forwards arguments to the pi coding agent", () => {});
+    it.skip("S2: lists models without a uipath provider when logged out", () => {});
+    it.skip("S3: registers the uipath provider when logged in", () => {});
+    it.skip("S4: completes a print-mode prompt through the uipath provider", () => {});
+    it.skip("S5: completes a print-mode prompt through a BYO provider", () => {});
+    it.skip("S6: reports a failure envelope when pi cannot start", () => {});
+});

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../../tsconfig.base.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "types": ["node"]
+    },
+    "include": ["src/**/*", "vitest*.ts"],
+    "exclude": ["node_modules", "dist"]
+}

package/vitest.config.ts

@@ -0,0 +1 @@
+export { default } from "../../vitest.base.config";