@steel-experiments/pi-steel 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Steel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# @steel-dev/pi-steel
+
+Steel browser automation tools for the Pi coding agent.
+
+This package publishes the Steel extension as a reusable Pi package so it can be installed directly into Pi or consumed by other runtimes such as Takopi-based wrappers.
+
+## What it adds
+
+- `steel_navigate`
+- `steel_scrape`
+- `steel_screenshot`
+- `steel_pdf`
+- `steel_click`
+- `steel_computer`
+- `steel_find_elements`
+- `steel_type`
+- `steel_fill_form`
+- `steel_wait`
+- `steel_extract`
+- `steel_scroll`
+- `steel_go_back`
+- `steel_get_url`
+- `steel_get_title`
+- `steel_pin_session`
+- `steel_release_session`
+
+`steel_scrape` defaults to `text`. Ask for `markdown` when headings, lists, and links matter. Ask for `html` only when raw DOM markup is actually needed.
+
+`steel_scroll` can scroll the page or a nested scroll container. For apps like Google Maps, pass a selector for the results pane instead of relying on window scrolling.
+
+## Install
+
+Install into Pi as a package:
+
+```bash
+pi install npm:@steel-dev/pi-steel
+```
+
+Or load it for a single run:
+
+```bash
+pi -e npm:@steel-dev/pi-steel
+```
+
+For local development from this repo:
+
+```bash
+pi -e .
+```
+
+For browser workflows that should continue across multiple prompts in the same Pi session, use:
+
+```bash
+STEEL_SESSION_MODE=session pi -e .
+```
+
+## Requirements
+
+- Node.js 20+
+- A Pi runtime that supports extensions
+- Steel authentication via either:
+  - `STEEL_API_KEY`, or
+  - `steel login` config in `~/.config/steel/config.json`
+- For self-hosted/local Steel, configure a custom base URL
+
+Optional runtime configuration:
+
+- `STEEL_BASE_URL`
+- `STEEL_BROWSER_API_URL`
+- `STEEL_LOCAL_API_URL`
+- `STEEL_API_URL`
+- `STEEL_CONFIG_DIR`
+- `STEEL_SESSION_TIMEOUT_MS`
+- `STEEL_TOOL_TIMEOUT_MS`
+- `STEEL_SOLVE_CAPTCHA`
+- `STEEL_USE_PROXY`
+- `STEEL_PROXY_URL`
+- `STEEL_SESSION_HEADLESS`
+- `STEEL_SESSION_REGION`
+- `STEEL_SESSION_PROFILE_ID`
+- `STEEL_SESSION_PERSIST_PROFILE`
+- `STEEL_SESSION_CREDENTIALS`
+- `STEEL_SESSION_NAMESPACE`
+- `STEEL_SESSION_MODE`
+- `STEEL_CAPTCHA_MAX_RETRIES`
+- `STEEL_CAPTCHA_WAIT_MS`
+- `STEEL_CAPTCHA_POLL_INTERVAL_MS`
+- `STEEL_NAVIGATE_RETRY_COUNT`
+
+`pi-steel` reads Steel CLI config for auth and local API resolution, and it normalizes CLI-style API URLs such as `http://localhost:3000/v1` to the SDK-compatible base URL form.
+
+Session lifecycle modes:
+
+- `STEEL_SESSION_MODE=agent` keeps one Steel session for the whole Pi prompt and closes it after `agent_end`. This is the default.
+- `STEEL_SESSION_MODE=session` keeps the same Steel session alive until Pi switches or shuts down the current session.
+- `STEEL_SESSION_MODE=turn` closes the Steel session after each Pi turn. This is more aggressive and can break workflows that need multiple tool rounds inside one prompt.
+
+You can also change session persistence at runtime:
+
+- `steel_pin_session` keeps the current or next Steel browser session alive across prompts for the rest of the Pi session.
+- `steel_release_session` closes the current Steel browser immediately and resets runtime session handling back to the default mode from `STEEL_SESSION_MODE`.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+Publish preflight:
+
+```bash
+npm pack --dry-run
+```
+
+## Package Layout
+
+This repo is a Pi package. The package manifest in `package.json` exposes the compiled extension entrypoint:
+
+```json
+{
+  "pi": {
+    "extensions": ["./dist/index.js"]
+  }
+}
+```
+
+That lets Pi load the package root directly after `pi install npm:@steel-dev/pi-steel`.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+export default function steelExtension(pi: ExtensionAPI): void;

package/dist/index.js

@@ -0,0 +1,91 @@
+import { resolveSessionMode } from "./session-mode.js";
+import { SteelClient } from "./steel-client.js";
+import { clickTool } from "./tools/click.js";
+import { computerTool } from "./tools/computer.js";
+import { extractTool } from "./tools/extract.js";
+import { findElementsTool } from "./tools/find-elements.js";
+import { fillFormTool } from "./tools/fill-form.js";
+import { getTitleTool, getUrlTool, goBackTool } from "./tools/navigation.js";
+import { navigateTool } from "./tools/navigate.js";
+import { pdfTool } from "./tools/pdf.js";
+import { scrapeTool } from "./tools/scrape.js";
+import { screenshotTool } from "./tools/screenshot.js";
+import { scrollTool } from "./tools/scroll.js";
+import { pinSessionTool, releaseSessionTool } from "./tools/session-control.js";
+import { typeTool } from "./tools/type.js";
+import { waitTool } from "./tools/wait.js";
+export default function steelExtension(pi) {
+    const steelClient = new SteelClient();
+    const defaultSessionMode = resolveSessionMode();
+    let sessionMode = defaultSessionMode;
+    let closingSessions = null;
+    const closeSessions = async (reason) => {
+        if (!closingSessions) {
+            closingSessions = (async () => {
+                try {
+                    await steelClient.closeAllSessions();
+                }
+                catch (error) {
+                    // Cleanup failures should not break the main agent response path.
+                    console.warn(`[steel] session cleanup failed (${reason})`, error);
+                }
+                finally {
+                    closingSessions = null;
+                }
+            })();
+        }
+        await closingSessions;
+    };
+    const sessionController = {
+        getDefaultSessionMode: () => defaultSessionMode,
+        getSessionMode: () => sessionMode,
+        setSessionMode: (mode) => {
+            sessionMode = mode;
+        },
+        closeSessions,
+    };
+    const tools = [
+        navigateTool(steelClient),
+        scrapeTool(steelClient),
+        screenshotTool(steelClient),
+        pdfTool(steelClient),
+        clickTool(steelClient),
+        computerTool(steelClient),
+        findElementsTool(steelClient),
+        typeTool(steelClient),
+        fillFormTool(steelClient),
+        waitTool(steelClient),
+        extractTool(steelClient),
+        scrollTool(steelClient),
+        goBackTool(steelClient),
+        getUrlTool(steelClient),
+        getTitleTool(steelClient),
+        pinSessionTool(steelClient, sessionController),
+        releaseSessionTool(steelClient, sessionController),
+    ];
+    for (const tool of tools) {
+        pi.registerTool(tool);
+    }
+    pi.on("turn_end", async () => {
+        if (sessionMode === "turn") {
+            await closeSessions("turn_end");
+        }
+    });
+    pi.on("agent_end", async () => {
+        if (sessionMode === "agent") {
+            await closeSessions("agent_end");
+        }
+    });
+    // Defensive cleanup for interactive session switches/forks.
+    pi.on("session_before_switch", async () => {
+        await closeSessions("session_before_switch");
+    });
+    pi.on("session_shutdown", async () => {
+        await closeSessions("session_shutdown");
+    });
+    const shutdownApi = pi;
+    shutdownApi.onShutdown?.(async () => {
+        await closeSessions("onShutdown");
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/session-mode.d.ts

@@ -0,0 +1,2 @@
+export type SteelSessionMode = "turn" | "agent" | "session";
+export declare function resolveSessionMode(): SteelSessionMode;

package/dist/session-mode.js

@@ -0,0 +1,12 @@
+export function resolveSessionMode() {
+    const rawValue = process.env.STEEL_SESSION_MODE?.trim().toLowerCase();
+    if (!rawValue) {
+        return "agent";
+    }
+    if (rawValue === "turn" || rawValue === "agent" || rawValue === "session") {
+        return rawValue;
+    }
+    console.warn(`[steel] unsupported STEEL_SESSION_MODE="${rawValue}", falling back to "agent"`);
+    return "agent";
+}
+//# sourceMappingURL=session-mode.js.map

package/dist/session-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-mode.js","sourceRoot":"","sources":["../src/session-mode.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,kBAAkB;IAChC,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACtE,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,OAAO,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC1E,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,OAAO,CAAC,IAAI,CACV,2CAA2C,QAAQ,4BAA4B,CAChF,CAAC;IACF,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/steel-client.d.ts

@@ -0,0 +1,79 @@
+import Steel from "steel-sdk";
+import type { CaptchaSolveResponse, CaptchaStatusResponse } from "steel-sdk/resources/sessions";
+import { type Page } from "playwright-core";
+type SessionCreateOptions = Steel.SessionCreateParams;
+type SessionGotoOptions = Parameters<Page["goto"]>[1];
+type SessionWaitForSelectorOptions = Parameters<Page["waitForSelector"]>[1];
+type SessionClickOptions = Parameters<Page["click"]>[1];
+type SessionTypeOptions = Parameters<Page["type"]>[2];
+type SessionScreenshotOptions = Parameters<Page["screenshot"]>[0];
+type SessionPdfOptions = Parameters<Page["pdf"]>[0];
+type SessionComputerParams = Steel.SessionComputerParams;
+type SessionComputerResponse = Steel.SessionComputerResponse;
+export interface LiveSteelSession {
+    id: string;
+    sessionViewerUrl: string;
+    debugUrl: string;
+    page: Page;
+    goto: (url: string, options?: SessionGotoOptions) => Promise<unknown>;
+    goBack: (options?: Parameters<Page["goBack"]>[0]) => Promise<unknown>;
+    back: (options?: Parameters<Page["goBack"]>[0]) => Promise<unknown>;
+    url: () => string;
+    title: () => Promise<string>;
+    waitForSelector: (selector: string, options?: SessionWaitForSelectorOptions) => Promise<unknown>;
+    click: (selector: string, options?: SessionClickOptions) => Promise<unknown>;
+    fill: (selector: string, text: string) => Promise<unknown>;
+    type: (selector: string, text: string, options?: SessionTypeOptions) => Promise<unknown>;
+    evaluate: <T>(fn: (...args: any[]) => T, ...args: any[]) => Promise<T>;
+    locator: (selector: string) => ReturnType<Page["locator"]>;
+    content: () => Promise<string>;
+    screenshot: (options?: SessionScreenshotOptions) => Promise<unknown>;
+    pdf: (options?: SessionPdfOptions) => Promise<unknown>;
+    computer: (body: SessionComputerParams) => Promise<SessionComputerResponse>;
+    captchasStatus: () => Promise<CaptchaStatusResponse>;
+    captchasSolve: () => Promise<CaptchaSolveResponse>;
+}
+export interface SteelClientOptions {
+    apiKey?: string | null;
+    baseURL?: string;
+    sessionTimeoutMs?: number;
+    sessionCreateOptions?: Partial<SessionCreateOptions>;
+}
+export interface SessionRefreshOptions {
+    useProxy?: boolean;
+    proxyUrl?: string | null;
+}
+export declare function resolveSessionId(session: Record<string, unknown>): string | undefined;
+export declare function resolveSessionConnectURL(session: Record<string, unknown>): string | undefined;
+export declare function buildSessionConnectURL(session: Record<string, unknown>, apiKey?: string | null): string | undefined;
+export declare function resolveSessionViewerURL(session: Record<string, unknown>, viewerBaseURL?: string): string | undefined;
+export declare function sessionDetails(session: {
+    id: string;
+    sessionViewerUrl?: string | null;
+}): {
+    sessionId: string;
+    sessionViewerUrl: string;
+};
+export declare class SteelClient {
+    private static readonly DEFAULT_SESSION_TIMEOUT_MS;
+    private readonly client;
+    private readonly apiKey;
+    private readonly sessionTimeoutMs;
+    private readonly sessionCreateOptions;
+    private readonly viewerBaseURL?;
+    private currentSession;
+    private readonly sessions;
+    private creatingSession;
+    constructor(apiKey?: string, options?: SteelClientOptions);
+    getOrCreateSession(): Promise<LiveSteelSession>;
+    getCurrentSessionId(): string | null;
+    hasActiveSession(): boolean;
+    isProxyConfigured(): boolean;
+    refreshSession(options?: SessionRefreshOptions): Promise<LiveSteelSession>;
+    closeSession(sessionId?: string): Promise<void>;
+    closeAllSessions(): Promise<void>;
+    private resolveSessionCreateOptions;
+    private createSession;
+    private buildLiveSession;
+}
+export {};