pullfrog 0.0.197 → 0.0.198

package/dist/mcp/shared.d.ts

@@ -0,0 +1,21 @@
+import type { StandardSchemaV1 } from "@standard-schema/spec";
+import type { FastMCP, Tool } from "fastmcp";
+import type { ToolContext } from "./server.ts";
+export declare const tool: <const params>(toolDef: Tool<any, StandardSchemaV1<params>>) => Tool<any, StandardSchemaV1<params>>;
+export interface ToolResult {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: boolean;
+}
+export declare const handleToolSuccess: (data: Record<string, any> | string) => ToolResult;
+export declare const handleToolError: (error: unknown) => ToolResult;
+/**
+ * Helper to wrap a tool execute function with error handling.
+ * Captures ctx in closure so tools don't need to handle try/catch.
+ * @param fn - the function to execute
+ * @param toolName - optional tool name for error logging
+ */
+export declare const execute: <T, R extends Record<string, any> | string>(fn: (params: T) => Promise<R>, toolName?: string) => (params: T) => Promise<ToolResult>;
+export declare const addTools: (_ctx: ToolContext, server: FastMCP<any>, tools: Tool<any, any>[]) => FastMCP<any>;

package/dist/mcp/shell.d.ts

@@ -0,0 +1,32 @@
+import type { ToolContext } from "./server.ts";
+export declare const ShellParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {}>;
+export type SandboxMethod = "unshare" | "sudo-unshare" | "none";
+/** get the current sandbox method (for testing/diagnostics) */
+export declare function getSandboxMethod(): SandboxMethod;
+export declare function ShellTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}, {
+    command: string;
+    description: string;
+    timeout?: number;
+    working_directory?: string;
+    background?: boolean;
+}>>;
+export declare const KillBackgroundParams: import("arktype/internal/variants/object.ts").ObjectType<{
+    handle: string;
+}, {}>;
+export declare function KillBackgroundTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    handle: string;
+}, {
+    handle: string;
+}>>;

package/dist/mcp/upload.d.ts

@@ -0,0 +1,6 @@
+import type { ToolContext } from "./server.ts";
+export declare function UploadFileTool(ctx: ToolContext): import("fastmcp").Tool<any, import("@standard-schema/spec").StandardSchemaV1<{
+    path: string;
+}, {
+    path: string;
+}>>;

package/dist/models.d.ts

@@ -0,0 +1,69 @@
+/**
+ * model alias registry.
+ *
+ * slugs use the format `provider/model-id` (e.g. "anthropic/claude-opus").
+ * bump `resolve` when a new model generation ships — the alias (slug) stays stable.
+ */
+export interface ModelAlias {
+    /** stable alias stored in DB, e.g. "anthropic/claude-opus" */
+    slug: string;
+    /** provider key (matches providers keys) */
+    provider: string;
+    /** human-readable name shown in dropdowns */
+    displayName: string;
+    /** concrete models.dev specifier, e.g. "anthropic/claude-opus-4-6" */
+    resolve: string;
+    /** full models.dev specifier for the OpenRouter equivalent (undefined for free models) */
+    openRouterResolve: string | undefined;
+    /** top-tier pick for this provider — preferred during auto-select */
+    preferred: boolean;
+    /** whether this alias is free and requires no API key */
+    isFree: boolean;
+    /** slug of a replacement model — presence implies this model is deprecated */
+    fallback: string | undefined;
+}
+interface ModelDef {
+    displayName: string;
+    /** concrete models.dev specifier, e.g. "anthropic/claude-opus-4-6" */
+    resolve: string;
+    /** full models.dev specifier for the OpenRouter equivalent, e.g. "openrouter/anthropic/claude-opus-4.6" */
+    openRouterResolve?: string;
+    preferred?: boolean;
+    envVars?: readonly string[];
+    isFree?: boolean;
+    /** slug of a replacement model — presence implies this model is deprecated */
+    fallback?: string;
+}
+export interface ProviderConfig {
+    displayName: string;
+    envVars: readonly string[];
+    models: Record<string, ModelDef>;
+}
+export declare const providers: {
+    anthropic: ProviderConfig;
+    openai: ProviderConfig;
+    google: ProviderConfig;
+    xai: ProviderConfig;
+    deepseek: ProviderConfig;
+    moonshotai: ProviderConfig;
+    opencode: ProviderConfig;
+    openrouter: ProviderConfig;
+};
+export type ModelProvider = keyof typeof providers;
+export declare function parseModel(slug: string): {
+    provider: string;
+    model: string;
+};
+export declare function getModelProvider(slug: string): string;
+export declare function getProviderDisplayName(slug: string): string | undefined;
+export declare function getModelEnvVars(slug: string): string[];
+export declare const modelAliases: ModelAlias[];
+/** resolve a model slug to its concrete models.dev specifier (e.g. "anthropic/claude-opus-4-6") */
+export declare function resolveModelSlug(slug: string): string | undefined;
+/**
+ * resolve a model slug to the CLI-ready model string, following the fallback
+ * chain when a model is deprecated. returns the first non-deprecated resolve
+ * target, or undefined if the chain is exhausted or broken.
+ */
+export declare function resolveCliModel(slug: string): string | undefined;
+export {};

package/dist/modes.d.ts

@@ -0,0 +1,9 @@
+import { type AgentId } from "./external.ts";
+export interface Mode {
+    name: string;
+    description: string;
+    prompt?: string | undefined;
+}
+export declare const PR_SUMMARY_FORMAT = "### Default format\n\nFollow this structure exactly:\n\n<b>TL;DR</b> \u2014 1-3 sentences on what the PR does and why. Focus on intent, not mechanics.\nNOTE: use HTML bold <b>TL;DR</b>, NOT markdown bold **TL;DR**.\n\n### Key changes\n\n- **Short human-readable title** \u2014 1 sentence per change. Write a short prose phrase (title case or sentence case); when you name a file, type, or function, put that name in backticks (e.g. **Add `TodoTracker` for live checklists**). A reviewer should understand the full PR from this list alone.\n\n<sub><b>Summary</b> \uFF5C {file_count} files \uFF5C {commit_count} commits \uFF5C base: `{base}` \u2190 `{head}`</sub>\nNOTE: the metadata line goes AFTER the bullet list, not before it.\n\nThen for each key change, a ## section with a short descriptive title that reads like a documentation heading (e.g. ## Live todo checklist tracking).\n\n<br/>\n\n## Example readable section title\n\n> **Before:** [old behavior/state]<br/>**After:** [new behavior/state]\nIMPORTANT: Before and After MUST be on a SINGLE blockquote line with an inline <br/> between them. Two separate `>` lines creates a double line break.\n\n1-2 sentences of explanation. Break up text with tables, blockquotes, or lists \u2014 NEVER 3+ plain paragraphs in a row.\n\nIf a change warrants deeper explanation, use a blockquoted details/summary framed as a question:\n> <details><summary>How does X work?</summary>\n> Extended explanation here.\n> </details>\n\nEnd each section with a file links trail (3-4 key files max):\n[`file.ts`](https://github.com/{owner}/{repo}/pull/{number}/files#diff-{sha256hex_of_filepath}) \u00B7 ...\n\nSingle-feature PRs: skip the ## sections. Fold before/after and explanation into the header after key changes.\n\nCRITICAL \u2014 GitHub markdown rendering rule:\nGitHub's markdown parser requires a blank line between ALL block-level elements. This includes transitions between: HTML tags (<br/>, <sub>, <details>, <b>, etc.) and markdown syntax (headings, lists, blockquotes, paragraphs). Without a blank line, GitHub treats the following content as a continuation of the HTML block and renders markdown syntax as literal text. ALWAYS separate block-level elements with a blank line.\n\nRules:\n- `##` titles and key-change bullet lead-ins are plain-language summaries; backtick only actual code tokens (files, types, functions) where they appear in the title\n- ALL variable names, identifiers, and file names in body text must be in backticks\n- ALL file references MUST link to the PR Files Changed view. Compute anchors by running `echo -n 'path/to/file.ts' | sha256sum` via shell for each file. NEVER fabricate hex strings \u2014 run the actual command. If shell is unavailable, omit the #diff- anchor rather than guessing.\n- Add <br/> before each ## heading for visual spacing. Do NOT use horizontal rules (---)\n- Do NOT include raw diff stats like '+123 / -45' or line counts\n- Do NOT include code blocks or repeat diff contents\n- Do NOT include a changelog section \u2014 the key changes list serves this purpose\n- Focus on *intent*, not *what* \u2014 the diff already shows what changed\n- Get the file count and commit count from the checkout_pr metadata, not by counting manually";
+export declare function computeModes(agentId: AgentId): Mode[];
+export declare const modes: Mode[];

package/dist/prep/index.d.ts

@@ -0,0 +1,7 @@
+import type { PrepOptions, PrepResult } from "./types.ts";
+export type { PrepOptions, PrepResult } from "./types.ts";
+/**
+ * run all prep steps sequentially.
+ * failures are logged as warnings but don't stop the run.
+ */
+export declare function runPrepPhase(options: PrepOptions): Promise<PrepResult[]>;

package/dist/prep/installNodeDependencies.d.ts

@@ -0,0 +1,2 @@
+import type { PrepDefinition } from "./types.ts";
+export declare const installNodeDependencies: PrepDefinition;

package/dist/prep/installPythonDependencies.d.ts

@@ -0,0 +1,2 @@
+import type { PrepDefinition } from "./types.ts";
+export declare const installPythonDependencies: PrepDefinition;

package/dist/prep/types.d.ts

@@ -0,0 +1,29 @@
+interface PrepResultBase {
+    dependenciesInstalled: boolean;
+    issues: string[];
+}
+export type NodePackageManager = "npm" | "pnpm" | "yarn" | "bun" | "deno";
+export interface NodePrepResult extends PrepResultBase {
+    language: "node";
+    packageManager: NodePackageManager;
+}
+export type PythonPackageManager = "pip" | "pipenv" | "poetry";
+export interface PythonPrepResult extends PrepResultBase {
+    language: "python";
+    packageManager: PythonPackageManager;
+    configFile: string;
+}
+export interface UnknownLanguagePrepResult extends PrepResultBase {
+    language: "unknown";
+}
+export type PrepResult = NodePrepResult | PythonPrepResult | UnknownLanguagePrepResult;
+export type PrepOptions = {
+    /** when true, lifecycle scripts (postinstall, etc.) are suppressed */
+    ignoreScripts: boolean;
+};
+export interface PrepDefinition {
+    name: string;
+    shouldRun: () => Promise<boolean> | boolean;
+    run: (options: PrepOptions) => Promise<PrepResult>;
+}
+export {};

package/dist/utils/activity.d.ts

@@ -0,0 +1,21 @@
+export declare const DEFAULT_ACTIVITY_TIMEOUT_MS = 300000;
+export declare const DEFAULT_ACTIVITY_CHECK_INTERVAL_MS = 5000;
+type ActivityTimeoutContext = {
+    timeoutMs: number;
+    checkIntervalMs: number;
+};
+export type ActivityTimeout = {
+    promise: Promise<never>;
+    stop: () => void;
+};
+/**
+ * mark activity to reset the no-output timeout.
+ * call this whenever the agent emits any event, even if it isn't logged to stdout.
+ */
+export declare function markActivity(): void;
+/**
+ * get the time since last activity in milliseconds
+ */
+export declare function getIdleMs(): number;
+export declare function createProcessOutputActivityTimeout(ctx: ActivityTimeoutContext): ActivityTimeout;
+export {};

package/dist/utils/agent.d.ts

@@ -0,0 +1,15 @@
+import type { Agent } from "../agents/index.ts";
+/**
+ * resolve the effective model for this run.
+ *
+ * priority:
+ *   1. PULLFROG_MODEL env var (explicit specifier override)
+ *   2. slug from repo config / payload → alias registry
+ *   3. undefined — agent will auto-select
+ */
+export declare function resolveModel(ctx: {
+    slug?: string | undefined;
+}): string | undefined;
+export declare function resolveAgent(ctx: {
+    model?: string | undefined;
+}): Agent;

package/dist/utils/apiFetch.d.ts

@@ -0,0 +1,19 @@
+type ApiFetchOptions = {
+    path: string;
+    method?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    body?: string | undefined;
+    signal?: AbortSignal | undefined;
+};
+/**
+ * fetch wrapper for hitting the Pullfrog API with Vercel deployment protection bypass.
+ *
+ * adds the bypass secret as BOTH a query parameter and a header for maximum reliability.
+ * the server-side forwarding code uses query params, and the Vercel docs say both work,
+ * so we do both as belt-and-suspenders.
+ *
+ * the query param approach is the primary bypass mechanism (matches server-side forwarding).
+ * the header is added as a fallback.
+ */
+export declare function apiFetch(options: ApiFetchOptions): Promise<Response>;
+export {};

package/dist/utils/apiKeys.d.ts

@@ -0,0 +1,10 @@
+/** check if the user has a BYOK key for the given model's provider (does not throw) */
+export declare function hasProviderKey(model: string): boolean;
+export declare function validateAgentApiKey(params: {
+    agent: {
+        name: string;
+    };
+    model: string | undefined;
+    owner: string;
+    name: string;
+}): void;

package/dist/utils/apiUrl.d.ts

@@ -0,0 +1,9 @@
+/**
+ * resolve the Pullfrog API base URL.
+ *
+ * in the action: API_URL is not explicitly set, so this falls back to https://pullfrog.com.
+ * in local dev: API_URL=http://localhost:3000 (from .env).
+ *
+ * enforces https:// for non-local URLs to prevent cleartext credential transmission.
+ */
+export declare function getApiUrl(): string;

package/dist/utils/body.d.ts

@@ -0,0 +1,16 @@
+import type { PayloadEvent } from "../external.ts";
+import type { OctokitWithPlugins } from "./github.ts";
+import type { RunContextData } from "./runContextData.ts";
+interface ResolveBodyContext {
+    event: PayloadEvent;
+    octokit: OctokitWithPlugins;
+    repo: RunContextData["repo"];
+}
+/**
+ * resolves the body of an event by fetching body_html and converting to markdown.
+ * only fetches body_html if the body contains images (to avoid unnecessary API calls).
+ * this ensures agents receive markdown with working signed image URLs instead of
+ * broken user-attachments URLs.
+ */
+export declare function resolveBody(ctx: ResolveBodyContext): Promise<string | null>;
+export {};

package/dist/utils/browser.d.ts

@@ -0,0 +1,21 @@
+import type { ToolState } from "../mcp/server.ts";
+/**
+ * ensure the agent-browser daemon is running by issuing a real command.
+ *
+ * agent-browser is stateful — it manages a persistent browser process via a
+ * daemon that communicates over a Unix socket. we start the daemon here,
+ * outside of ShellTool, because ShellTool's child process lifecycle would
+ * kill it between invocations and the daemon must survive across calls.
+ *
+ * despite ShellTool commands running inside unshare-sandboxed namespaces,
+ * they can still reach this daemon because the Unix socket is discoverable
+ * regardless of unshare's PID/mount isolation. starting the daemon in the
+ * host namespace keeps it alive while sandboxed shells come and go.
+ *
+ * agent-browser auto-starts its daemon on the first CLI invocation and
+ * keeps it alive via the socket for subsequent commands.
+ * we run `open about:blank` as the seed command to trigger this.
+ * idempotent — only runs once.
+ */
+export declare function ensureBrowserDaemon(toolState: ToolState): string | undefined;
+export declare function closeBrowserDaemon(toolState: ToolState): void;

package/dist/utils/buildPullfrogFooter.d.ts

@@ -0,0 +1,30 @@
+export declare const PULLFROG_DIVIDER = "<!-- PULLFROG_DIVIDER_DO_NOT_REMOVE_PLZ -->";
+export interface WorkflowRunFooterInfo {
+    owner: string;
+    repo: string;
+    runId: number;
+    /** optional job ID - if provided, will append /job/{jobId} to the workflow run URL */
+    jobId?: string | undefined;
+}
+export interface BuildPullfrogFooterParams {
+    /** add "Triggered by Pullfrog" link */
+    triggeredBy?: boolean;
+    /** add "View workflow run" link */
+    workflowRun?: WorkflowRunFooterInfo | undefined;
+    /** alternative: just pass a pre-built URL directly (for shortlinks etc.) */
+    workflowRunUrl?: string | undefined;
+    /** arbitrary custom parts (e.g., action links) */
+    customParts?: string[] | undefined;
+    /** model slug from payload (e.g., "anthropic/claude-opus"). shown in footer as "Using `Model Name`" */
+    model?: string | undefined;
+}
+/**
+ * build a pullfrog footer with configurable parts
+ * always includes: frog logo at start and X link at end
+ * order: action links (customParts) > workflow run > model > attribution > reference links
+ */
+export declare function buildPullfrogFooter(params: BuildPullfrogFooterParams): string;
+/**
+ * strip any existing pullfrog footer from a comment body
+ */
+export declare function stripExistingFooter(body: string): string;

package/dist/utils/cli.d.ts

@@ -0,0 +1,10 @@
+/**
+ * CLI utilities
+ */
+export { formatIndentedField, formatJsonValue, formatUsageSummary, log, writeSummary, } from "./log.ts";
+/**
+ * Finds a CLI executable path by checking if it's installed globally
+ * @param name The name of the CLI executable to find
+ * @returns The path to the CLI executable, or null if not found
+ */
+export declare function findCliPath(name: string): string | null;

package/dist/utils/errorReport.d.ts

@@ -0,0 +1,8 @@
+import type { ToolState } from "../mcp/server.ts";
+interface ReportErrorParams {
+    toolState: ToolState;
+    error: string;
+    title?: string;
+}
+export declare function reportErrorToComment(ctx: ReportErrorParams): Promise<void>;
+export {};

package/dist/utils/exitHandler.d.ts

@@ -0,0 +1,8 @@
+type ExitSignalHandler = (signal: "SIGINT" | "SIGTERM") => void | Promise<void>;
+/**
+ * Register a handler to run when the process receives SIGINT or SIGTERM.
+ * Returns a dispose function that removes the handler.
+ */
+export declare function onExitSignal(handler: ExitSignalHandler): () => void;
+export declare function exitWithSignal(signal: "SIGINT" | "SIGTERM"): void;
+export {};

package/dist/utils/fixDoubleEscapedString.d.ts

@@ -0,0 +1 @@
+export declare function fixDoubleEscapedString(str: string): string;

package/dist/utils/gitAuth.d.ts

@@ -0,0 +1,47 @@
+/**
+ * git authentication via GIT_ASKPASS.
+ *
+ * a localhost HTTP server serves tokens via single-use UUID codes.
+ * each $git() call writes a unique askpass script with the server
+ * port+code baked into the file body — no secrets in subprocess env.
+ *
+ * see wiki/askpass.md for full security documentation.
+ */
+import type { GitAuthServer } from "./gitAuthServer.ts";
+type SafeGitSubcommand = "fetch" | "push";
+type GitAuthOptions = {
+    token: string;
+    cwd?: string;
+};
+type GitResult = {
+    stdout: string;
+    stderr: string;
+};
+/**
+ * resolve and fingerprint the git binary. must be called once at startup
+ * (in main()) before any agent code runs, so the path and hash reflect
+ * the untampered binary.
+ *
+ * resolves symlinks via realpath so the hash is of the actual binary.
+ * a malicious agent with sudo could replace the binary later, which is
+ * caught by verifyGitBinary() before each authenticated call.
+ */
+export declare function resolveGit(): void;
+export declare function setGitAuthServer(server: GitAuthServer): void;
+/**
+ * execute authenticated git command via ASKPASS.
+ *
+ * subcommand is restricted to "fetch" | "push" — operations that talk to
+ * a remote and need credentials. working-tree operations (checkout, merge)
+ * use $() from shell.ts which has no token.
+ *
+ * per call: registers a one-time code with the auth server, writes a
+ * unique askpass script with port+code baked in, spawns git with
+ * GIT_ASKPASS pointing to the script, and deletes the script in finally.
+ *
+ * @example
+ * await $git("fetch", ["origin", "main"], { token });
+ * await $git("push", ["-u", "origin", "feature"], { token });
+ */
+export declare function $git(subcommand: SafeGitSubcommand, args: string[], options: GitAuthOptions): Promise<GitResult>;
+export {};

package/dist/utils/gitAuthServer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * ASKPASS-based git authentication server.
+ *
+ * serves tokens via a localhost HTTP server with single-use UUID codes.
+ * each $git() call gets a unique askpass script with the port+code baked in.
+ * the token never appears in subprocess env — only the script file path.
+ *
+ * tamper-evident: if a code is used twice, the second request triggers
+ * immediate token revocation via the GitHub API as a precaution.
+ */
+export type GitAuthServer = {
+    port: number;
+    register: (token: string) => string;
+    writeAskpassScript: (code: string) => string;
+    close: () => Promise<void>;
+    [Symbol.asyncDispose]: () => Promise<void>;
+};
+export declare function startGitAuthServer(tmpdir: string): Promise<GitAuthServer>;

package/dist/utils/github.d.ts

@@ -0,0 +1,78 @@
+import { throttling } from "@octokit/plugin-throttling";
+import { Octokit } from "@octokit/rest";
+export interface InstallationToken {
+    token: string;
+    expires_at: string;
+    installation_id: number;
+    repository: string;
+    ref: string;
+    runner_environment: string;
+    owner?: string;
+}
+type ReadWrite = "read" | "write";
+type WriteOnly = "write";
+/**
+ * GitHub App installation access token permissions.
+ * passed to `POST /app/installations/{id}/access_tokens` to scope the token.
+ * fields and allowed values come from the `app-permissions` OpenAPI schema.
+ * @see https://docs.github.com/en/rest/apps/installations#create-an-installation-access-token-for-an-app
+ * @see https://github.com/github/rest-api-description — components.schemas.app-permissions
+ */
+type GitHubAppPermissions = {
+    actions?: ReadWrite;
+    artifact_metadata?: ReadWrite;
+    attestations?: ReadWrite;
+    checks?: ReadWrite;
+    contents?: ReadWrite;
+    deployments?: ReadWrite;
+    discussions?: ReadWrite;
+    issues?: ReadWrite;
+    packages?: ReadWrite;
+    pages?: ReadWrite;
+    pull_requests?: ReadWrite;
+    security_events?: ReadWrite;
+    statuses?: ReadWrite;
+    workflows?: WriteOnly;
+};
+type AcquireTokenOptions = {
+    repos?: string[];
+    permissions?: GitHubAppPermissions;
+};
+/**
+ * ensure a GitHub token is available in the environment.
+ *
+ * when OIDC is available (CI), always mints a fresh token scoped to
+ * GITHUB_REPOSITORY — overriding any inherited GITHUB_TOKEN that may
+ * be scoped to the wrong repo.
+ *
+ * otherwise falls back to GitHub App credentials for local development.
+ *
+ * only called from play.ts (test/dev path) — the live action calls
+ * main() directly and never calls this.
+ */
+export declare function ensureGitHubToken(): Promise<void>;
+export declare function acquireNewToken(opts?: AcquireTokenOptions): Promise<string>;
+export interface RepoContext {
+    owner: string;
+    name: string;
+}
+/**
+ * Parse repository context from GITHUB_REPOSITORY environment variable.
+ */
+export declare function parseRepoContext(): RepoContext;
+export type OctokitWithPlugins = InstanceType<ReturnType<typeof Octokit.plugin<typeof Octokit, [typeof throttling]>>>;
+export interface ResourceUsage {
+    requestCount: number;
+    rateLimitRemaining: number | null;
+    rateLimitResetMs: number | null;
+}
+export interface UsageSummary {
+    version: 1;
+    github: {
+        core: ResourceUsage;
+        graphql: ResourceUsage;
+    };
+}
+export declare function writeGitHubUsageSummaryToFile(path: string): Promise<void>;
+export declare function createOctokit(token: string): OctokitWithPlugins;
+export {};

package/dist/utils/globals.d.ts

@@ -0,0 +1,3 @@
+export declare const isCloudflareSandbox: boolean;
+export declare const isGitHubActions: boolean;
+export declare const isInsideDocker: boolean;

package/dist/utils/install.d.ts

@@ -0,0 +1,60 @@
+export interface InstallFromNpmTarballParams {
+    packageName: string;
+    version: string;
+    executablePath: string;
+    installDependencies?: boolean;
+}
+export interface InstallFromCurlParams {
+    installUrl: string;
+    executableName: string;
+}
+export interface InstallFromDirectTarballParams {
+    url: string;
+    executablePath: string;
+    stripComponents?: number;
+}
+export interface InstallFromGithubParams {
+    owner: string;
+    repo: string;
+    tag?: string;
+    assetName?: string;
+    executablePath?: string;
+    githubInstallationToken?: string;
+}
+export interface InstallFromGithubTarballParams {
+    owner: string;
+    repo: string;
+    tag?: string;
+    assetNamePattern: string;
+    executablePath: string;
+    githubInstallationToken?: string;
+}
+/**
+ * Install a CLI tool from an npm package tarball
+ * Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export declare function installFromNpmTarball(params: InstallFromNpmTarballParams): Promise<string>;
+/**
+ * Install a CLI tool from GitHub releases
+ * Downloads the latest release asset from GitHub and returns the path to the executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export declare function installFromGithub(params: InstallFromGithubParams): Promise<string>;
+/**
+ * Install a CLI tool from a GitHub release tarball
+ * Downloads the tar.gz from GitHub releases, extracts it, and returns the path to the CLI executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export declare function installFromGithubTarball(params: InstallFromGithubTarballParams): Promise<string>;
+/**
+ * Install a CLI tool from a direct tarball URL.
+ * Downloads the tarball, extracts it to a temp directory, and returns the path to the CLI executable.
+ */
+export declare function installFromDirectTarball(params: InstallFromDirectTarballParams): Promise<string>;
+/**
+ * Install a CLI tool from a curl-based install script
+ * Downloads the install script, runs it with HOME set to temp directory, and returns the path to the CLI executable
+ * The temp directory will be cleaned up by the OS automatically
+ */
+export declare function installFromCurl(params: InstallFromCurlParams): Promise<string>;

package/dist/utils/instructions.d.ts

@@ -0,0 +1,22 @@
+import { type AgentId } from "../external.ts";
+import type { Mode } from "../modes.ts";
+import type { ResolvedPayload } from "./payload.ts";
+import type { RunContextData } from "./runContextData.ts";
+interface InstructionsContext {
+    payload: ResolvedPayload;
+    repo: RunContextData["repo"];
+    modes: Mode[];
+    agentId: AgentId;
+    outputSchema?: Record<string, unknown> | undefined;
+    learnings: string | null;
+}
+export interface ResolvedInstructions {
+    full: string;
+    system: string;
+    user: string;
+    eventInstructions: string;
+    event: string;
+    runtime: string;
+}
+export declare function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions;
+export {};

package/dist/utils/lifecycle.d.ts

@@ -0,0 +1,9 @@
+export interface ExecuteLifecycleHookParams {
+    event: string;
+    script: string | null;
+}
+/**
+ * execute a lifecycle hook script if one is configured.
+ * runs the script in a bash shell with a timeout.
+ */
+export declare function executeLifecycleHook(params: ExecuteLifecycleHookParams): Promise<void>;