pullfrog 0.1.30 → 0.1.32

package/dist/utils/modelAccess.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Model-access gate for explicitly-requested per-run models (`--opus`,
+ * `--model=<slug>`). An explicit model the run can't serve hard-fails *before*
+ * the agent starts with one consistent, reason-tailored error.
+ *
+ * The provenance split lives upstream: `payload.modelExplicit` is true only for
+ * a flag in the triggerer's own @pullfrog prompt. A standing default (repo
+ * setting, a model flag in org/repo `baseInstructions`, or a trigger's fallback
+ * instructions) keeps `modelExplicit = false` and never reaches the error
+ * branches here — a missing key for a standing default surfaces through
+ * `validateAgentApiKey`'s missing-key error instead (#938).
+ *
+ * `decideModelAccess` is pure (no env / IO) so the branching is unit-testable;
+ * `buildModelAccessError` renders the user-facing markdown that `main.ts`
+ * throws and `runErrorRenderer.ts` re-surfaces on both run surfaces.
+ */
+export type ModelAccessReason = "oss" | "byok_no_key" | "router";
+export type ModelAccessDecision = {
+    kind: "ok";
+}
+/** route through the Router/OSS proxy, re-targeted to the requested model. */
+ | {
+    kind: "proxy";
+    target: string;
+}
+/** run BYOK with the requested model — clear the minted proxy target. */
+ | {
+    kind: "byok";
+} | {
+    kind: "error";
+    reason: ModelAccessReason;
+};
+/**
+ * decide whether an (already-resolved) requested model can run, and how.
+ *
+ * - non-explicit / no model → `ok` (caller's missing-key validation applies).
+ * - proxy active + OSS → only the funded subsidy target routes; a different
+ *   model needs the repo's own key (`byok`) else `error("oss")`.
+ * - proxy active + Router → honor any Router-servable model (`proxy`); fall to
+ *   BYOK when locally authorized, else `error("router")`.
+ * - no proxy → the resolved model must be locally authorized, else
+ *   `error("byok_no_key")`.
+ */
+export declare function decideModelAccess(input: {
+    modelExplicit: boolean;
+    model: string | undefined;
+    oss: boolean;
+    proxyActive: boolean;
+    subsidyTarget: string | undefined;
+    resolvedModel: string | undefined;
+    authorized: Set<string>;
+}): ModelAccessDecision;
+/** marker on the throw message so `runErrorRenderer` can reclassify it. */
+export declare const MODEL_ACCESS_MARKER = "requested model is not available";
+/**
+ * render the model-access failure body (used for both the thrown error and the
+ * PR comment / job summary). one shape, reason-branched why → CTA.
+ */
+export declare function buildModelAccessError(input: {
+    reason: ModelAccessReason;
+    model: string;
+    owner: string;
+    name: string;
+}): string;

package/dist/utils/payload.d.ts

@@ -5,10 +5,18 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     version: string;
     prompt: string;
     model?: string | undefined;
+    modelExplicit?: boolean | undefined;
     triggerer?: string | undefined;
+    baseInstructions?: string | undefined;
     eventInstructions?: string;
     previousRunsNote?: string;
     event?: object;
+    xrepo?: {
+        mode: "all" | "explicit";
+        read: string[];
+        write: string[];
+        unavailable?: string[];
+    } | undefined;
     timeout?: string | undefined;
     progressComment?: {
         id: string;
@@ -17,26 +25,42 @@ export declare const JsonPayload: import("arktype/internal/variants/object.ts").
     generateSummary?: boolean | undefined;
 }, {}>;
 export declare const Inputs: import("arktype/internal/variants/object.ts").ObjectType<{
-    prompt: string;
+    prompt?: string | undefined;
+    prompt_file?: string | undefined;
     model?: string | undefined;
     timeout?: string | undefined;
     push?: "disabled" | "enabled" | "restricted" | undefined;
     shell?: "disabled" | "enabled" | "restricted" | undefined;
+    status_checks?: "disabled" | "enabled" | undefined;
     cwd?: string | undefined;
     output_schema?: string | undefined;
 }, {}>;
 export type Inputs = typeof Inputs.infer;
 export type ResolvedPromptInput = string | typeof JsonPayload.infer;
 export declare function resolvePromptInput(): ResolvedPromptInput;
+/**
+ * true when `actor` is Pullfrog's own GitHub identity — the bot login
+ * (`pullfrog[bot]` / `pullfrogdev[bot]`) or the bare account. used to skip
+ * self-triggered events and to recognize Pullfrog-originated review threads.
+ */
+export declare const isPullfrog: (actor: string | null | undefined) => boolean;
 export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput, repoSettings: RepoSettings): {
     "~pullfrog": true;
     version: string;
     model: string | undefined;
+    modelExplicit: boolean;
     prompt: string;
     triggerer: string | undefined;
+    baseInstructions: string | undefined;
     eventInstructions: string | undefined;
     previousRunsNote: string | undefined;
     event: PayloadEvent;
+    xrepo: {
+        mode: "all" | "explicit";
+        read: string[];
+        write: string[];
+        unavailable?: string[];
+    } | undefined;
     timeout: string | undefined;
     cwd: string | undefined;
     progressComment: {
@@ -46,6 +70,7 @@ export declare function resolvePayload(resolvedPromptInput: ResolvedPromptInput,
     generateSummary: boolean | undefined;
     push: import("../external.ts").PushPermission;
     shell: import("../external.ts").ShellPermission;
+    statusChecks: boolean;
     proxyModel: string | undefined;
 };
 export type ResolvedPayload = ReturnType<typeof resolvePayload>;

package/dist/utils/runContext.d.ts

@@ -36,6 +36,9 @@ export interface RepoSettings {
     learnings: string | null;
     learningsHeadings: LearningsHeading[];
     envAllowlist: string | null;
+    xrepoBrief: string | null;
+    xrepoLearnings: string | null;
+    xrepoLearningsHeadings: LearningsHeading[];
 }
 /**
  * Account-level billing plan. Orthogonal to repo-level OSS status. Mirrors

package/dist/utils/runContextData.d.ts

@@ -18,6 +18,16 @@ interface ResolveRunContextDataParams {
     octokit: OctokitWithPlugins;
     token: string;
 }
+/**
+ * true when the action is pinned to a full commit SHA (vs the moving `@v0`
+ * tag or a branch). GitHub runs the action's `post:` hook (and reads
+ * `action.yml`) straight from the checked-out action ref, so a SHA pin freezes
+ * that checkout forever: the main agent still floats to the latest `^semver`
+ * via the npm bootstrap (this code is proof — it ran), but the post-run
+ * cleanup step keeps executing the pinned commit's source and never receives
+ * fixes. surfaced in the log and PR footers to nudge repos back to `@v0`.
+ */
+export declare function isActionPinnedToSha(): boolean;
 /**
  * initialize run context data: parse context, fetch repo info and settings
  */

package/dist/utils/setup.d.ts

@@ -1,5 +1,5 @@
 import type { ShellPermission } from "../external.ts";
-import type { ToolState } from "../toolState.ts";
+import { type ToolState } from "../toolState.ts";
 import type { OctokitWithPlugins } from "./github.ts";
 export interface SetupOptions {
     tempDir: string;
@@ -61,15 +61,30 @@ export interface GitContext {
     postCheckoutScript: string | null;
 }
 export type SetupGitParams = GitContext;
+/** GitContext plus an explicit working-tree directory (primary cwd or a
+ * secondary clone under ctx.tmpdir/xrepo/<name>). */
+export interface ConfigureRepoGitParams extends GitContext {
+    dir: string;
+}
 /**
- * setup git configuration and authentication for the repository.
+ * setup git configuration + authentication for the PRIMARY repo working tree
+ * (process.cwd()). thin wrapper over configureRepoGit. preserves the existing
+ * single-repo call shape in main.ts.
+ */
+export declare function setupGit(params: SetupGitParams): Promise<void>;
+/**
+ * setup git configuration and authentication for a repository working tree at
+ * `params.dir`. used for the primary repo (dir = cwd) and for secondary repos
+ * cloned on demand by checkout_repo (dir = ctx.tmpdir/xrepo/<name>).
  * - configures git identity (user.email, user.name)
  * - sets up authentication via gitToken (minimal contents:write)
+ * - records pushUrl + initialHead onto the repo's RepoToolState (must already
+ *   be registered in toolState.repos)
  *
  * gitToken is a minimal-permission token (contents + workflows) used for git operations.
  * it is assumed to be potentially exfiltratable, so it has limited scope.
  */
-export declare function setupGit(params: SetupGitParams): Promise<void>;
+export declare function configureRepoGit(params: ConfigureRepoGitParams): Promise<void>;
 /**
  * snapshot the current HEAD as either a branch name (when on a named branch)
  * or a literal SHA (when detached). used by setupGit to pin the run-entry

package/dist/utils/statusChecks.d.ts

@@ -0,0 +1,25 @@
+import type { ToolContext } from "../mcp/server.ts";
+/**
+ * post the opt-in `pullfrog` (run completion) and `pullfrog-approval` (review
+ * verdict) commit-status check-runs so they can be required by branch
+ * protection. no-op unless the `status_checks` input is enabled and the run is
+ * on a pull request.
+ *
+ * terminal-only by design: we never create an `in_progress` check. a
+ * hard-cancelled run (SIGKILL) would strand a required check `in_progress` and
+ * block merges forever; an absent required check already blocks merge the same
+ * way while the run is in flight, with no stuck-check failure mode.
+ *
+ *   - `pullfrog` is posted on every PR run: success iff the run finished
+ *     successfully, failure on error/timeout. review-verdict-agnostic.
+ *   - `pullfrog-approval` is posted only when this run produced an approval
+ *     verdict (`toolState.approval`, set by create_pull_request_review),
+ *     anchored to the reviewed sha so a mid-run push leaves the new head
+ *     unapproved until the follow-up re-review reports.
+ *
+ * best-effort throughout: a check-post failure (fork PR head not in the base
+ * repo, transient 5xx, closed PR) must never flip the run's own outcome.
+ */
+export declare function reportStatusChecks(ctx: ToolContext, params: {
+    runSucceeded: boolean;
+}): Promise<void>;

package/dist/utils/token.d.ts

@@ -1,4 +1,4 @@
-import type { PushPermission } from "../external.ts";
+import type { PushPermission, XrepoConfig } from "../external.ts";
 import { acquireNewToken, type OidcCredentials } from "./github.ts";
 export { acquireNewToken as acquireInstallationToken };
 export { revokeGitHubInstallationToken as revokeInstallationToken };
@@ -20,10 +20,13 @@ export declare function getJobToken(): string;
 export type TokenRef = {
     gitToken: string;
     mcpToken: string;
+    readToken?: string | undefined;
+    refreshGitToken?: ((stale: string) => Promise<string>) | undefined;
     [Symbol.asyncDispose]: () => Promise<void>;
 };
 type ResolveTokensParams = {
     push: PushPermission;
+    xrepo?: XrepoConfig | undefined;
     /**
      * OIDC credentials stashed by main.ts before the restricted-mode env wipe —
      * the mid-run MCP token refresh mints from this snapshot (#891). null when
@@ -34,11 +37,16 @@ type ResolveTokensParams = {
 /**
  * resolve tokens for the action run.
  *
- * creates two separate tokens:
+ * creates two separate tokens (three on cross-repo runs):
  * - gitToken: contents permission based on `push` setting (assumed exfiltratable)
  *   - push: enabled → contents:write (can push)
  *   - push: disabled → contents:read (read-only)
  * - mcpToken: full installation token - used for GitHub API calls in MCP tools (not exfiltratable)
+ * - readToken (xrepo only): contents:read over the read set, for cloning read-tier secondaries
+ *
+ * on cross-repo runs, gitToken + mcpToken are scoped to the WRITE set (always
+ * incl. the primary), so a writable secondary can take PRs; read-only
+ * secondaries route through readToken instead.
  *
  * security-conscious users can pass their own token via GH_TOKEN env var or inputs.token.
  */

package/dist/yes/index.d.ts

@@ -0,0 +1,58 @@
+import type { StandardSchemaV1 } from "./standard-schema.ts";
+export type { StandardSchemaV1 } from "./standard-schema.ts";
+export declare function range(n: number): number[];
+export declare function range(start: number, end: number): number[];
+export declare function range(n: number, fn: (i: number) => number): number[];
+export declare function schedule(fn: (i: number) => number, count: number): number[];
+/**
+ * read a retry delay (ms) from a thrown HTTP error's response headers, honoring
+ * GitHub's rate-limit backoff hints on octokit errors (`error.response.headers`):
+ *   - `retry-after` (RFC 9110 delta-seconds or an HTTP-date) — an explicit
+ *     backoff directive whenever present (covers secondary rate limits, which
+ *     carry it with `x-ratelimit-remaining > 0`).
+ *   - else `x-ratelimit-reset` (epoch seconds) but ONLY when
+ *     `x-ratelimit-remaining` is `"0"` — GitHub sends the reset header on ~every
+ *     response (~1h ahead), so it's a backoff hint only under actual primary
+ *     rate-limit exhaustion (matching octokit's throttling plugin). without this
+ *     gate a non-rate-limit retried error (e.g. a permissions 403) would be
+ *     wrongly delayed to the reset time.
+ * returns `undefined` when no applicable hint is present/parseable.
+ */
+export declare function retryAfterMs(error: unknown): number | undefined;
+type InferInput<S> = S extends StandardSchemaV1<infer I, any> ? I : never;
+type InferOutput<S> = S extends StandardSchemaV1<any, infer O> ? O : never;
+export interface OpOptions<TReturn = any> {
+    name?: string;
+    ttl?: number;
+    maxItems?: number;
+    retries?: number[];
+    /**
+     * honor a server backoff hint on retries: when a retried error carries a
+     * `retry-after` / `x-ratelimit-reset` header, schedule the next retry from
+     * that value (clamped to `[fixed delay, retryAfterCap]`) instead of the fixed
+     * `retries[attempt]` backoff. `true` uses the built-in `retryAfterMs` reader;
+     * a function extracts a delay-ms from a custom error shape. errors without the
+     * header fall back to the fixed backoff.
+     */
+    retryAfter?: boolean | ((error: unknown) => number | undefined);
+    /** cap (ms) on a honored retry-after hint. default 20000. */
+    retryAfterCap?: number;
+    cacheHit?: ((key: string) => void) | null;
+    cacheMiss?: ((key: string) => void) | null;
+    skipCache?: (result: TReturn) => boolean;
+    bail?: (error: unknown) => boolean;
+}
+export interface OpObjectOptions<TInputSchema extends StandardSchemaV1 | undefined = undefined, TOutputSchema extends StandardSchemaV1 | undefined = undefined, TRun extends (input: TInputSchema extends StandardSchemaV1 ? InferOutput<TInputSchema> : any, ctx?: any) => Promise<TOutputSchema extends StandardSchemaV1 ? InferInput<TOutputSchema> : any> = (input: TInputSchema extends StandardSchemaV1 ? InferOutput<TInputSchema> : any, ctx?: any) => Promise<TOutputSchema extends StandardSchemaV1 ? InferInput<TOutputSchema> : any>> extends OpOptions<TOutputSchema extends StandardSchemaV1 ? InferOutput<TOutputSchema> : Awaited<ReturnType<TRun>>> {
+    input?: TInputSchema;
+    output?: TOutputSchema;
+    run: TRun;
+}
+type AnyAsyncFn = (...args: any[]) => Promise<any>;
+type Input<F extends AnyAsyncFn> = Parameters<F>[0];
+export type OpFunction<F extends AnyAsyncFn> = F & {
+    clear: (key?: Input<F>) => void;
+    has: (key: Input<F>) => boolean;
+    invalidate: (predicate: (key: Input<F>) => boolean) => number;
+};
+export declare function op<F extends AnyAsyncFn>(fn: F, options?: OpOptions<Awaited<ReturnType<F>>>): OpFunction<F>;
+export declare function op<TInputSchema extends StandardSchemaV1 | undefined = undefined, TOutputSchema extends StandardSchemaV1 | undefined = undefined, TRun extends (input: TInputSchema extends StandardSchemaV1 ? InferOutput<TInputSchema> : any, ctx?: any) => Promise<TOutputSchema extends StandardSchemaV1 ? InferInput<TOutputSchema> : any> = (input: TInputSchema extends StandardSchemaV1 ? InferOutput<TInputSchema> : any, ctx?: any) => Promise<TOutputSchema extends StandardSchemaV1 ? InferInput<TOutputSchema> : any>>(options: OpObjectOptions<TInputSchema, TOutputSchema, TRun>): OpFunction<(input: TInputSchema extends StandardSchemaV1 ? InferInput<TInputSchema> : Parameters<TRun>[0], ctx?: TRun extends (input: any, ctx: infer C, ...rest: any[]) => any ? C : never) => Promise<TOutputSchema extends StandardSchemaV1 ? InferOutput<TOutputSchema> : Awaited<ReturnType<TRun>>>>;

package/dist/yes/standard-schema.d.ts

@@ -0,0 +1,117 @@
+/** The Standard Typed interface. This is a base type extended by other specs. */
+export interface StandardTypedV1<Input = unknown, Output = Input> {
+    /** The Standard properties. */
+    readonly "~standard": StandardTypedV1.Props<Input, Output>;
+}
+export declare namespace StandardTypedV1 {
+    /** The Standard Typed properties interface. */
+    interface Props<Input = unknown, Output = Input> {
+        /** The version number of the standard. */
+        readonly version: 1;
+        /** The vendor name of the schema library. */
+        readonly vendor: string;
+        /** Inferred types associated with the schema. */
+        readonly types?: Types<Input, Output> | undefined;
+    }
+    /** The Standard Typed types interface. */
+    interface Types<Input = unknown, Output = Input> {
+        /** The input type of the schema. */
+        readonly input: Input;
+        /** The output type of the schema. */
+        readonly output: Output;
+    }
+    /** Infers the input type of a Standard Typed. */
+    type InferInput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["input"];
+    /** Infers the output type of a Standard Typed. */
+    type InferOutput<Schema extends StandardTypedV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+/** The Standard Schema interface. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard Schema properties. */
+    readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardSchemaV1 {
+    /** The Standard Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+        /** Validates unknown input values. */
+        readonly validate: (value: unknown, options?: StandardSchemaV1.Options | undefined) => Result<Output> | Promise<Result<Output>>;
+    }
+    /** The result interface of the validate function. */
+    type Result<Output> = SuccessResult<Output> | FailureResult;
+    /** The result interface if validation succeeds. */
+    interface SuccessResult<Output> {
+        /** The typed output value. */
+        readonly value: Output;
+        /** A falsy value for `issues` indicates success. */
+        readonly issues?: undefined;
+    }
+    interface Options {
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The result interface if validation fails. */
+    interface FailureResult {
+        /** The issues of failed validation. */
+        readonly issues: ReadonlyArray<Issue>;
+    }
+    /** The issue interface of the failure output. */
+    interface Issue {
+        /** The error message of the issue. */
+        readonly message: string;
+        /** The path of the issue, if any. */
+        readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+    }
+    /** The path segment interface of the issue. */
+    interface PathSegment {
+        /** The key representing a path segment. */
+        readonly key: PropertyKey;
+    }
+    /** The Standard types interface. */
+    interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {
+    }
+    /** Infers the input type of a Standard. */
+    type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+    /** Infers the output type of a Standard. */
+    type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}
+/** The Standard JSON Schema interface. */
+export interface StandardJSONSchemaV1<Input = unknown, Output = Input> {
+    /** The Standard JSON Schema properties. */
+    readonly "~standard": StandardJSONSchemaV1.Props<Input, Output>;
+}
+export declare namespace StandardJSONSchemaV1 {
+    /** The Standard JSON Schema properties interface. */
+    interface Props<Input = unknown, Output = Input> extends StandardTypedV1.Props<Input, Output> {
+        /** Methods for generating the input/output JSON Schema. */
+        readonly jsonSchema: StandardJSONSchemaV1.Converter;
+    }
+    /** The Standard JSON Schema converter interface. */
+    interface Converter {
+        /** Converts the input type to JSON Schema. May throw if conversion is not supported. */
+        readonly input: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+        /** Converts the output type to JSON Schema. May throw if conversion is not supported. */
+        readonly output: (options: StandardJSONSchemaV1.Options) => Record<string, unknown>;
+    }
+    /**
+     * The target version of the generated JSON Schema.
+     *
+     * It is *strongly recommended* that implementers support `"draft-2020-12"` and `"draft-07"`, as they are both in wide use. All other targets can be implemented on a best-effort basis. Libraries should throw if they don't support a specified target.
+     *
+     * The `"openapi-3.0"` target is intended as a standardized specifier for OpenAPI 3.0 which is a superset of JSON Schema `"draft-04"`.
+     */
+    type Target = "draft-2020-12" | "draft-07" | "openapi-3.0" | ({} & string);
+    /** The options for the input/output methods. */
+    interface Options {
+        /** Specifies the target version of the generated JSON Schema. Support for all versions is on a best-effort basis. If a given version is not supported, the library should throw. */
+        readonly target: Target;
+        /** Explicit support for additional vendor-specific parameters, if needed. */
+        readonly libraryOptions?: Record<string, unknown> | undefined;
+    }
+    /** The Standard types interface. */
+    interface Types<Input = unknown, Output = Input> extends StandardTypedV1.Types<Input, Output> {
+    }
+    /** Infers the input type of a Standard. */
+    type InferInput<Schema extends StandardTypedV1> = StandardTypedV1.InferInput<Schema>;
+    /** Infers the output type of a Standard. */
+    type InferOutput<Schema extends StandardTypedV1> = StandardTypedV1.InferOutput<Schema>;
+}