export type PrTokenSource = 'project' | 'env' | 'gh-cli' | 'github_app' | 'credential-helper'; export interface ResolvedPrToken { token: string; source: PrTokenSource; /** * Set only on a credential-helper rescue: the backend refused first with * this code (e.g. REPO_NOT_INSTALLED) and the helper supplied a token * anyway. Lets the caller log WHY the fallback was used without ever * seeing the token. */ note?: string; } /** A typed backend refusal: the UPPER_SNAKE code names the fix. */ export interface PrTokenRefusal { error: { code: string; message: string; }; } export interface BackendRunTokenOpts { remoteUrl: string; projectId?: string | null; apiKey?: string | null; apiBaseUrl?: string | null; /** Passed in the POST body when present (lets the hub audit per task). */ taskId?: string | null; } /** Best-effort ambient GitHub CLI token (null when gh is absent/logged-out). */ export declare function ghAuthToken(): string | null; /** * GitHub-shaped token check for the credential-helper rescue. * * Some helpers answer `git credential fill` with a username or some other * non-token secret; pushing with that burns the attempt on a 401 and the * report then blames the wrong thing. So on a github.com host ONLY a * GitHub token shape is accepted (classic `ghp_*` family + fine-grained * `github_pat_*` + the legacy 40-hex PAT). Non-GitHub forges (Gitea accepts * any non-empty password) take whatever the helper stored. */ export declare function looksLikeGitHubToken(value: string): boolean; /** * Best-effort machine credential (step 5). Runs `git credential fill` for the * remote's host and returns the filled password when it is usable. Returns * null on every failure — absent git, timeout, non-zero exit, empty password, * or a non-token-shaped secret on a github.com host. Never throws, never * logs the secret (callers log only the source name). * * NOTE on where the password can come from: `fill` consults the configured * helpers AND, when they miss, the prompt fallback (`GIT_ASKPASS` / * `core.askPass`) — on a VS Code-integrated shell that fallback silently * returns the editor's stored GitHub session. That is ordinary `fill` * semantics and a session token is a fine credential (same trust boundary as * manager-core), so it is accepted, not scrubbed. `GIT_TERMINAL_PROMPT=0` * keeps a truly-interactive prompt from hanging the run past the timeout. */ export declare function credentialFillToken(remoteUrl: string): ResolvedPrToken | null; /** * Ask the hub for a one-shot token for this run (step 4). * * Returns null ONLY when there is no run identity (no project, no key) — a * normal "not connected" state, never an error. Every answered request * resolves to either a token or a TYPED refusal carrying the backend's * UPPER_SNAKE code and message (truncated to 300 chars); a request that never * got an answer (network/timeout) is `RUN_TOKEN_UNREACHABLE`. Callers must * NOT treat a typed refusal as "try nothing else" — see `resolvePrToken`. */ export declare function backendRunToken(opts: BackendRunTokenOpts): Promise; export type ResolvePrTokenOpts = BackendRunTokenOpts; export type ResolvePrTokenResult = ResolvedPrToken | PrTokenRefusal | null; /** * Full precedence chain. Pure except for the env/process reads and the * optional backend call — `gh` and the network are only touched when every * earlier step missed, so the common PAT/env path stays side-effect free. * * The backend leg NEVER short-circuits to a refusal: a typed error is * remembered, the credential helper is still tried (it may hold a fine PAT * while the App installation is merely missing the repo), and a helper hit * carries the backend code in `note` so the caller can log why the fallback * was used. Only when the helper also misses is the typed error surfaced. */ export declare function resolvePrToken(opts: ResolvePrTokenOpts): Promise; /** * User-facing PR refusal for a typed run-token error. Every branch ends with * "The branch IS pushed" — the push already succeeded, so the refusal is * never a data-loss scare, only a next step. */ export declare function prRefusalLine(code: string, message: string): string;