terramend 0.2.0

package/dist/utils/codexOAuth.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Pure-stdlib (fetch + Buffer) Codex OAuth refresh + JWT exp decoding.
+ *
+ * Lives here (not in codexAuth.ts) so the Next.js server side can import it
+ * via terramend/internal without dragging in node:child_process / spawn /
+ * mkdtemp from the rest of codexAuth.ts. Used by:
+ *   - action/utils/codexAuth.ts (re-exports refreshCodexAuthBody)
+ *   - utils/codexSecretRotation.ts (server-side maybeRotate at run-context)
+ *
+ * See wiki/codex-auth.md for the end-to-end refresh lifecycle.
+ */
+export interface CodexAuthBody {
+    auth_mode: "chatgpt";
+    tokens: {
+        access_token: string;
+        refresh_token: string;
+        id_token?: string;
+        account_id?: string;
+    };
+    last_refresh?: string;
+}
+/** OAuth client id Codex CLI and OpenCode both use against `auth.openai.com`.
+ * Same chain — a refresh token minted via `codex login --device-auth` can be
+ * refreshed against this client_id. */
+export declare const CODEX_OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export declare const CODEX_OAUTH_TOKEN_URL = "https://auth.openai.com/oauth/token";
+/** thrown when the OAuth provider rejects the refresh token (4xx). callers
+ * can distinguish "race-lost / token revoked" from network errors via
+ * `instanceof OAuthInvalidGrantError`. */
+export declare class OAuthInvalidGrantError extends Error {
+    readonly status: number;
+    constructor(status: number, body: string);
+}
+/** force one refresh round-trip against the OAuth provider. returns the
+ * rotated Codex-shaped blob (the auth.json body verbatim). does NOT persist
+ * — caller is responsible for writing back to wherever the token lives.
+ *
+ * server-side callers (maybeRotateCodexSecret) hold a DB row lock around
+ * this call so concurrent runs serialize: first one rotates, subsequent
+ * ones see the fresh value and skip. The 10s timeout is critical for that
+ * use: it caps how long a stalled auth.openai.com holds the row lock,
+ * keeping us well under the enclosing 30s transaction budget so the lock
+ * always releases and queued callers get a turn instead of timing out on
+ * the tx wrapper. Real OAuth latency is sub-second; 10s is generous. */
+export declare function refreshCodexAuthBody(body: CodexAuthBody): Promise<CodexAuthBody>;
+/** decode the access_token's JWT payload and return its `exp` claim in ms
+ * since epoch. returns null if the token isn't a parseable JWT or has no
+ * `exp` claim — caller falls back to "treat as expired".
+ *
+ * We don't verify the JWT signature (we'd need OpenAI's JWKS); we're only
+ * using the claim as a freshness hint. The actual auth check happens
+ * server-side at OpenAI when the token is used — trusting a fake JWT here
+ * would just delay the inevitable 401 from OpenAI. No security boundary
+ * at this decode step. */
+export declare function decodeJwtExpMs(token: string): number | null;
+/** parse + validate a Codex auth.json body from its JSON-string form.
+ * returns null on any shape mismatch — caller treats as "no codex auth". */
+export declare function parseCodexAuthBody(raw: string): CodexAuthBody | null;
+/** serialize a CodexAuthBody to its canonical on-disk form. */
+export declare function stringifyCodexAuthBody(body: CodexAuthBody): string;

package/dist/utils/diffCoverage.d.ts

@@ -0,0 +1,63 @@
+export type DiffLineRange = {
+    startLine: number;
+    endLine: number;
+};
+export type DiffTocEntry = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+};
+export type DiffCoverageFileBreakdown = {
+    filename: string;
+    startLine: number;
+    endLine: number;
+    totalLines: number;
+    coveredLines: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+};
+export type DiffCoverageBreakdown = {
+    totalLines: number;
+    coveredLines: number;
+    unreadLines: number;
+    coveragePercent: number;
+    coveredRanges: DiffLineRange[];
+    unreadRanges: DiffLineRange[];
+    files: DiffCoverageFileBreakdown[];
+};
+export type DiffCoverageState = {
+    diffPath: string;
+    totalLines: number;
+    tocEntries: DiffTocEntry[];
+    coveredRanges: DiffLineRange[];
+    coveragePreflightRan: boolean;
+    lastBreakdown?: string | undefined;
+};
+export declare function countLines(params: {
+    content: string;
+}): number;
+export declare function parseDiffTocEntries(params: {
+    toc: string;
+}): DiffTocEntry[];
+export declare function createDiffCoverageState(params: {
+    diffPath: string;
+    totalLines: number;
+    toc: string;
+    previous?: DiffCoverageState | undefined;
+}): DiffCoverageState;
+export declare function recordDiffReadFromToolUse(params: {
+    state: DiffCoverageState | undefined;
+    toolName: string;
+    input: unknown;
+    cwd: string;
+}): boolean;
+export declare function getDiffCoverageBreakdown(params: {
+    state: DiffCoverageState;
+}): DiffCoverageBreakdown;
+export declare function renderDiffCoverageBreakdown(params: {
+    diffPath: string;
+    breakdown: DiffCoverageBreakdown;
+}): string;
+export declare function countLinesInRanges(params: {
+    ranges: DiffLineRange[];
+}): number;

package/dist/utils/errorReport.d.ts

@@ -0,0 +1,17 @@
+import type { ToolState } from "#app/toolState";
+interface ReportErrorParams {
+    toolState: ToolState;
+    error: string;
+    title?: string;
+    /**
+     * When the run has no pre-existing progress comment to update (silent
+     * IncrementalReview / pull_request_synchronize, mode-less polls), create
+     * a fresh issue comment on `toolState.issueNumber` instead of returning
+     * silently. Used for terminal errors (BillingError, TransientError) where
+     * the GH job summary is the only other surface and most users never open
+     * it. see #775.
+     */
+    createIfMissing?: boolean;
+}
+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,84 @@
+/**
+ * git authentication via GIT_ASKPASS.
+ *
+ * a localhost HTTP server serves tokens via UUID codes whose lifetime is
+ * bounded by the parent $git() invocation: register() makes the code active,
+ * the script (and any sibling subprocess — e.g. git-lfs pre-push) can fetch
+ * the token any number of times, and $git()'s finally calls revoke() to
+ * close the window. each $git() call writes a unique askpass script with
+ * the server port+code baked into the file body — no secrets in subprocess
+ * env. a replay of a revoked code trips a 409 and revokes the underlying
+ * github installation token.
+ *
+ * see wiki/askpass.md for full security documentation.
+ */
+import type { GitAuthServer } from "#app/utils/gitAuthServer";
+type SafeGitSubcommand = "fetch" | "push";
+type GitAuthOptions = {
+    token: string;
+    cwd?: string;
+    disableHooks?: boolean;
+};
+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 code with the auth server (valid for the lifetime
+ * of this invocation), writes a unique askpass script with port+code baked
+ * in, spawns git with GIT_ASKPASS pointing to the script. on completion,
+ * revokes the code and deletes the script in finally. multiple sibling
+ * askpass calls within one invocation (e.g. git itself + git-lfs pre-push)
+ * all see a valid code; replay attempts after finally trip a 409 and the
+ * server revokes the underlying github token as a tamper signal.
+ *
+ * @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>;
+/**
+ * shallow-clone unreachable: when an existing local depth is too shallow for
+ * git to traverse to the requested ref's ancestry, the remote walk fails with
+ * one of these wordings (git emits the full OID via oid_to_hex, so the bound
+ * is 40 for SHA-1 or 64 for SHA-256). detecting both lets a single deepen
+ * retry recover before the error reaches the agent — see issue #564 for the
+ * original `git_fetch` precedent and #656 for the `checkout_pr` follow-up.
+ */
+export declare const SHALLOW_UNREACHABLE_PATTERNS: RegExp[];
+/**
+ * large enough to clear the merge base on most real-world PRs without
+ * downloading the full history; matches the fallback used by
+ * `checkoutPrBranch` when the GitHub compare API is unavailable.
+ */
+export declare const DEEPEN_RETRY_DEPTH = 1000;
+/**
+ * authenticated `git fetch` that recovers from shallow-unreachable errors
+ * by retrying once with `--deepen=1000`. callers pass the same args they
+ * would to `$git("fetch", ...)`; on shallow-unreachable failures in a
+ * shallow repo, the second attempt prepends `--deepen=N` and strips any
+ * caller-supplied `--depth=` (the two flags are mutually exclusive, and
+ * the caller's depth is what got us into this mess).
+ *
+ * non-shallow-unreachable errors and non-shallow repos rethrow unchanged,
+ * so this is safe to wrap any fetch without changing fast-path behavior.
+ */
+export declare function $gitFetchWithDeepen(args: string[], options: GitAuthOptions, label?: string): Promise<GitResult>;
+export {};

package/dist/utils/gitAuthServer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * ASKPASS-based git authentication server.
+ *
+ * serves tokens via a localhost HTTP server with per-$git()-call 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.
+ *
+ * lifetime: the code is valid for as long as the $git() invocation is
+ * running. multiple askpass calls within one invocation (e.g. git's own
+ * fetch/push + a git-lfs pre-push hook that also authenticates) all
+ * succeed. $git() calls revoke(code) in finally; subsequent requests for
+ * a revoked code trigger immediate token revocation via the GitHub API
+ * as a tamper-evidence precaution (an agent replaying the code after the
+ * legitimate window has closed is the realistic attack we still catch).
+ */
+export type GitAuthServer = {
+    port: number;
+    register: (token: string) => string;
+    revoke: (code: string) => void;
+    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 dev-run.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,48 @@
+import { type AgentId } from "#app/external";
+import type { Mode } from "#app/modes";
+import type { ResolvedPayload } from "#app/utils/payload";
+import type { LearningsHeading } from "#app/utils/runContext";
+import type { RunContextData } from "#app/utils/runContextData";
+interface InstructionsContext {
+    payload: ResolvedPayload;
+    repo: RunContextData["repo"];
+    modes: Mode[];
+    agentId: AgentId;
+    outputSchema?: Record<string, unknown> | undefined;
+    /** absolute path to the seeded learnings tmpfile, or null when the file
+     * couldn't be seeded for some reason. main.ts always seeds, so in
+     * practice this is always set; the null case keeps the type honest. */
+    learningsFilePath: string | null;
+    /** server-parsed TOC for the body of the learnings tmpfile. rendered
+     * inline into the LEARNINGS prompt section so the agent can `read_file`
+     * targeted line ranges instead of pulling the whole file into context. */
+    learningsHeadings: LearningsHeading[];
+    /** agent-facing description of a setup lifecycle hook failure (see
+     * `describeSetupFailure`), rendered as a SETUP HOOK FAILED banner. empty
+     * string when the hook succeeded, was skipped, or wasn't configured. */
+    setupHookFailure: string;
+}
+export interface ResolvedInstructions {
+    full: string;
+    system: string;
+    user: string;
+    eventInstructions: string;
+    event: string;
+    runtime: string;
+}
+/** render the heading list as an indented bullet TOC. ranges shown in
+ * parentheses (`(L3-L18)`); the start line is always the heading line
+ * itself, so reading the listed range gives the agent the heading +
+ * body together. shallowest heading depth in the body sits at the root
+ * column; deeper levels indent by `(depth - rootDepth) * 2` spaces. */
+export declare function renderLearningsToc(headings: LearningsHeading[]): string;
+/** assemble the LEARNINGS prompt section: file path + intro + either
+ * the rendered heading TOC (when the body has structure) or a no-headings
+ * affordance pointing the agent at the reflection turn for restructuring.
+ * empty string when the seed step failed and there's no path to surface. */
+export declare function buildLearningsSection(ctx: {
+    filePath: string | null;
+    headings: LearningsHeading[];
+}): string;
+export declare function resolveInstructions(ctx: InstructionsContext): ResolvedInstructions;
+export {};

package/dist/utils/leapingComment.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The prefix text for the initial "leaping into action" comment.
+ * Used to detect whether a progress comment is still in its initial state
+ * and hasn't been updated with real progress or error messages.
+ *
+ * Lives in `utils/` (not `mcp/`) so it can be re-exported via `terramend/internal`
+ * without dragging the MCP server's transitive imports into the Next.js app's
+ * type-check graph.
+ */
+export declare const LEAPING_INTO_ACTION_PREFIX = "Leaping into action";
+export declare function isLeapingIntoActionCommentBody(body: string): boolean;

package/dist/utils/learnings.d.ts

@@ -0,0 +1,62 @@
+import type { ToolContext } from "#app/mcp/server";
+import { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary } from "#app/utils/learningsTruncate";
+export { MAX_LEARNINGS_LENGTH, truncateAtLineBoundary };
+/**
+ * Repo-level learnings — operational facts about a repo (setup steps, test
+ * commands, conventions, gotchas) that accumulate across agent runs and feed
+ * back into future runs as durable context. Modeled on the PR-summary tmpfile
+ * pattern (see action/utils/prSummary.ts):
+ *
+ *   1. server seeds `terramend-learnings.md` with the verbatim body of
+ *      `Repo.learnings` (or empty for fresh repos), and parses headings
+ *      server-side (`utils/learningsToc.ts`) — the parsed TOC is rendered
+ *      into the LEARNINGS prompt section, not into the file
+ *   2. the agent reads the TOC in the prompt and uses listed line ranges
+ *      to read just the sections relevant to the current task — file can
+ *      grow large, but only targeted ranges hit the agent's context
+ *   3. agent edits the file in place at end-of-run during the reflection
+ *      turn (see action/agents/postRun.ts buildLearningsReflectionPrompt)
+ *   4. main.ts reads the file back at end-of-run and PATCHes
+ *      `/api/repo/[owner]/[repo]/learnings` if the body changed
+ *
+ * Edit-in-place avoids stuffing the entire learnings list into both the
+ * prompt context and an `update_learnings` MCP tool call (which previously
+ * required passing the FULL merged list as a string parameter — an
+ * output-token tax that grew linearly with the learnings size).
+ *
+ * Section structure is agent-curated. The reflection prompt teaches
+ * hierarchy + a soft 300-line-per-section cap to keep TOC ranges
+ * agent-targetable on long-lived repos; there is no fixed taxonomy.
+ */
+export declare const LEARNINGS_FILE_NAME = "terramend-learnings.md";
+export declare function learningsFilePath(tmpdir: string): string;
+/** seed the rolling learnings tmpfile with the verbatim DB body (or empty
+ * string for fresh repos). returns the absolute path. the parsed TOC is
+ * carried separately via `RepoSettings.learningsHeadings` and rendered
+ * into the prompt by `resolveInstructions`, so the file on disk is just
+ * the body — no markers, no scaffold, no in-file TOC. */
+export declare function seedLearningsFile(params: {
+    tmpdir: string;
+    current: string | null;
+}): Promise<string>;
+/** read the agent-edited learnings file. returns null when the file is
+ * missing or unreadable (treated as "no change"). caps content at the
+ * server's max length to avoid a 400 round-trip. */
+export declare function readLearningsFile(path: string): Promise<string | null>;
+/**
+ * Read the agent-edited repo-level learnings tmpfile and PATCH it to
+ * `Repo.learnings`.
+ *
+ * Best-effort: any failure is logged and does not affect the run's success
+ * status. Skips the PATCH when the file is byte-trim-identical to its seed —
+ * the agent didn't touch it, so writing the same content back would just
+ * burn a `LearningsRevision` row and an API round-trip.
+ *
+ * `ctx.toolState.model` is forwarded so `LearningsRevision.model` keeps
+ * populating; it powers the per-revision attribution badge in the UI
+ * history view.
+ *
+ * `learningsPersistAttempted` guards against double-execution between the
+ * normal end-of-run path and the SIGINT/SIGTERM handler.
+ */
+export declare function persistLearnings(ctx: ToolContext): Promise<void>;

package/dist/utils/learningsTruncate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * pure string helpers for capping and line-boundary-truncating the
+ * `Repo.learnings` body. lives in its own module (vs alongside
+ * `learnings.ts`) so the proprietary root app can re-export it through
+ * `action/internal/index.ts` without dragging the entire MCP type graph
+ * along — `learnings.ts` imports `ToolContext` for its runtime helpers,
+ * and pulling that into the SDK-facing `internal` barrel expands the
+ * type graph reachable from root `tsc` and `cf-worker-indexing` to every
+ * tool module under `action/mcp/`. keeping these helpers MCP-free is the
+ * cheap structural fix.
+ *
+ * see `action/utils/learnings.ts` for the full learnings-file lifecycle.
+ */
+/** maximum size of `Repo.learnings` body in chars. action truncates the
+ * read-back BEFORE the PATCH to avoid sending an oversized payload; the
+ * server applies the same truncation as a defense-in-depth backstop (any
+ * caller that misses the client-side step would otherwise persist a
+ * mid-line tail, breaking the next-run TOC parse).
+ *
+ * raised from 10k → 100k once the TOC affordance landed: with line-range
+ * reads via the server-parsed TOC the agent doesn't ingest the whole
+ * file, so the cap is governed by curation discipline rather than a
+ * tight byte ceiling. 100k holds ~400-500 short bullets. */
+export declare const MAX_LEARNINGS_LENGTH = 100000;
+export declare function truncateAtLineBoundary(body: string, cap: number): string;

package/dist/utils/lifecycle.d.ts

@@ -0,0 +1,57 @@
+export interface ExecuteLifecycleHookParams {
+    event: string;
+    script: string | null;
+    /**
+     * when true, after the hook runs (success or failure), discard tracked-file
+     * mods so the agent doesn't see hook-generated drift (e.g. `pnpm install`
+     * rewriting a lockfile). untracked files are preserved — hooks that
+     * intentionally materialize files (e.g. a `.env` from a template) stay
+     * visible to the agent. skipped (with a warning) if the tree had
+     * pre-existing tracked changes before the hook ran, so we never clobber
+     * pre-existing work; pre-existing untracked files are ignored for this
+     * gate because `git restore --staged --worktree .` doesn't touch them
+     * anyway. no-op when no script was configured.
+     */
+    normalizeWorkingTreeAfter?: boolean;
+}
+/** structured failure info — `output` on the `exit` variant is trimmed
+ * stderr, falling back to stdout when stderr is empty. */
+export type LifecycleHookFailure = {
+    kind: "exit";
+    exitCode: number;
+    output: string;
+} | {
+    kind: "timeout";
+} | {
+    kind: "spawn";
+    spawnError: string;
+};
+/** one-line, agent-facing description of a hook failure. empty string when
+ * there was no failure, so callers can pass the result straight through to a
+ * prompt section that omits itself on empty. */
+export declare function describeSetupFailure(failure: LifecycleHookFailure | undefined): string;
+export interface LifecycleHookResult {
+    /**
+     * human-readable warning when the hook failed. includes retry guidance:
+     * transient spawn/exit errors are worth retrying, timeouts and
+     * persistent failures are not. absent when the hook succeeded or was
+     * skipped. setup/post-checkout callers surface this verbatim; prepush
+     * builds its own message from `failure` instead.
+     */
+    warning?: string;
+    /**
+     * structured failure info — undefined when the hook succeeded or was
+     * skipped. lets callers compose their own messaging without parsing the
+     * `warning` string.
+     */
+    failure?: LifecycleHookFailure;
+}
+/**
+ * execute a lifecycle hook script if one is configured.
+ *
+ * soft-fails: instead of throwing on hook errors, returns a warning string
+ * (and structured failure info) so callers can choose how to surface it
+ * (mcp tools relay it to the agent; setup logs it and adds a prompt banner).
+ * timeouts are flagged as non-retryable in the warning text.
+ */
+export declare function executeLifecycleHook(params: ExecuteLifecycleHookParams): Promise<LifecycleHookResult>;