@wardby/cli 0.3.0 → 0.4.1

package/dist/providers/engine/types.d.ts

@@ -50,6 +50,19 @@ export interface LoadedTool {
 export type StepRunner = <T>(name: string, fn: () => Promise<T>) => Promise<T>;
 /** The no-checkpoint default: run the step body directly. */
 export declare const runStepInline: StepRunner;
+/**
+ * Live progress after a completed model turn: absolute cumulative totals,
+ * never deltas, so re-delivering one (a DBOS replay re-runs the loop over
+ * recorded steps) rewrites the same values instead of double counting.
+ */
+export interface EngineProgress {
+    turns: number;
+    usage: {
+        tokensIn: number;
+        tokensOut: number;
+        costUsd: number;
+    };
+}
 export interface EngineRunContext {
     agent: EngineAgent;
     tools: LoadedTool[];
@@ -57,6 +70,8 @@ export interface EngineRunContext {
     /** Host bridge: validates params (Zod-in-sandbox) then runs the tool body in the WASM sandbox. Never throws — a tool/validation failure is a JSON error result string, fed back to the model as the tool's result. */
     runSandboxTool(name: string, argsJson: string): Promise<string>;
     onText?: (delta: string) => void;
+    /** Called after each model turn that completed without error; the engine awaits it. */
+    onProgress?: (progress: EngineProgress) => Promise<void>;
     /** See StepRunner. Optional; the in-process executor leaves it unset. */
     step?: StepRunner;
 }
@@ -69,6 +84,10 @@ export interface EngineResult {
         tokensIn: number;
         tokensOut: number;
         costUsd: number;
+        /** Subset of tokensIn served from a prompt cache. */
+        cachedInputTokens?: number;
+        /** Tokens billed for writing prompt-cache entries (not part of tokensIn). */
+        cacheWriteTokens?: number;
     };
     error?: string;
 }

package/dist/providers/executor/composition.js

@@ -3,6 +3,7 @@ import { resolve } from "node:path";
 import { loadCodingConcurrencyConfig, loadContainerExecutorConfig, loadGitHubVcsConfig, loadKubernetesJobConfig, loadProviderConfig, } from "../../config/providers.js";
 import { summarizeRegistryFetches } from "../../coding/registry/report.js";
 import { drainCodingQueue } from "../../core/coding-queue.js";
+import { prismaServiceStateReporter } from "../../core/coding-service-status.js";
 import { logger } from "../../core/logger.js";
 import { EnvironmentCredentialResolver } from "../coding-proxy/environment-credentials.js";
 import { CodingProxy } from "../coding-proxy/proxy.js";
@@ -17,6 +18,7 @@ import { buildVcsProvider } from "../vcs/index.js";
 import { ContainerExecutor, PrismaContainerExecutionStore, RunCapabilityVault } from "./container.js";
 import { PrismaExecutionKindResolver, RoutingExecutor } from "./routing.js";
 import { createRepoAccessGate } from "../../core/repo-access.js";
+import { buildIssueTrackers } from "../issue-tracker/index.js";
 import { buildReviewHosts } from "../review-host/index.js";
 const compositionLog = logger.child({ module: "executor-composition" });
 /** Builds container execution only when Docker or Kubernetes is explicitly selected. */
@@ -41,6 +43,7 @@ export function buildConfiguredExecutor(options) {
         ledger: new PrismaProxyLedger(options.db),
         credentials: new EnvironmentCredentialResolver(env),
     });
+    const onServiceState = prismaServiceStateReporter(options.db);
     let jobs;
     if (providerConfig.jobs === "kubernetes") {
         if (!isRegistryDigest(config.workerImage)) {
@@ -65,6 +68,7 @@ export function buildConfiguredExecutor(options) {
         const api = options.kubernetesApi ?? new ClientNodeKubernetesApi({ context: kubernetes.context });
         const workerImage = config.workerImage;
         jobs = new KubernetesJobLauncher({
+            onServiceState,
             api,
             config: kubernetes,
             workspaceRoot,
@@ -87,6 +91,7 @@ export function buildConfiguredExecutor(options) {
     else {
         const stateRoot = resolve(config.stateRoot ?? resolve(tmpdir(), "wardby-docker-jobs"));
         jobs = new DockerJobLauncher({
+            onServiceState,
             stateRoot,
             workspaceRoot,
             proxyContainer: proxyContainer,
@@ -100,12 +105,13 @@ export function buildConfiguredExecutor(options) {
             },
         });
     }
+    const issueTrackers = buildIssueTrackers(env);
     const concurrency = loadCodingConcurrencyConfig(env);
     // The release hook needs the composed RoutingExecutor, which only exists
     // after the ContainerExecutor it wraps is built. The closure reads
     // `composed` only when a run finishes, which is after this function returns.
     const coding = new ContainerExecutor({
-        store: new PrismaContainerExecutionStore(options.db, { maxConcurrent: concurrency.maxConcurrent }),
+        store: new PrismaContainerExecutionStore(options.db, { maxConcurrent: concurrency.maxConcurrent, issueTrackers }),
         jobs,
         vcs,
         sessions,
@@ -121,6 +127,7 @@ export function buildConfiguredExecutor(options) {
         limits: { cpus: config.cpus, memoryMb: config.memoryMb, pids: config.pids, diskMb: config.diskMb },
         maxDiskMb: config.maxDiskMb,
         repoAccess: options.repoAccess ?? createRepoAccessGate({ db: options.db, hosts: buildReviewHosts(env) }),
+        issueUrl: (provider, key) => (provider === "jira" ? issueTrackers.jira?.issueUrl(key) : undefined),
         registryReport: async (runId) => {
             const rows = await options.db.registryFetch.findMany({ where: { runId }, orderBy: { createdAt: "asc" } });
             return summarizeRegistryFetches(rows);
@@ -131,6 +138,7 @@ export function buildConfiguredExecutor(options) {
                 executor: composed,
                 maxConcurrent: concurrency.maxConcurrent,
                 queueTimeoutSec: concurrency.queueTimeoutSec,
+                selfDefects: { db: options.db, issueTrackers },
             }).catch((err) => {
                 // Never throws: the next scheduler tick drains again.
                 compositionLog.warn({ err }, "coding queue drain after a released slot failed");

package/dist/providers/executor/container.d.ts

@@ -1,9 +1,10 @@
 import type { PrismaClient } from "#prisma";
-import type { CodingProvider } from "../../coding/provider.js";
+import { type CodingProvider } from "../../coding/provider.js";
+import type { IssueTrackerRegistry } from "../issue-tracker/types.js";
 import { type RepoAccessGate } from "../../core/repo-access.js";
 import { type CodingRunObserver } from "../../coding/observability.js";
 import { type CodingRunResult } from "../../coding/protocol.js";
-import type { ProxyProtocol } from "../coding-proxy/types.js";
+import type { ProxyModelTerms, ProxyProtocol } from "../coding-proxy/types.js";
 import type { JobHandle, JobResourceLimits, WorkspaceJobLauncher } from "../jobs/types.js";
 import type { VcsProvider } from "../vcs/types.js";
 import type { CodingImageSelector, ExecutionRecoveryResult, Executor, PersistedExecutionHandle } from "./types.js";
@@ -32,6 +33,9 @@ export interface ContainerRunSnapshot {
     collectExclude: unknown;
     /** Revision-in-place: set when this run continues another run's branch/PR. See preflight(). */
     rootCodingRunId: string | null;
+    /** The issue that triggered this run (CodingRun.issueProvider/issueKey); null when none. */
+    issueProvider?: string | null;
+    issueKey?: string | null;
     budgetUsd: number;
     /** The agent's own per-run budget; `budgetUsd` is less when its budget group had less left. */
     agentBudgetUsd?: number;
@@ -57,6 +61,9 @@ export interface ContainerRunSnapshot {
     profileRepository: string | null;
     /** How the profile's repository was authorized (CodingAgentProfile.repositoryAuthorizedVia). */
     repositoryAuthorizedVia: string | null;
+    /** The run's catalog entry recorded at dispatch (Run.pricingSnapshot); null on runs from before the catalog. */
+    pricingVersion: string | null;
+    pricingSnapshot: unknown;
 }
 /**
  * claimed: this caller owns provisioning. unavailable: someone else does, or
@@ -82,7 +89,13 @@ export declare class PrismaContainerExecutionStore implements ContainerExecution
     private readonly options;
     constructor(db: PrismaClient, options?: {
         maxConcurrent?: number;
+        /** Configured issue trackers: a coding run this store ends failed/lost/budget_exhausted files a self-defect. */
+        issueTrackers?: IssueTrackerRegistry;
     });
+    /** Best effort (bounded, never throws): only called by the write that made the row terminal, so it files once. */
+    private selfDefect;
+    /** An empty registry (no Jira site configured) means no self-defect queries at all. */
+    private get hasTrackers();
     load(runId: string): Promise<ContainerRunSnapshot | null>;
     claimProvisioning(runId: string, claimId: string): Promise<ProvisioningClaim>;
     persistHandle(runId: string, claimId: string, handle: JobHandle): Promise<void>;
@@ -98,6 +111,8 @@ export interface CodingSessionController {
         allowedModels: string[];
         deadlineAt: Date;
         budgetUsd: number;
+        /** The run's catalog entry; the proxy prices and shapes the run's requests from it. */
+        terms?: ProxyModelTerms;
     }): Promise<{
         id: string;
         capability: string;
@@ -159,6 +174,8 @@ export interface ContainerExecutorOptions {
      * reporting failure must never fail the run itself.
      */
     registryReport?: (runId: string) => Promise<RegistryReport>;
+    /** Browse URL for an issue of a tracker provider (composition wires the issue-tracker registry); undefined when unconfigured. */
+    issueUrl?: (provider: string, key: string) => string | undefined;
     /**
      * Repository authorization: every run is checked, before its workspace is
      * prepared, against the agent owner's current GitHub access (or a recorded
@@ -224,6 +241,10 @@ export declare class ContainerExecutor implements Executor {
      * access. Throws RepoAccessError (refused before anything is cloned).
      */
     private authorizeRepository;
+    /** The originating issue for the PR title/body: control-plane data from the CodingRun row, key re-validated. */
+    private issueFor;
+    /** The run's stored model terms; a run from before the catalog resolves them from the current catalog. */
+    private modelTerms;
     private preflight;
     private finishTerminal;
     /** The package report is informational: any failure loading it (a
@@ -241,6 +262,13 @@ export declare class ContainerExecutor implements Executor {
         repository: string;
         baseRef: string;
     }): Promise<string | null>;
+    /** One repository file at the run's base ref (Executor.readCodingRepositoryFile). */
+    readCodingRepositoryFile(input: {
+        repository: string;
+        baseRef: string;
+        path: string;
+        maxBytes: number;
+    }): Promise<string | null>;
     /** The job launcher decides (Kubernetes and Docker start services for both providers). */
     supportsCodingServices(provider: CodingProvider): boolean;
     private requireCurrent;

package/dist/providers/executor/container.js

@@ -1,23 +1,27 @@
 import { randomUUID } from "node:crypto";
 import { mkdir, realpath, rename, rm, writeFile } from "node:fs/promises";
 import { join, resolve, sep } from "node:path";
+import { withBaseCommit } from "../../coding/base-commit.js";
 import { normalizeCollectExclusions } from "../../coding/collect-exclude.js";
+import { codingProviderForModelProvider } from "../../coding/provider.js";
 import { CodingProfileSchema } from "../../coding/profile.js";
 import { parseStoredServices, storedServiceNames, workerServices } from "../../coding/services/catalog.js";
 import { MAX_SERVICE_DECLARATION_BYTES, SERVICE_DECLARATION_PATH } from "../../coding/services/declaration.js";
 import { SERVICE_UNREADY_CATEGORY, SERVICE_UNREADY_ERROR, serviceUnreadyName, serviceUnreadySentence, } from "../../coding/services/wording.js";
 import { PROTECTED_PATH_CATEGORY, protectedPathFromError, protectedPathSentence, } from "../../coding/protected-path-wording.js";
 import { budgetSentence } from "../../core/budget-wording.js";
+import { fileSelfDefect } from "../../core/self-defects.js";
 import { classifyProviderFailure, providerClassOfCategory, providerSentence, } from "../../core/provider-wording.js";
 import { logger } from "../../core/logger.js";
 import { requiredLevel } from "../../core/repo-access.js";
 import { ensurePrivateDirectory } from "../../core/private-directory.js";
 import { codingRunObserver } from "../../coding/observability.js";
 import { CODING_PROTOCOL_VERSION, CodingRunResultSchema, CodingTaskInputSchema, parseCodingAgentOutputJson, redactAndTruncate, } from "../../coding/protocol.js";
-import { getModelPricing } from "../llm/pricing.js";
-import { getAnthropicPricing } from "../llm/pricing-anthropic.js";
+import { parseStoredEntry } from "../llm/catalog-types.js";
+import { resolveCodingEntry } from "../../core/run-pricing.js";
 import { CODING_PROXY_ALIAS, CODING_PROXY_PORT, isImmutableDockerImage } from "../jobs/docker-isolation.js";
 import { normalizeRegistryLockfiles } from "../../coding/registry/lockfiles.js";
+import { ISSUE_KEY, ISSUE_TRACKER_NAMES } from "../issue-tracker/types.js";
 import { HEARTBEAT_TIMEOUT_MS } from "../../core/timing.js";
 const containerLog = logger.child({ module: "container-executor" });
 const TERMINAL_STATUSES = new Set(["succeeded", "failed", "refused", "lost", "budget_exhausted", "cancelled"]);
@@ -62,6 +66,15 @@ export class PrismaContainerExecutionStore {
         this.db = db;
         this.options = options;
     }
+    /** Best effort (bounded, never throws): only called by the write that made the row terminal, so it files once. */
+    async selfDefect(run) {
+        if (this.hasTrackers)
+            await fileSelfDefect(this.db, this.options.issueTrackers, run);
+    }
+    /** An empty registry (no Jira site configured) means no self-defect queries at all. */
+    get hasTrackers() {
+        return Object.values(this.options.issueTrackers ?? {}).some(Boolean);
+    }
     async load(runId) {
         const row = await this.db.run.findUnique({
             where: { id: runId },
@@ -88,6 +101,8 @@ export class PrismaContainerExecutionStore {
             protectedPaths: row.codingRun.protectedPaths,
             collectExclude: row.codingRun.collectExclude,
             rootCodingRunId: row.codingRun.rootCodingRunId,
+            issueProvider: row.codingRun.issueProvider,
+            issueKey: row.codingRun.issueKey,
             budgetUsd: Number(row.codingRun.budgetReservedUsd),
             agentBudgetUsd: Number(row.agent.budgetUsd),
             budgetGroupName: row.agent.budgetGroup?.name ?? null,
@@ -108,6 +123,8 @@ export class PrismaContainerExecutionStore {
             failureCategory: row.codingRun.failureCategory,
             profileRepository: row.agent.codingProfile?.repository ?? null,
             repositoryAuthorizedVia: row.agent.codingProfile?.repositoryAuthorizedVia ?? null,
+            pricingVersion: row.pricingVersion,
+            pricingSnapshot: row.pricingSnapshot,
         };
     }
     async claimProvisioning(runId, claimId) {
@@ -220,13 +237,14 @@ export class PrismaContainerExecutionStore {
         });
     }
     async complete(runId, status, result) {
-        await this.db.$transaction(async (tx) => {
+        const finishedAt = new Date();
+        const finished = await this.db.$transaction(async (tx) => {
             const run = await tx.run.findUnique({ where: { id: runId }, include: { codingRun: true } });
             if (!run?.codingRun)
                 throw new Error("coding_run_not_found");
             if (TERMINAL_STATUSES.has(run.status)) {
                 if (run.codingRun.result && stableJson(run.codingRun.result) === stableJson(result))
-                    return;
+                    return null;
                 throw new Error("coding_run_terminal_conflict");
             }
             await tx.codingRun.update({
@@ -238,26 +256,40 @@ export class PrismaContainerExecutionStore {
                 data: {
                     status,
                     finalText: result.summary,
-                    finishedAt: new Date(),
+                    finishedAt,
                     heartbeatAt: new Date(),
                     error: null,
                 },
             });
+            return { id: runId, agentId: run.agentId };
         });
+        if (finished && status === "budget_exhausted") {
+            await this.selfDefect({ ...finished, status, error: null, finishedAt });
+        }
     }
     async terminate(runId, status, error, audit) {
-        await this.db.$transaction(async (tx) => {
+        const finishedAt = new Date();
+        const agentId = await this.db.$transaction(async (tx) => {
             const updated = await tx.run.updateMany({
                 where: { id: runId, status: { in: ["pending", "running"] } },
-                data: { status, error, finishedAt: new Date(), heartbeatAt: new Date() },
+                data: { status, error, finishedAt, heartbeatAt: new Date() },
             });
-            if (updated.count && audit) {
+            if (!updated.count)
+                return null;
+            if (audit) {
                 await tx.codingRun.update({
                     where: { runId },
                     data: { failureCategory: audit.failureCategory, diagnosticId: audit.diagnosticId },
                 });
             }
+            if (!this.hasTrackers)
+                return null;
+            const row = await tx.run.findUnique({ where: { id: runId }, select: { agentId: true } });
+            return row?.agentId ?? null;
         });
+        // After commit, so the failure category is readable; cancelled/refused are skipped inside fileSelfDefect.
+        if (agentId)
+            await this.selfDefect({ id: runId, agentId, status, error, finishedAt });
     }
 }
 /** Plain capabilities live only for the short provisioning window. */
@@ -470,11 +502,12 @@ export class ContainerExecutor {
                     allowedModels: [run.model],
                     deadlineAt,
                     budgetUsd: run.budgetUsd,
+                    terms: this.modelTerms(run),
                 });
                 spendEnabled = true;
                 sessionId = session.id;
                 this.options.capabilities.set(runId, session.capability);
-                const inputArtifact = await this.writeInput(run, deadlineAt);
+                const inputArtifact = await this.writeInput(run, deadlineAt, workspace.baseCommit);
                 const beforeLaunch = await this.requireCurrent(runId);
                 if (TERMINAL_STATUSES.has(beforeLaunch.status))
                     throw new Error("coding_run_no_longer_active");
@@ -609,18 +642,50 @@ export class ContainerExecutor {
         if (!decision.ok)
             throw new RepoAccessError(`repo_access_${decision.reason}`);
     }
+    /** The originating issue for the PR title/body: control-plane data from the CodingRun row, key re-validated. */
+    issueFor(run) {
+        const { issueProvider, issueKey } = run;
+        if (!issueProvider || !issueKey || !ISSUE_KEY.test(issueKey))
+            return {};
+        let url;
+        try {
+            url = this.options.issueUrl?.(issueProvider, issueKey);
+        }
+        catch {
+            url = undefined;
+        }
+        const trackerName = Object.hasOwn(ISSUE_TRACKER_NAMES, issueProvider)
+            ? ISSUE_TRACKER_NAMES[issueProvider]
+            : undefined;
+        return {
+            issue: {
+                key: issueKey,
+                ...(url?.startsWith("https://") ? { url } : {}),
+                ...(trackerName ? { trackerName } : {}),
+            },
+        };
+    }
+    /** The run's stored model terms; a run from before the catalog resolves them from the current catalog. */
+    modelTerms(run) {
+        if (run.provider !== "codex" && run.provider !== "claude-code")
+            throw new Error("coding_provider_unsupported");
+        const stored = parseStoredEntry(run.pricingSnapshot);
+        if (stored && run.pricingVersion) {
+            if (stored.modelId !== run.model || codingProviderForModelProvider(stored.provider) !== run.provider) {
+                throw new Error("coding_run_pricing_mismatch");
+            }
+            return { version: run.pricingVersion, entry: stored };
+        }
+        const entry = resolveCodingEntry(run.provider, run.model);
+        return { version: entry.priceVersion, entry: parseStoredEntry(entry) };
+    }
     preflight(run) {
         try {
             if (run.status !== "pending" && run.status !== "running")
                 throw new Error("coding_run_status_invalid");
             if (run.agentKind !== "coding" || !run.ownerId)
                 throw new Error("coding_run_ownership_invalid");
-            if (run.provider === "codex")
-                getModelPricing(run.model);
-            else if (run.provider === "claude-code")
-                getAnthropicPricing(run.model);
-            else
-                throw new Error("coding_provider_unsupported");
+            this.modelTerms(run);
             if (!Number.isFinite(run.budgetUsd) || run.budgetUsd <= 0 || run.costUsd > run.budgetUsd) {
                 throw new Error("coding_run_budget_invalid");
             }
@@ -744,6 +809,7 @@ export class ContainerExecutor {
                 tests: output.tests,
                 tag: output.tag,
                 ...report,
+                ...this.issueFor(current),
             });
             const result = this.resultFor(output, current, finalized.outcome, finalized);
             await this.options.store.complete(run.runId, "succeeded", result);
@@ -884,6 +950,17 @@ export class ContainerExecutor {
             maxBytes: MAX_SERVICE_DECLARATION_BYTES,
         });
     }
+    /** One repository file at the run's base ref (Executor.readCodingRepositoryFile). */
+    async readCodingRepositoryFile(input) {
+        if (!this.options.vcs.readRepositoryFile)
+            return null;
+        return this.options.vcs.readRepositoryFile({
+            repository: input.repository,
+            ref: input.baseRef,
+            path: input.path,
+            maxBytes: input.maxBytes,
+        });
+    }
     /** The job launcher decides (Kubernetes and Docker start services for both providers). */
     supportsCodingServices(provider) {
         return this.options.jobs.supportsServicesFor?.(provider) === true;
@@ -929,7 +1006,7 @@ export class ContainerExecutor {
             return this.options.anthropicCredentialRef;
         throw new Error("coding_provider_not_configured:claude-code");
     }
-    async writeInput(run, deadlineAt) {
+    async writeInput(run, deadlineAt, baseCommit) {
         await ensurePrivateDirectory(this.artifactRoot);
         const rootReal = await realpath(this.artifactRoot);
         const directory = resolve(rootReal, run.runId);
@@ -941,13 +1018,17 @@ export class ContainerExecutor {
         const destination = join(directory, "input.json");
         const temporary = join(directory, `.input-${randomUUID()}.tmp`);
         const services = parseStoredServices(run.services);
+        const task = withBaseCommit(run.task, baseCommit);
+        if (task === run.task && /^[0-9a-f]{40}$/.test(baseCommit)) {
+            containerLog.warn({ event: "coding.base_commit_omitted", runId: run.runId }, "the coding task left no room for the base commit line");
+        }
         const input = CodingTaskInputSchema.parse({
             schemaVersion: CODING_PROTOCOL_VERSION,
             runId: run.runId,
             repository: run.repository,
             baseRef: run.baseRef,
             headRef: run.headRef,
-            task: run.task,
+            task,
             model: run.model,
             budgetUsd: run.budgetUsd,
             deadlineAt: deadlineAt.toISOString(),

package/dist/providers/executor/dbos.d.ts

@@ -38,6 +38,8 @@ export declare class DbosExecutor implements Executor {
     get executorId(): string;
     launch(): Promise<void>;
     close(): Promise<void>;
+    /** Where a run this executor marks failed files its self-defect (no-op without a configured issue tracker). */
+    private get selfDefects();
     start(runId: string): Promise<void>;
     stop(runId: string, reason?: string): Promise<void>;
     /**

package/dist/providers/executor/dbos.js

@@ -133,6 +133,10 @@ export class DbosExecutor {
             setActiveExecutor(undefined);
         await DBOS.shutdown({ workflowCompletionTimeoutMS: 5_000 });
     }
+    /** Where a run this executor marks failed files its self-defect (no-op without a configured issue tracker). */
+    get selfDefects() {
+        return { db: this.db, issueTrackers: this.providers.issueTrackers };
+    }
     async start(runId) {
         if (!this.launched)
             await this.launch();
@@ -165,7 +169,7 @@ export class DbosExecutor {
             // the same failure — dispatchRun's own `.catch` around `start()` calls
             // it too — which is harmless precisely because it is conditional and
             // idempotent: the second call matches zero rows.
-            await markRunFailedFromExecutorError(this.db, runId, err);
+            await markRunFailedFromExecutorError(this.db, runId, err, this.selfDefects);
             throw err;
         }
     }
@@ -241,10 +245,8 @@ export class DbosExecutor {
                 return { state: "terminal" };
             case "mark-failed":
                 this.resumeAttempts.delete(handle.runId);
-                await this.db.run.updateMany({
-                    where: { id: handle.runId, status: { in: ["pending", "running"] } },
-                    data: { status: "failed", error: decision.error, finishedAt: new Date() },
-                });
+                // Conditional (only a pending/running row), so a self-defect is filed only when this made the run failed.
+                await markRunFailedFromExecutorError(this.db, handle.runId, decision.error, this.selfDefects);
                 return { state: "terminal" };
             case "lost":
                 this.resumeAttempts.delete(handle.runId);

package/dist/providers/executor/routing.d.ts

@@ -27,6 +27,12 @@ export declare class RoutingExecutor implements Executor {
         repository: string;
         baseRef: string;
     }): Promise<string | null>;
+    readCodingRepositoryFile(input: {
+        repository: string;
+        baseRef: string;
+        path: string;
+        maxBytes: number;
+    }): Promise<string | null>;
     supportsCodingServices(provider: CodingProvider): boolean;
 }
 export declare class PrismaExecutionKindResolver implements ExecutionKindResolver {

package/dist/providers/executor/routing.js

@@ -64,6 +64,11 @@ export class RoutingExecutor {
             return null;
         return this.coding.readCodingServiceDeclaration(input);
     }
+    async readCodingRepositoryFile(input) {
+        if (!this.coding.readCodingRepositoryFile)
+            return null;
+        return this.coding.readCodingRepositoryFile(input);
+    }
     supportsCodingServices(provider) {
         return this.coding.supportsCodingServices?.(provider) === true;
     }

package/dist/providers/executor/types.d.ts

@@ -68,6 +68,18 @@ export interface Executor {
         repository: string;
         baseRef: string;
     }): Promise<string | null>;
+    /**
+     * The raw text of one repository file at `baseRef`, or null when absent.
+     * Throws (github_file_too_large, github_file_not_a_file, github_file_not_utf8)
+     * when the file is oversized or not UTF-8 text. Called by dispatch before its transaction (network call).
+     * Used for the knowledge note (src/knowledge/note.ts).
+     */
+    readCodingRepositoryFile?(input: {
+        repository: string;
+        baseRef: string;
+        path: string;
+        maxBytes: number;
+    }): Promise<string | null>;
     /**
      * Whether this executor can start coding-run services for a run of `provider`: its job launcher
      * says so (Kubernetes and Docker, for Codex and Claude Code).

package/dist/providers/issue-tracker/adf.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Atlassian Document Format helpers. Jira Cloud's v3 API takes and returns
+ * rich text as ADF; webhook payloads use the v2 shape (wiki-markup strings),
+ * so the readers (adfToText, adfMentionIds) accept both. Agents write a
+ * small Markdown subset (markdownToAdf); the control plane reads issue text
+ * as plain text (adfToText). Nothing here
+ * produces HTML or mention nodes: a model can never ping a person.
+ */
+export interface AdfNode {
+    type: string;
+    version?: number;
+    attrs?: Record<string, unknown>;
+    content?: AdfNode[];
+    text?: string;
+    marks?: Array<{
+        type: string;
+        attrs?: Record<string, unknown>;
+    }>;
+}
+/**
+ * Smart links (ADF inlineCard, what Jira's editor makes from a pasted issue link) for this site's
+ * issues: a bare `<siteUrl>/browse/KEY-1` URL, and a bare `KEY-1` whose project is in `projectKeys`
+ * (only those, so look-alikes such as UTF-8 or SHA-256 stay text).
+ */
+export interface SmartLinkOptions {
+    siteUrl: string;
+    projectKeys?: readonly string[];
+}
+export declare function markdownToAdf(markdown: string, smart?: SmartLinkOptions): AdfNode;
+export declare function adfToText(node: unknown, maxChars?: number): string;
+export declare function adfMentionIds(node: unknown): string[];