@cat-factory/server 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/agents/CompositeAgentExecutor.d.ts

@@ -0,0 +1,39 @@
+import { type AgentExecutor, type AgentJobHandle, type AgentJobUpdate, type AgentRunContext, type AgentRunResult, type AsyncAgentExecutor } from '@cat-factory/kernel';
+export declare class CompositeAgentExecutor implements AsyncAgentExecutor {
+    private readonly inline;
+    private readonly container;
+    constructor(inline: AgentExecutor, container: AgentExecutor | null);
+    /**
+     * The executor that handles a given step's kind. Container kinds REQUIRE a real
+     * sandbox: with none wired we throw rather than fall back to the inline executor,
+     * because a one-shot LLM call cannot operate on repo contents.
+     */
+    private pick;
+    run(context: AgentRunContext): Promise<AgentRunResult>;
+    /**
+     * Preview the model the step will run, forwarding to the executor that will
+     * handle its kind. Best-effort: returns undefined when the picked executor can't
+     * preview. `pick` throws for an unwired container kind — that real error surfaces
+     * at dispatch, so the engine treats this preview as optional and guards the call.
+     */
+    resolveModel(context: AgentRunContext): Promise<string | undefined>;
+    /**
+     * Whether the step runs on a flat-rate subscription (quota) model, forwarding to
+     * the executor that handles its kind (only the container executor runs subscription
+     * harnesses). Best-effort: an inline kind, an unwired container, or an executor
+     * without the capability all report false (budget-metered, the prior behaviour).
+     */
+    isQuotaBased(context: AgentRunContext): Promise<boolean>;
+    /** Async only for container kinds whose executor actually supports polling. */
+    runsAsync(context: AgentRunContext): boolean;
+    startJob(context: AgentRunContext): Promise<AgentJobHandle>;
+    pollJob(handle: AgentJobHandle): Promise<AgentJobUpdate>;
+    /**
+     * Best-effort container reclaim. The engine narrows the composite (not the inner
+     * container executor) when stopping a run, so the composite must forward stopJob
+     * to the container — otherwise the Layer-2 reclaim silently no-ops and leaks a
+     * warm instance. Delegates only when a container that supports it is wired.
+     */
+    stopJob(handle: AgentJobHandle): Promise<void>;
+}
+//# sourceMappingURL=CompositeAgentExecutor.d.ts.map

package/dist/agents/CompositeAgentExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EAExB,MAAM,qBAAqB,CAAA;AAkF5B,qBAAa,sBAAuB,YAAW,kBAAkB;IAE7D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAGvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAJ5B,YACmB,MAAM,EAAE,aAAa,EAGrB,SAAS,EAAE,aAAa,GAAG,IAAI,EAC9C;IAEJ;;;;OAIG;IACH,OAAO,CAAC,IAAI;IAmBZ,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAErD;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAGlE;IAED;;;;;OAKG;IACH,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvD;IAED,+EAA+E;IAC/E,SAAS,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAG3C;IAED,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAM1D;IAED,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC,CAMvD;IAED;;;;;OAKG;IACG,OAAO,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAInD;CACF"}

package/dist/agents/CompositeAgentExecutor.js

@@ -0,0 +1,169 @@
+import { isAsyncAgentExecutor, } from '@cat-factory/kernel';
+import { registeredKindRequiresContainer } from '@cat-factory/agents';
+// Routes each pipeline step to the right executor by agent kind. The kinds that
+// produce and commit files against a real checkout — implementation (`coder`),
+// the external-dependency mock builder (`mocker`), the Playwright e2e test
+// writer (`playwright`) and the business-logic documenter (`business-documenter`,
+// which reads the implementation and commits domain-rules docs) — run in a real
+// sandbox via the container executor. The `architect` also runs in a container, but
+// read-only: it explores the repo before proposing (no commits, like `analysis`).
+// Every other kind (reviewer and the other companions, tester, the
+// `business-reviewer` that reports on a change, custom) stays on the inline LLM
+// executor. This keeps container cost/latency to the phases that actually need a real
+// workspace, while pure review/companion steps remain single-shot LLM calls.
+//
+// There is deliberately NO inline fallback for the container kinds: a one-shot
+// LLM call cannot clone a repo, edit files, commit and open a PR, so routing an
+// implementer step to the inline executor produces plausible-looking text that is
+// silently useless. When no sandbox is wired (`container` is null), the container
+// kinds throw instead — the run fails loudly rather than pretending to succeed.
+//
+// Runtime-neutral: both the Cloudflare Worker and the Node service wire this
+// composite (inline `AiAgentExecutor` + a container executor backed by a
+// per-run Cloudflare Container or an org's self-hosted runner pool).
+/**
+ * Agent kinds that need a real checkout to operate on repo contents (clone,
+ * edit/commit files, open a PR) and so run in a container rather than inline:
+ * code implementation (`coder`), WireMock mock building (`mocker`), Playwright
+ * end-to-end test authoring (`playwright`) and business-logic documentation
+ * (`business-documenter`, which reads the code and commits the domain-rules docs).
+ */
+const CONTAINER_KINDS = new Set([
+    'coder',
+    'mocker',
+    'playwright',
+    'business-documenter',
+    // The Blueprinter step clones the repo, regenerates the in-repo `blueprints/`
+    // folder and commits it — a real-checkout operation, so it runs in a container.
+    'blueprints',
+    // The spec-writer clones (or creates) the implementation branch and commits the
+    // in-repo `spec/` folder onto it — a real-checkout operation, so it runs in a
+    // container. Like the blueprinter it returns a structured doc.
+    'spec-writer',
+    // The architect explores the repository (read-only) before proposing a design, so
+    // it needs a real checkout. Like `analysis` it makes no edits — the harness produces
+    // no commit and opens no PR — and returns its proposal as prose `output`.
+    'architect',
+    // The CI-fixer clones the PR head branch, runs the failing build/tests, fixes
+    // them and pushes back to the same branch — a real-checkout operation. (The `ci`
+    // step itself is NOT here: it is a special, non-agent gate handled in the engine
+    // that *dispatches* a `ci-fixer` job; only the fixer reaches this executor.)
+    'ci-fixer',
+    // The conflict-resolver clones the PR head branch, merges the base in and resolves
+    // the conflicts on the same branch — a real-checkout operation. (The `conflicts`
+    // gate itself is NOT here: like `ci` it is a non-agent engine gate that *dispatches*
+    // a `conflict-resolver` job; only the resolver reaches this executor.)
+    'conflict-resolver',
+    // The merger clones the PR head branch to assess the diff (complexity/risk/impact)
+    // before the engine decides whether to auto-merge — a real-checkout operation.
+    'merger',
+    // The tech-debt `analysis` agent clones the repo to inspect it and emit a report.
+    // It is read-only (makes no edits) so the coding-agent harness produces no commit
+    // and opens no PR — but it still needs a real checkout, so it runs in a container.
+    'analysis',
+    // The tester clones the PR branch, stands up infra (local docker-compose or an
+    // ephemeral env), runs the suite and returns a structured report — a real-checkout
+    // operation. (The `tester` step is also a special engine gate that loops a `fixer`
+    // on a withheld greenlight, mirroring `ci`/`ci-fixer`; the engine dispatches both
+    // jobs, which reach this executor.)
+    'tester',
+    // The fixer clones the PR head branch, applies fixes from the Tester's report and
+    // pushes back to the same branch — a real-checkout operation, like `ci-fixer`.
+    'fixer',
+    // The on-call agent clones the released PR head to correlate its diff with the
+    // Datadog regression evidence and returns a JSON assessment — a real-checkout
+    // operation (makes no commits). (The `post-release-health` gate itself is NOT here:
+    // like `ci` it is a non-agent engine gate that *dispatches* an `on-call` job; only
+    // the on-call agent reaches this executor.)
+    'on-call',
+]);
+export class CompositeAgentExecutor {
+    inline;
+    container;
+    constructor(inline, 
+    // null when no sandbox is wired — container kinds then fail loudly (see below)
+    // rather than silently degrading to a useless one-shot inline call.
+    container) {
+        this.inline = inline;
+        this.container = container;
+    }
+    /**
+     * The executor that handles a given step's kind. Container kinds REQUIRE a real
+     * sandbox: with none wired we throw rather than fall back to the inline executor,
+     * because a one-shot LLM call cannot operate on repo contents.
+     */
+    pick(context) {
+        // Built-in container kinds, plus any custom kind a deployment registered with
+        // `requiresContainer: true` (e.g. a proprietary org package contributing a
+        // repo-operating agent), need a real checkout; everything else runs inline.
+        const needsContainer = CONTAINER_KINDS.has(context.agentKind) || registeredKindRequiresContainer(context.agentKind);
+        if (!needsContainer)
+            return this.inline;
+        if (!this.container) {
+            throw new Error(`Agent kind '${context.agentKind}' needs a real checkout (clone/edit/commit/PR) ` +
+                'and cannot run as a one-shot LLM call. Its sandbox prerequisites must be wired: ' +
+                'a runner backend (the EXEC_CONTAINER binding on the Worker, or a registered ' +
+                'runner pool with RUNNERS_ENABLED), plus the GitHub App, the public proxy URL ' +
+                'and AUTH_SESSION_SECRET.');
+        }
+        return this.container;
+    }
+    run(context) {
+        return this.pick(context).run(context);
+    }
+    /**
+     * Preview the model the step will run, forwarding to the executor that will
+     * handle its kind. Best-effort: returns undefined when the picked executor can't
+     * preview. `pick` throws for an unwired container kind — that real error surfaces
+     * at dispatch, so the engine treats this preview as optional and guards the call.
+     */
+    resolveModel(context) {
+        const executor = this.pick(context);
+        return executor.resolveModel?.(context) ?? Promise.resolve(undefined);
+    }
+    /**
+     * Whether the step runs on a flat-rate subscription (quota) model, forwarding to
+     * the executor that handles its kind (only the container executor runs subscription
+     * harnesses). Best-effort: an inline kind, an unwired container, or an executor
+     * without the capability all report false (budget-metered, the prior behaviour).
+     */
+    isQuotaBased(context) {
+        if (!this.container)
+            return Promise.resolve(false);
+        const needsContainer = CONTAINER_KINDS.has(context.agentKind) || registeredKindRequiresContainer(context.agentKind);
+        if (!needsContainer)
+            return Promise.resolve(false);
+        return this.container.isQuotaBased?.(context) ?? Promise.resolve(false);
+    }
+    /** Async only for container kinds whose executor actually supports polling. */
+    runsAsync(context) {
+        const executor = this.pick(context);
+        return isAsyncAgentExecutor(executor) && executor.runsAsync(context);
+    }
+    startJob(context) {
+        const executor = this.pick(context);
+        if (!isAsyncAgentExecutor(executor)) {
+            throw new Error(`No async executor for agent kind '${context.agentKind}'`);
+        }
+        return executor.startJob(context);
+    }
+    pollJob(handle) {
+        // Only the container executor runs async jobs, so polls route there.
+        if (!this.container || !isAsyncAgentExecutor(this.container)) {
+            throw new Error('Container executor does not support async jobs');
+        }
+        return this.container.pollJob(handle);
+    }
+    /**
+     * Best-effort container reclaim. The engine narrows the composite (not the inner
+     * container executor) when stopping a run, so the composite must forward stopJob
+     * to the container — otherwise the Layer-2 reclaim silently no-ops and leaks a
+     * warm instance. Delegates only when a container that supports it is wired.
+     */
+    async stopJob(handle) {
+        if (this.container && isAsyncAgentExecutor(this.container) && this.container.stopJob) {
+            await this.container.stopJob(handle);
+        }
+    }
+}
+//# sourceMappingURL=CompositeAgentExecutor.js.map

package/dist/agents/CompositeAgentExecutor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CompositeAgentExecutor.js","sourceRoot":"","sources":["../../src/agents/CompositeAgentExecutor.ts"],"names":[],"mappings":"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"}

package/dist/agents/ContainerAgentExecutor.d.ts

@@ -0,0 +1,235 @@
+import { type AgentJobHandle, type AgentJobUpdate, type AgentRunContext, type AgentRunResult, type AsyncAgentExecutor, type LlmTraceSink, type ModelRef, type SubscriptionVendor } from '@cat-factory/kernel';
+import { type AgentRouting } from '@cat-factory/agents';
+import type { ContainerSessionService } from '../containers/ContainerSessionService.js';
+import { type ResolveRunnerTransport } from './RunnerJobClient.js';
+export type { ResolveRunnerTransport };
+export interface RepoTarget {
+    installationId: number;
+    owner: string;
+    name: string;
+    baseBranch: string;
+    /**
+     * For a service in a monorepo, the subdirectory (relative to the repo root) the
+     * service lives in, e.g. `packages/api`. Present only when the resolved repo is
+     * flagged a monorepo AND the service pins a directory; the harness then runs the
+     * agent within that subtree and tells it so. Absent ⇒ whole-repo behaviour.
+     */
+    serviceDirectory?: string;
+}
+export type ResolveRepoTarget = (workspaceId: string, blockId: string) => Promise<RepoTarget | null>;
+export type MintInstallationToken = (installationId: number) => Promise<string>;
+/**
+ * Ensure the per-task work branch exists on the remote, so every agent in the pipeline
+ * operates on the SAME branch. Returns whether the branch is present afterwards; a
+ * `false`/absent result makes read-only agents fall back to the base branch (writers
+ * create-or-resume the branch in their harness regardless). `options.create` is `true`
+ * for writers (create from base when absent) and `false` for read-only agents (probe
+ * only — never create, since a missing branch means there is nothing yet to read).
+ */
+export type EnsureWorkBranch = (repo: RepoTarget, branch: string, options: {
+    create: boolean;
+}) => Promise<boolean>;
+/** A subscription token leased from the workspace's pool for a vendor. */
+export interface LeasedSubscriptionToken {
+    tokenId: string;
+    secret: string;
+}
+/** Lease the least-loaded subscription token for a vendor, or throw if none. */
+export type LeaseSubscriptionToken = (workspaceId: string, vendor: SubscriptionVendor) => Promise<LeasedSubscriptionToken>;
+/**
+ * Lease the run-initiator's OWN activated personal credential for an individual-usage
+ * vendor (Claude). Scoped to the run + user (not pooled); throws a
+ * `CredentialRequiredError` when the run has no live activation (the user must re-enter
+ * their password). Returns just the raw secret — no token id, since there is no pool
+ * rotation/usage to attribute for a single-user credential.
+ */
+export type LeasePersonalSubscriptionToken = (executionId: string, userId: string, vendor: SubscriptionVendor) => Promise<{
+    secret: string;
+}>;
+/** Fold a finished subscription job's usage into the leased token + telemetry. */
+export type RecordSubscriptionUsage = (workspaceId: string, tokenId: string, usage: {
+    inputTokens: number;
+    outputTokens: number;
+}) => Promise<void>;
+export interface ContainerAgentExecutorDependencies {
+    /** Resolve which runner backend (Cloudflare container or self-hosted pool) a job runs on. */
+    resolveTransport: ResolveRunnerTransport;
+    /** Default model routing; used when the block pins no (usable) model. */
+    agentRouting: AgentRouting;
+    /** Resolve a block's selected model id to a concrete ref (direct flavour). */
+    resolveBlockModel: (modelId: string | undefined) => ModelRef | undefined;
+    /**
+     * Resolve the workspace's per-agent-kind default model id, consulted when the
+     * block pins no model. Optional: absent → the env routing for the kind is used.
+     */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string) => Promise<string | undefined>;
+    /** Resolve which repo (and installation) a run targets. */
+    resolveRepoTarget: ResolveRepoTarget;
+    /**
+     * Resolve a workspace's owning account id, signed into the proxy session token so the
+     * proxy can lease an account-scoped API key from the merged pool. Optional; absent ⇒
+     * only the workspace + initiator scopes are leased.
+     */
+    resolveAccountId?: (workspaceId: string) => Promise<string | null | undefined>;
+    /** Mint a short-lived GitHub installation token for cloning + opening the PR. */
+    mintInstallationToken: MintInstallationToken;
+    /**
+     * Create the shared per-task work branch up front so every agent — including the
+     * read-only design agents — operates on the same branch. Optional: absent (tests, no
+     * GitHub) ⇒ read-only agents clone the base branch, the prior behaviour.
+     */
+    ensureWorkBranch?: EnsureWorkBranch;
+    /** Mints the signed LLM-proxy session token the container uses (Pi harness). */
+    sessionService: ContainerSessionService;
+    /**
+     * Lease a pooled subscription token for a vendor. Required for the Claude Code /
+     * Codex subscription harnesses; absent ⇒ those harnesses are unavailable and a
+     * subscription-only model fails loudly at dispatch.
+     */
+    leaseSubscriptionToken?: LeaseSubscriptionToken;
+    /**
+     * Lease the run-initiator's personal (individual-usage) credential for a vendor like
+     * Claude. Required to run an individual-usage model; absent ⇒ such models fail loudly
+     * at dispatch (the per-user personal store isn't wired on this deployment).
+     */
+    leasePersonalSubscriptionToken?: LeasePersonalSubscriptionToken;
+    /** Attribute a finished subscription job's usage to its leased token (usage-aware rotation). */
+    recordSubscriptionUsage?: RecordSubscriptionUsage;
+    /**
+     * Whether the workspace has a pooled token for a vendor. Drives "subscriptions
+     * always win" for POOLABLE vendors: a step pinned to a dual-mode model (Kimi/DeepSeek
+     * with a Cloudflare base) is auto-routed to its subscription flavour when this returns
+     * true.
+     */
+    hasSubscriptionToken?: (workspaceId: string, vendor: SubscriptionVendor) => Promise<boolean>;
+    /**
+     * Whether the run-initiator has their OWN personal subscription for an INDIVIDUAL-usage
+     * vendor. Individual vendors (e.g. GLM) are never pooled, so a dual-mode individual
+     * model is auto-routed to the user's personal subscription when this returns true, and
+     * otherwise stays on its Cloudflare base — so a subscriber runs GLM on their plan while
+     * a non-subscriber on the same workspace falls back to Cloudflare GLM.
+     */
+    hasPersonalSubscription?: (userId: string, vendor: SubscriptionVendor) => Promise<boolean>;
+    /**
+     * Public base URL of the facade's OpenAI-compatible LLM proxy, including the
+     * `/v1` suffix — Pi posts to `${proxyBaseUrl}/chat/completions`.
+     */
+    proxyBaseUrl: string;
+    /** GitHub REST base for opening the PR (GitHub Enterprise / api.github.com). */
+    githubApiBase?: string;
+    /**
+     * Whether the facade wired a container web-search upstream (the `/v1/web-search`
+     * proxy). When true, coding/ci-fixer jobs are told to point Pi's `web_search` tool
+     * at `${proxyBaseUrl}/web-search` with their session token — so no provider key
+     * reaches the sandbox. Off ⇒ container web search stays disabled.
+     */
+    webSearchProxyEnabled?: boolean;
+    /**
+     * Optional observability trace sink (e.g. Langfuse). When wired, each poll forwards
+     * the container's drained tool spans as child spans under the run's trace — the same
+     * sink the LLM proxy fans generations out to, so the trace tree is complete.
+     * Best-effort and isolated: a sink failure never affects the job lifecycle.
+     */
+    llmTraceSink?: LlmTraceSink;
+}
+/**
+ * An {@link AgentExecutor} that performs implementation work in a real sandbox:
+ * it dispatches a per-run container running the Pi coding agent (a per-run
+ * Cloudflare Container, or an org's self-hosted runner pool), feeds it the block's
+ * composed prompt fragments as context, and has it clone the repo, implement the
+ * block, push a branch and open a PR.
+ *
+ * Secrets never reach the container image. Provider keys stay in the backend; the
+ * container reaches models only through the facade's LLM proxy using a
+ * short-lived, model-locked session token, and clones/pushes with a short-lived
+ * GitHub installation token — both handed over per job. Token usage is metered
+ * by the proxy (the single metering point), so this executor reports no `usage`
+ * to avoid double-counting in the execution engine.
+ */
+export declare class ContainerAgentExecutor implements AsyncAgentExecutor {
+    private readonly deps;
+    /** Shared backend-polymorphic dispatch/poll/release plumbing (see RunnerJobClient). */
+    private readonly jobs;
+    /**
+     * Job ids whose subscription usage has already been folded into the leased token.
+     * `recordSubscriptionUsage` is additive, and the durable driver polls a finished
+     * job inside a retriable step — so a poll that records usage and then throws (or
+     * whose surrounding upsert/emit throws) would replay and double-count, unfairly
+     * penalising the token in the usage-aware rotation. Recording once per job id
+     * guards that. Best-effort + bounded: cleared wholesale past a cap, and it cannot
+     * survive a cold isolate replay — a re-record there is the documented, benign
+     * worst case (one extra job's tokens on one row), never silent over-counting.
+     */
+    private readonly recordedUsageJobs;
+    /** Resolves which model + subscription path a step runs on (routing policy). */
+    private readonly modelRouter;
+    constructor(deps: ContainerAgentExecutorDependencies);
+    /** Repo-operating steps always run as polled async jobs (the coding can be long). */
+    runsAsync(_context: AgentRunContext): boolean;
+    /**
+     * Dispatch the implementation job to this run's container and return a handle.
+     * Returns as soon as the job is accepted — the work continues in the container,
+     * polled via {@link pollJob}. Idempotent: the harness re-attaches to a job
+     * already running for `executionId`, so a replayed dispatch never duplicates work.
+     */
+    startJob(context: AgentRunContext): Promise<AgentJobHandle>;
+    /** Poll a dispatched job for its state, mapping the runner view into an update. */
+    pollJob(handle: AgentJobHandle): Promise<AgentJobUpdate>;
+    /**
+     * Stop a running job and reclaim its backing runner: resolve the same transport
+     * the job dispatched to (by workspace) and `release` it — for the Cloudflare
+     * backend this SIGKILLs the per-run container instead of letting it idle out.
+     * Best-effort/idempotent: a transport without `release`, or an already-gone job,
+     * is a no-op.
+     */
+    stopJob(handle: AgentJobHandle): Promise<void>;
+    /**
+     * Synchronous convenience for non-durable callers (and tests): dispatch then
+     * poll inline until the job finishes. The durable driver does not use this — it
+     * calls {@link startJob}/{@link pollJob} so it can sleep durably between polls.
+     */
+    run(context: AgentRunContext): Promise<AgentRunResult>;
+    /**
+     * Preview the model this job will run, without dispatching the container. The
+     * proxyable-provider guard is deliberately left to `buildJobBody` (the dispatch
+     * path) so an unservable model still fails loudly there; this only names it.
+     */
+    resolveModel(context: AgentRunContext): Promise<string>;
+    /**
+     * Whether this step will run on a flat-rate subscription (quota) model — it
+     * resolves to a Claude Code / Codex harness (a subscription-only model, or a
+     * dual-mode model auto-routed to its subscription flavour because the workspace has
+     * a token). The engine's spend gate consults this so a quota run is not paused by
+     * an exhausted monetary budget it never contributes to. Best-effort: without a
+     * workspace id it reports false.
+     */
+    isQuotaBased(context: AgentRunContext): Promise<boolean>;
+    /**
+     * Per-service provisioning hints for the dispatch: the cloud provider the service
+     * runs on and the abstract instance size resolved to the target's concrete
+     * instance-type id. Cloudflare maps the id to a Container instance type; a
+     * self-hosted pool forwards it (with the provider) and provisions itself. Undefined
+     * when the service pins no provider/size (the transport keeps its default).
+     */
+    private dispatchOptions;
+    /** Validate the ids every container job needs, narrowing them to non-empty strings. */
+    private requireIds;
+    /** Resolve tokens/prompts/target and assemble the harness job body for `context`. */
+    private buildJobBody;
+    /**
+     * Resolve the per-job auth the harness carries: the proxy session token for Pi, or a
+     * leased subscription token for Claude Code / Codex. Spread into every job body
+     * (`common`) so the per-kind bodies can't drift on which auth they forward.
+     */
+    private resolveAuth;
+    /**
+     * Build the per-kind harness job body: the shared `common` fields plus ONLY the delta
+     * specific to this kind's harness endpoint (its prompts, the branch it runs on, and
+     * any per-kind extras), and the matching dispatch `kind`. The web-search fields live
+     * in `webTools` (shared by the kinds that allow web access). The dispatch precedence
+     * matches the original if-ladder exactly: the specific kinds first, then any read-only
+     * kind, then the default coder body.
+     */
+    private buildKindBody;
+}
+//# sourceMappingURL=ContainerAgentExecutor.d.ts.map

package/dist/agents/ContainerAgentExecutor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ContainerAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/ContainerAgentExecutor.ts"],"names":[],"mappings":"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"}