@wardby/cli 0.3.0 → 0.4.1

package/.env.example

@@ -11,6 +11,9 @@ OPENAI_API_KEY=
 # Set LLM_PROVIDER=anthropic to select the Claude adapter (default: openai).
 LLM_PROVIDER=openai
 ANTHROPIC_API_KEY=
+# How often (seconds) each process re-reads the model catalog from the database,
+# so another process's set_model/disable_model/reset_model reaches it (docs/models.md).
+# WARDBY_MODEL_CATALOG_REFRESH_SECONDS=45
 
 # Phase 4: MCP server (`wardby mcp`). stdio is the local/no-OAuth default.
 MCP_TRANSPORT=stdio
@@ -34,9 +37,9 @@ AUTH_ISSUER=
 AUTH_JWKS_URI=
 AUTH_AUDIENCE=
 # Optional, delegating mode: wardby roles from a signed access-token claim.
-# Privileged scopes (agents:admin, packages:approve, services:manage) are honoured only for a
-# role granting them (admin: all three; package-approver: packages:approve;
-# service-manager: services:manage). Set
+# Privileged scopes (agents:admin, packages:approve, services:manage, admin:view, models:admin)
+# are honoured only for a role granting them (admin: all five; package-approver: packages:approve;
+# service-manager: services:manage; model-manager: models:admin). Set
 # both, or neither (then nobody has a role). The claim is an exact top-level
 # name first (e.g. groups, roles, or a namespaced https://… claim), else a
 # dotted path (e.g. realm_access.roles). The map is idpValue=wardbyRole pairs,
@@ -140,6 +143,22 @@ GITHUB_APP_WEBHOOK_SECRET=
 GITHUB_APP_CLIENT_ID=
 GITHUB_APP_CLIENT_SECRET=
 
+# --- Jira Cloud (optional; see docs/jira-agents.md) ---
+# wardby acts in Jira as an Atlassian service account, never a person's account:
+# every comment and change an agent makes is attributed to this account.
+# The site people browse (bare origin). Issue links in comments point here.
+WARDBY_JIRA_SITE_URL=
+# The service account's API token and the Atlassian API gateway for your site.
+WARDBY_JIRA_API_TOKEN=
+WARDBY_JIRA_API_BASE_URL=https://api.atlassian.com/ex/jira/<cloudId>
+# Optional: the token's expiry date (YYYY-MM-DD); wardby warns 14 days ahead.
+WARDBY_JIRA_API_TOKEN_EXPIRES_AT=
+# Optional: field id of the legacy Epic Link field (company-managed projects), so
+# cost reports group runs under their epic, e.g. customfield_10014.
+# WARDBY_JIRA_EPIC_LINK_FIELD=
+# The secret you set on the Jira webhook (20+ characters).
+WARDBY_JIRA_WEBHOOK_SECRET=
+
 # EXECUTOR=in-process (default): heartbeat + reconciler durability; a run whose
 # process dies is reconciled to `lost`. EXECUTOR=dbos: each run is a DBOS
 # durable workflow that resumes from its last completed LLM turn / tool call

package/README.md

@@ -225,14 +225,14 @@ These are example systems a team can build and manage through MCP:
 **Builders can vary. The controls do not.** Each system inherits the same
 budget, capability, identity, evidence, and review contract.
 
-| Agent system             | Typical cycle                                                      | Governed outcome                     |
-| ------------------------ | ------------------------------------------------------------------ | ------------------------------------ |
-| **Delivery pipeline**    | Work request → plan → implementation → tests → review              | Optional draft feature or bug-fix PR |
-| **Security maintenance** | Scheduled scan → assess → patch → verify                           | Report or optional remediation PR    |
-| **Architecture review**  | Inspect codebase → score risks → prioritize findings               | Architecture and risk report         |
-| **QA coverage**          | Map journeys → rank gaps → add tests → run suite                   | Coverage report or optional test PR  |
-| **System monitoring**    | Receive signal → investigate → correlate → escalate                | Actionable defect or incident report |
-| **Project tracking**     | Read delivery data → compare plan, cost, and progress → flag drift | Portfolio or program update          |
+| Agent system                                                                     | Typical cycle                                                      | Governed outcome                     |
+| -------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------ |
+| **[Delivery pipeline](docs/agent-recipes.md#recipe-b-a-builder-per-language)**   | Work request → plan → implementation → tests → review              | Optional draft feature or bug-fix PR |
+| **Security maintenance**                                                         | Scheduled scan → assess → patch → verify                           | Report or optional remediation PR    |
+| **[Architecture review](docs/agent-recipes.md#recipe-a-an-architecture-keeper)** | Inspect codebase → score risks → prioritize findings               | Architecture and risk report         |
+| **QA coverage**                                                                  | Map journeys → rank gaps → add tests → run suite                   | Coverage report or optional test PR  |
+| **System monitoring**                                                            | Receive signal → investigate → correlate → escalate                | Actionable defect or incident report |
+| **Project tracking**                                                             | Read delivery data → compare plan, cost, and progress → flag drift | Portfolio or program update          |
 
 Agents can stand alone or be connected as bounded sub-agents. Shared budget
 groups can cap the combined spend of an ecosystem, while each agent retains its
@@ -364,7 +364,9 @@ for the repository's own dependency-override policy.
 - MCP-first agent, tool, schedule, budget-group, secret, datastore, webhook,
   run, and sub-agent management.
 - Scheduled and event-triggered native agents with OpenAI, direct Anthropic,
-  and Bedrock-Claude model routing.
+  and Bedrock-Claude model routing, priced and routed from an admin-editable
+  model catalog (`list_models`, `get_model`, `set_model`, `disable_model`,
+  `reset_model`).
 - Per-run budgets, shared budget groups, usage accounting, and cancellation.
 - QuickJS tool isolation with host allowlists and secret bindings.
 - Containerized Codex and Claude Code executors with trusted GitHub draft-PR

package/dist/cli-help.d.ts

@@ -1 +1 @@
-export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute)\n  wardby agent list\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";
+export declare const CLI_USAGE = "usage:\n  wardby quickstart [--provider openai|anthropic] [--model <m>] [--budget <usd>] [--client none|codex|claude|both] [--skip-demo] [--non-interactive --yes]\n  wardby doctor\n  wardby status\n  wardby logs [--tail N] [--follow]\n  wardby down [--volumes]\n  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)\n  wardby help [list]\n  wardby help search <terms>\n  wardby help open <article-id>\n  wardby agent create --name <n> --model <m> --prompt <p> --budget <usd> [--schedule \"<cron>\"] [--timezone <tz>] [--max-turns <n>] [--owner <subject>] [--public]\n      (owned by --owner or LOCAL_PRINCIPAL; --public shares it with everyone at execute)\n  wardby agent list\n  wardby agent schedule <name> --cron \"<expr>\" [--timezone <tz>] [--disable]\n  wardby tool create --name <n> --description <d> --params <file> --code <file>\n  wardby tool attach <tool-name|tool-id> <agent-name>   (grants the capabilities in the agent owner's name)\n  wardby tool detach <tool-name|tool-id> <agent-name>\n  wardby tool update <tool-name|tool-id> [--description <d>] [--params <file>] [--code <file>]\n  wardby tool delete <tool-name|tool-id> [--detach]\n  wardby tool list [--agent <name>]\n  wardby run <name>\n  wardby runs [--agent <name>] [--limit N] [--status <s>]\n  wardby coding preflight   (JOB_LAUNCHER=docker or kubernetes)\n  wardby coding cleanup --run-id <id>\n  wardby scheduler [--scope default]\n  wardby mcp   (MCP_TRANSPORT=stdio|http selects the transport)\n  wardby serve [--scope default]   (mcp + scheduler + reconciler in one process; http only)\n  wardby grants migration-report [--json]\n  wardby grants adopt-public --owner <subject> [--dry-run] [--keep-everyone-execute]\n  wardby grants prune-bindings [--dry-run]\n  wardby import <bundle-dir> [--owner <subject>] [--public] [--include-secrets --transfer-key <pem>] [--default-budget <usd>] [--dry-run] [--prefix <p>] [--on-conflict fail|skip|rename] [--allow-open-fetch]\n\noptions:\n  -h, --help       Show this help\n  -v, --version    Show the installed Wardby version";

package/dist/cli-help.js

@@ -4,6 +4,7 @@ export const CLI_USAGE = `usage:
   wardby status
   wardby logs [--tail N] [--follow]
   wardby down [--volumes]
+  wardby knowledge check [dir] [--root <dir>] [--strict] [--json]   Validate a knowledge bundle (offline)
   wardby help [list]
   wardby help search <terms>
   wardby help open <article-id>

package/dist/cli.js

@@ -26,6 +26,7 @@ import { isImmutableDockerImage } from "./providers/jobs/docker-isolation.js";
 import { ClientNodeKubernetesApi } from "./providers/jobs/kubernetes-client.js";
 import { describePreflightFailure, kubernetesPreflight } from "./providers/jobs/kubernetes-preflight.js";
 import { RoutingLlmProvider, isLlmEffort, modelSupportedEfforts, resolveLlmRegistrations, } from "./providers/llm/index.js";
+import { startModelCatalog } from "./providers/llm/catalog-store.js";
 import { buildConfiguredExecutor, buildExecutor } from "./providers/executor/index.js";
 import { PostgresDatastore } from "./providers/datastore/index.js";
 import { PostgresAgentMemory } from "./providers/memory/index.js";
@@ -33,9 +34,11 @@ import { buildSecretCipher } from "./providers/secrets/index.js";
 import { prisma } from "./core/db.js";
 import { runAgent } from "./core/runner.js";
 import { cancelRunOnSignal } from "./core/run-heartbeat.js";
+import { buildIssueTrackers } from "./providers/issue-tracker/index.js";
 import { buildReviewHosts } from "./providers/review-host/index.js";
 import { createRepoAccessGate } from "./core/repo-access.js";
 import { validateCronExpression } from "./core/cron.js";
+import { assertAgentModelAvailable } from "./core/run-pricing.js";
 import { startScheduler } from "./core/scheduler.js";
 import { startReconciler } from "./core/reconciler.js";
 import { NativeEngine } from "./core/engine-native.js";
@@ -140,6 +143,22 @@ async function agentCreate(args) {
             fail(`invalid --schedule/--timezone: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // Started before validating the model so an admin override recorded in
+    // ModelCatalogEntry (a disabled model, a narrowed effort list) is
+    // respected here too, not just at run time.
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    try {
+        assertAgentModelAvailable(values.model);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     if (values.effort !== undefined) {
         const accepted = modelSupportedEfforts(values.model);
         if (!isLlmEffort(values.effort) || !accepted.includes(values.effort)) {
@@ -147,6 +166,7 @@ async function agentCreate(args) {
                 (accepted.length > 0 ? ` (accepted: ${accepted.join(", ")}).` : " (it accepts no effort setting)."));
         }
     }
+    modelCatalog.close();
     // Owned by --owner or the local operator; never owner-less (resource-
     // sharing grants spec §3.8). --public shares it with everyone at execute.
     let ownerId;
@@ -510,6 +530,13 @@ async function run(name) {
     if (agent.kind === "coding") {
         fail("Coding agents are MCP-first: use trigger_agent so task input and ownership are recorded safely.");
     }
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     const llm = buildLlmProvider();
     const engine = buildEngine();
     const secrets = buildSecrets();
@@ -520,7 +547,7 @@ async function run(name) {
     // `running` row behind.
     let removeSignalHandlers;
     try {
-        run = await runAgent(name, { llm, engine, datastore, secrets, memory, reviewHosts: buildReviewHosts() }, prisma, (delta) => {
+        run = await runAgent(name, { llm, engine, datastore, secrets, memory, reviewHosts: buildReviewHosts(), issueTrackers: buildIssueTrackers() }, prisma, (delta) => {
             process.stdout.write(delta);
         }, (created) => {
             removeSignalHandlers = cancelRunOnSignal(prisma, created.id);
@@ -531,6 +558,7 @@ async function run(name) {
     }
     finally {
         removeSignalHandlers?.();
+        modelCatalog.close();
     }
     process.stdout.write("\n");
     const completedAgent = await prisma.agent.findUnique({ where: { id: run.agentId } });
@@ -657,6 +685,13 @@ async function scheduler(args) {
     // Parsed before anything starts, so a malformed CODING_MAX_CONCURRENT or
     // CODING_QUEUE_TIMEOUT_SEC fails fast.
     const concurrency = loadCodingConcurrencyConfig();
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
     const config = loadProviderConfig();
     const llm = buildLlmProvider();
     const engine = buildEngine();
@@ -664,18 +699,21 @@ async function scheduler(args) {
     const datastore = buildDatastore(secrets);
     const memory = buildMemory();
     const reviewHosts = buildReviewHosts();
+    const issueTrackers = buildIssueTrackers();
     // One repository-access gate (and cache) for native repo_* calls and coding runs.
     const repoAccess = createRepoAccessGate({ db: prisma, hosts: reviewHosts });
-    const nativeExecutor = buildExecutor(config, { llm, engine, datastore, secrets, memory, reviewHosts, repoAccess }, prisma);
+    const nativeExecutor = buildExecutor(config, { llm, engine, datastore, secrets, memory, reviewHosts, issueTrackers, repoAccess }, prisma);
     const executor = buildConfiguredExecutor({ native: nativeExecutor, db: prisma, providerConfig: config, repoAccess });
     await executor.launch?.();
-    const reconciler = startReconciler({ db: prisma, executor, reviewHosts });
+    const reconciler = startReconciler({ db: prisma, executor, reviewHosts, issueTrackers });
+    const selfDefects = { db: prisma, issueTrackers };
     const sched = startScheduler({
         executor,
         db: prisma,
         scope,
+        selfDefects,
         onLeaderTick: async () => {
-            await drainCodingQueue({ db: prisma, executor, ...concurrency });
+            await drainCodingQueue({ db: prisma, executor, ...concurrency, selfDefects });
         },
     });
     console.log(`wardby scheduler started (scope "${scope}"). Press Ctrl+C to stop.`);
@@ -686,7 +724,10 @@ async function scheduler(args) {
             reconciler.stop();
             void Promise.resolve(executor.close?.())
                 .catch((err) => cliLog.warn({ err }, "executor close failed during scheduler shutdown"))
-                .finally(resolve);
+                .finally(() => {
+                modelCatalog.close();
+                resolve();
+            });
         };
         process.once("SIGINT", shutdown);
         process.once("SIGTERM", shutdown);
@@ -734,11 +775,28 @@ async function serve(args) {
 }
 async function importCommand(rest) {
     const opts = parseImportArgs(rest);
-    const { report, result } = await runImport({ ...opts, db: prisma, env: process.env });
-    console.log(report);
-    if (result) {
-        for (const w of result.webhookSecrets)
-            console.log(`webhook secret (${w.agentName}): ${w.secret}`);
+    // runImport builds an LLM provider and classifies each agent's model as
+    // routable/unroutable from currentModelCatalog() — without a store
+    // started here first, that falls back to the shipped catalog, so an
+    // admin-disabled model would be (wrongly) imported as routable and a
+    // DB-only custom model would be (wrongly) imported as disabled.
+    let modelCatalog;
+    try {
+        modelCatalog = await startModelCatalog(prisma);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+    }
+    try {
+        const { report, result } = await runImport({ ...opts, db: prisma, env: process.env });
+        console.log(report);
+        if (result) {
+            for (const w of result.webhookSecrets)
+                console.log(`webhook secret (${w.agentName}): ${w.secret}`);
+        }
+    }
+    finally {
+        modelCatalog.close();
     }
 }
 async function main() {

package/dist/coding/base-commit.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The coding workspace has no git metadata, so the worker cannot learn which
+ * commit it is looking at. The executor appends it to the task when it writes
+ * the worker input (after cloning). Never grows a task past the limit.
+ */
+export declare function withBaseCommit(task: string, baseCommit: string): string;

package/dist/coding/base-commit.js

@@ -0,0 +1,12 @@
+import { byteLength, MAX_CODING_TASK_BYTES } from "./protocol.js";
+/**
+ * The coding workspace has no git metadata, so the worker cannot learn which
+ * commit it is looking at. The executor appends it to the task when it writes
+ * the worker input (after cloning). Never grows a task past the limit.
+ */
+export function withBaseCommit(task, baseCommit) {
+    if (!/^[0-9a-f]{40}$/.test(baseCommit))
+        return task;
+    const withLine = `${task}\n\nBase commit: ${baseCommit} (the commit this workspace was checked out at; the workspace has no git metadata).`;
+    return byteLength(withLine) <= MAX_CODING_TASK_BYTES ? withLine : task;
+}

package/dist/coding/protocol.d.ts

@@ -1,7 +1,11 @@
 import { z } from "zod";
 export declare const CODING_PROTOCOL_VERSION: 1;
+/** The code host every coding run's repository and pull request live on (see pullRequestUrlSchema); the one place to change when another is added. */
+export declare const CODING_CODE_PROVIDER = "github";
 export declare const MAX_CODING_ARTIFACT_BYTES: number;
 export declare const MAX_CODING_TASK_BYTES: number;
+/** Room reserved at the end of a composed task for lines the executor appends (e.g. the base commit). */
+export declare const CODING_TASK_TRAILER_RESERVE_BYTES = 256;
 export declare const MAX_CODING_SUMMARY_BYTES: number;
 export declare const MAX_CODING_TESTS = 64;
 export declare const MAX_CODING_TEST_COMMAND_BYTES: number;
@@ -35,6 +39,15 @@ export declare function normalizeGitHubRepository(value: string): string;
 export declare function normalizeGitRef(value: string): string;
 export declare const CodingBaseRefSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
 export declare const CodingTaskOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>, string, string>;
+/**
+ * A section rendered to fit whatever room the task leaves (the knowledge note:
+ * src/knowledge/note.ts). Declared structurally so this module, which coding
+ * workers ship as a single file, imports nothing new.
+ */
+export interface FittedSection {
+    /** The section text within `maxBytes`, or undefined when it does not fit. */
+    render(maxBytes: number): string | undefined;
+}
 /**
  * A coding worker receives only its task text, so a coding agent's own
  * instructions (its systemPrompt) travel inside that text, ahead of the
@@ -42,8 +55,11 @@ export declare const CodingTaskOverrideSchema: z.ZodEffects<z.ZodEffects<z.ZodEf
  * started: src/coding/services/note.ts). Blank instructions and no note leave
  * the task unchanged. The combination must still fit MAX_CODING_TASK_BYTES;
  * exceeding it is an error naming both parts rather than a silent truncation.
+ * A knowledge note, when given, goes between the standing instructions and the
+ * request and is fitted into whatever room is left: it is cut, or dropped,
+ * never the cause of an error.
  */
-export declare function composeCodingTask(instructions: string | null | undefined, task: string, note?: string): string;
+export declare function composeCodingTask(instructions: string | null | undefined, task: string, note?: string, knowledge?: FittedSection): string;
 /**
  * The tag only labels a pull request title, so a model's malformed tag must not
  * sink an otherwise finished run. A tag that already passes is kept as-is; any

package/dist/coding/protocol.js

@@ -1,7 +1,11 @@
 import { z } from "zod";
 export const CODING_PROTOCOL_VERSION = 1;
+/** The code host every coding run's repository and pull request live on (see pullRequestUrlSchema); the one place to change when another is added. */
+export const CODING_CODE_PROVIDER = "github";
 export const MAX_CODING_ARTIFACT_BYTES = 64 * 1024;
 export const MAX_CODING_TASK_BYTES = 16 * 1024;
+/** Room reserved at the end of a composed task for lines the executor appends (e.g. the base commit). */
+export const CODING_TASK_TRAILER_RESERVE_BYTES = 256;
 export const MAX_CODING_SUMMARY_BYTES = 8 * 1024;
 export const MAX_CODING_TESTS = 64;
 export const MAX_CODING_TEST_COMMAND_BYTES = 2 * 1024;
@@ -201,17 +205,24 @@ export const CodingTaskOverrideSchema = boundedText(MAX_CODING_TASK_BYTES);
  * started: src/coding/services/note.ts). Blank instructions and no note leave
  * the task unchanged. The combination must still fit MAX_CODING_TASK_BYTES;
  * exceeding it is an error naming both parts rather than a silent truncation.
+ * A knowledge note, when given, goes between the standing instructions and the
+ * request and is fitted into whatever room is left: it is cut, or dropped,
+ * never the cause of an error.
  */
-export function composeCodingTask(instructions, task, note) {
+export function composeCodingTask(instructions, task, note, knowledge) {
     const standing = [instructions?.trim(), note?.trim()].filter((part) => Boolean(part)).join("\n\n");
-    if (!standing)
-        return task;
-    const composed = `Standing instructions for this coding agent:\n${standing}\n\nRequest:\n${task}`;
-    if (byteLength(composed) > MAX_CODING_TASK_BYTES) {
+    const base = standing ? `Standing instructions for this coding agent:\n${standing}\n\nRequest:\n${task}` : task;
+    if (byteLength(base) > MAX_CODING_TASK_BYTES) {
         throw new Error(`The coding agent's instructions (${byteLength(standing)} bytes) plus this task (${byteLength(task)} bytes) ` +
             `exceed the ${MAX_CODING_TASK_BYTES}-byte coding task limit; shorten one of them.`);
     }
-    return composed;
+    if (!knowledge)
+        return base;
+    const prefix = standing ? `Standing instructions for this coding agent:\n${standing}\n\n` : "";
+    const suffix = `\n\nRequest:\n${task}`;
+    const room = MAX_CODING_TASK_BYTES - byteLength(prefix) - byteLength(suffix) - CODING_TASK_TRAILER_RESERVE_BYTES;
+    const rendered = room > 0 ? knowledge.render(room) : undefined;
+    return rendered ? `${prefix}${rendered}${suffix}` : base;
 }
 const runIdSchema = boundedText(MAX_RUN_ID_BYTES, true).refine((value) => /^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value), "must be an opaque identifier");
 const modelSchema = boundedText(MAX_MODEL_BYTES, true).refine((value) => /^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(value), "must be a model identifier");

package/dist/coding/provider.d.ts

@@ -1,4 +1,9 @@
+import type { ModelCatalog } from "../providers/llm/catalog.js";
+import type { ModelProvider } from "../providers/llm/catalog-types.js";
 export declare const CODING_PROVIDERS: readonly ["codex", "claude-code"];
 export type CodingProvider = (typeof CODING_PROVIDERS)[number];
-export declare function codingProviderSupportsModel(provider: CodingProvider, model: string): boolean;
+/** Which coding provider runs a model provider's models; Bedrock models are never coding models. */
+export declare function codingProviderForModelProvider(provider: ModelProvider): CodingProvider | undefined;
+export declare function codingProviderSupportsModel(provider: CodingProvider, model: string, catalog?: ModelCatalog): boolean;
+export declare function assertCodingProvider(provider: string): asserts provider is CodingProvider;
 export declare function assertCodingProviderModel(provider: string, model: string): asserts provider is CodingProvider;

package/dist/coding/provider.js

@@ -1,17 +1,24 @@
-import { anthropicSupportedModels } from "../providers/llm/pricing-anthropic.js";
-import { supportedModels as openaiSupportedModels } from "../providers/llm/pricing.js";
+import { currentModelCatalog } from "../providers/llm/catalog-store.js";
 export const CODING_PROVIDERS = ["codex", "claude-code"];
-const MODELS_BY_PROVIDER = {
-    codex: new Set(openaiSupportedModels()),
-    "claude-code": new Set(anthropicSupportedModels()),
-};
-export function codingProviderSupportsModel(provider, model) {
-    return MODELS_BY_PROVIDER[provider].has(model);
+/** Which coding provider runs a model provider's models; Bedrock models are never coding models. */
+export function codingProviderForModelProvider(provider) {
+    if (provider === "openai")
+        return "codex";
+    if (provider === "anthropic")
+        return "claude-code";
+    return undefined;
 }
-export function assertCodingProviderModel(provider, model) {
+export function codingProviderSupportsModel(provider, model, catalog = currentModelCatalog()) {
+    const entry = catalog.get(model);
+    return entry !== undefined && codingProviderForModelProvider(entry.provider) === provider;
+}
+export function assertCodingProvider(provider) {
     if (!CODING_PROVIDERS.includes(provider)) {
         throw new Error(`Unsupported coding provider "${provider}".`);
     }
+}
+export function assertCodingProviderModel(provider, model) {
+    assertCodingProvider(provider);
     if (!codingProviderSupportsModel(provider, model)) {
         throw new Error(`Model "${model}" is not supported by coding provider "${provider}".`);
     }

package/dist/config/providers.d.ts

@@ -52,6 +52,31 @@ export declare function loadGitHubUserAuthConfig(env?: NodeJS.ProcessEnv): {
     clientId?: string;
     clientSecret?: string;
 };
+export interface JiraConfig {
+    /** The site people browse, e.g. https://your-site.atlassian.net — used for issue links. A bare https origin. */
+    siteUrl: string;
+    /** Where REST calls go: always https://api.atlassian.com/ex/jira/<cloudId>, the only base a service-account token works against. */
+    apiBaseUrl: string;
+    /** A service account's API token, sent as a Bearer token. Personal (Basic email:token) auth is not supported. */
+    auth: {
+        kind: "bearer";
+        token: string;
+    };
+    webhookSecret: string;
+    /** Optional, for expiry warnings; Atlassian API tokens last at most a year. */
+    tokenExpiresAt?: Date;
+    /** Company-managed sites still on the legacy Epic Link field: its id (customfield_N). Optional. */
+    epicLinkField?: string;
+}
+/**
+ * Jira Cloud issue-tracker settings (docs/jira-agents.md). Unset = Jira is
+ * disabled. wardby acts in Jira only as an Atlassian service account, so
+ * everything an agent does is attributed to that account: the token is sent
+ * as a Bearer token and REST calls go through the api.atlassian.com gateway
+ * (WARDBY_JIRA_API_BASE_URL, required). Personal tokens (Basic email:token)
+ * are rejected.
+ */
+export declare function loadJiraConfig(env?: NodeJS.ProcessEnv): JiraConfig | null;
 export interface ContainerExecutorConfig {
     workerImage?: string;
     claudeWorkerImage?: string;

package/dist/config/providers.js

@@ -64,6 +64,77 @@ export function loadGitHubUserAuthConfig(env = process.env) {
     }
     return { clientId, clientSecret };
 }
+const JIRA_GATEWAY = /^https:\/\/api\.atlassian\.com\/ex\/jira\/[0-9a-f-]{36}$/i;
+function httpsOrigin(value, name) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${name} is not a valid URL.`);
+    }
+    if (url.protocol !== "https:")
+        throw new Error(`${name} must be an https URL.`);
+    return value.replace(/\/+$/, "");
+}
+/**
+ * Jira Cloud issue-tracker settings (docs/jira-agents.md). Unset = Jira is
+ * disabled. wardby acts in Jira only as an Atlassian service account, so
+ * everything an agent does is attributed to that account: the token is sent
+ * as a Bearer token and REST calls go through the api.atlassian.com gateway
+ * (WARDBY_JIRA_API_BASE_URL, required). Personal tokens (Basic email:token)
+ * are rejected.
+ */
+export function loadJiraConfig(env = process.env) {
+    const site = env.WARDBY_JIRA_SITE_URL?.trim();
+    const token = env.WARDBY_JIRA_API_TOKEN?.trim();
+    const secret = env.WARDBY_JIRA_WEBHOOK_SECRET?.trim();
+    const base = env.WARDBY_JIRA_API_BASE_URL?.trim();
+    const expires = env.WARDBY_JIRA_API_TOKEN_EXPIRES_AT?.trim() || undefined;
+    if (env.WARDBY_JIRA_API_EMAIL?.trim()) {
+        throw new Error("WARDBY_JIRA_API_EMAIL is no longer supported: personal (Basic email:token) Jira tokens are not accepted. " +
+            "Use an Atlassian service account's API token with WARDBY_JIRA_API_BASE_URL=https://api.atlassian.com/ex/jira/<cloudId>.");
+    }
+    if (!site && !token && !secret && !base)
+        return null;
+    if (!site || !token || !secret || !base) {
+        throw new Error("Set WARDBY_JIRA_SITE_URL, WARDBY_JIRA_API_BASE_URL, WARDBY_JIRA_API_TOKEN and WARDBY_JIRA_WEBHOOK_SECRET together, or none of them.");
+    }
+    if (secret.length < 20)
+        throw new Error("WARDBY_JIRA_WEBHOOK_SECRET must be at least 20 characters.");
+    const siteUrl = httpsOrigin(site, "WARDBY_JIRA_SITE_URL");
+    const siteParsed = new URL(siteUrl);
+    if (siteParsed.pathname !== "/" ||
+        siteParsed.search ||
+        siteParsed.hash ||
+        siteParsed.username ||
+        siteParsed.password) {
+        throw new Error("WARDBY_JIRA_SITE_URL must be a bare https origin such as https://your-site.atlassian.net.");
+    }
+    const apiBaseUrl = httpsOrigin(base, "WARDBY_JIRA_API_BASE_URL");
+    if (!JIRA_GATEWAY.test(apiBaseUrl)) {
+        throw new Error("WARDBY_JIRA_API_BASE_URL must be https://api.atlassian.com/ex/jira/<cloudId>, the only base a service " +
+            "account's API token works against.");
+    }
+    let tokenExpiresAt;
+    if (expires) {
+        tokenExpiresAt = new Date(expires);
+        if (Number.isNaN(tokenExpiresAt.getTime()))
+            throw new Error("WARDBY_JIRA_API_TOKEN_EXPIRES_AT must be an ISO date.");
+    }
+    const epicLinkField = env.WARDBY_JIRA_EPIC_LINK_FIELD?.trim() || undefined;
+    if (epicLinkField && !/^customfield_\d+$/.test(epicLinkField)) {
+        throw new Error("WARDBY_JIRA_EPIC_LINK_FIELD must be a custom field id such as customfield_10014.");
+    }
+    return {
+        siteUrl,
+        apiBaseUrl,
+        auth: { kind: "bearer", token },
+        webhookSecret: secret,
+        ...(tokenExpiresAt ? { tokenExpiresAt } : {}),
+        ...(epicLinkField ? { epicLinkField } : {}),
+    };
+}
 function optionalPositiveNumber(value, name, fallback) {
     if (value === undefined)
         return fallback;

package/dist/core/attribution.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Cost attribution (docs/private/2026-10-01-issue-cost-attribution-design.md):
+ * every run in an issue-related run tree points at one WorkItem, with the
+ * item's parent frozen as of dispatch. Attribution comes from control-plane
+ * data only (the event, a stored PR link, a validated explicit key, or the
+ * parent run), never from model output. A snapshot is a network call, so it
+ * is taken before dispatch's persist transaction and never fails a dispatch.
+ */
+import type { Prisma, PrismaClient } from "#prisma";
+import { type IssueSnapshot, type IssueTrackerProvider, type IssueTrackerRegistry } from "../providers/issue-tracker/types.js";
+export type AttributionSource = "issue_event" | "linked_pr" | "explicit";
+/** Resolved before the persist transaction; never contains a network call. */
+export interface ResolvedWorkItem {
+    provider: string;
+    key: string;
+    scopeKey: string;
+    /** null = key-only (snapshot failed or no tracker); then existing WorkItem fields are kept. */
+    snapshot: IssueSnapshot | null;
+}
+export interface AttributionIntent {
+    source: AttributionSource;
+    item: ResolvedWorkItem;
+}
+/** A WorkItem snapshotted this recently is reused as-is, without calling the tracker. */
+export declare const SNAPSHOT_CACHE_MS: number;
+export declare const SNAPSHOT_TIMEOUT_MS = 3000;
+/**
+ * Snapshot budget for a caller that is answering a request (a webhook, an
+ * MCP tool call, a host event): a short timeout and no 429 retry, so a slow
+ * or rate-limited tracker degrades to key-only attribution instead of
+ * stalling the response.
+ */
+export declare const RESPONSE_PATH_SNAPSHOT_BUDGET: {
+    readonly timeoutMs: 2000;
+    readonly retryOn429: false;
+};
+/**
+ * The work item a new attribution points at, snapshotted from the tracker
+ * unless a fresh snapshot is already stored. Never throws: a failed lookup or
+ * snapshot attributes by key only.
+ */
+export declare function resolveWorkItem(db: Pick<PrismaClient, "workItem">, trackers: IssueTrackerRegistry | undefined, provider: string, key: string, opts?: {
+    timeoutMs?: number;
+    retryOn429?: boolean;
+    now?: Date;
+}): Promise<ResolvedWorkItem>;
+export type AttributionTx = Pick<Prisma.TransactionClient, "workItem" | "runAttribution" | "codingRun" | "runIssueStatus">;
+/**
+ * Writes the run's attribution inside dispatch's persist transaction.
+ * Precedence: the parent run's attribution, then the continued coding run's,
+ * then a pre-attribution issue (legacyIssue), then the caller's intent. Returns the item's provider/key (for
+ * CodingRun.issueProvider/issueKey), or null when the run is unattributed.
+ */
+export declare function attributeRun(tx: AttributionTx, runId: string, from: {
+    parentRunId?: string;
+    continuesCodingRunId?: string;
+    intent?: AttributionIntent;
+}, now?: Date): Promise<{
+    provider: string;
+    key: string;
+} | null>;
+/** The issue a pull request was opened for (phase-3 IssuePullRequest); the earliest link when several exist. */
+export declare function linkedPullRequestIssue(db: Pick<PrismaClient, "issuePullRequest">, pr: {
+    codeProvider: string;
+    repository: string;
+    number: number;
+}): Promise<{
+    provider: string;
+    key: string;
+} | null>;
+/** Attribution for a run on a pull request that was opened for an issue; undefined when it has none. */
+export declare function linkedPullRequestAttribution(db: Pick<PrismaClient, "issuePullRequest" | "workItem">, trackers: IssueTrackerRegistry | undefined, pr: {
+    codeProvider: string;
+    repository: string;
+    number: number;
+}, opts?: {
+    timeoutMs?: number;
+    retryOn429?: boolean;
+}): Promise<AttributionIntent | undefined>;
+/** A refusal whose message is safe to return to the caller. */
+export declare class AttributionError extends Error {
+    constructor(message: string);
+}
+/**
+ * An issue a caller names on trigger_agent or a webhook. It decides whose
+ * cost this run counts toward, so it must be well formed and in a project the
+ * agent is linked to (AgentIssueProject) — otherwise the dispatch is refused.
+ * Issue keys are uppercase, so a key that differs only by case or surrounding
+ * spaces ("pay-241") is corrected rather than refused. `field` is the caller's
+ * name for the value (trigger_agent: issue; webhooks: wardbyIssue), so
+ * refusals name the field the caller actually sent.
+ */
+export declare function validateExplicitIssue(db: Pick<PrismaClient, "agentIssueProject">, agentId: string, issue: unknown, field?: string): Promise<{
+    provider: IssueTrackerProvider;
+    key: string;
+}>;
+export declare function explicitAttribution(db: Pick<PrismaClient, "agentIssueProject" | "workItem">, trackers: IssueTrackerRegistry | undefined, agentId: string, issue: unknown, opts?: {
+    timeoutMs?: number;
+    retryOn429?: boolean;
+    field?: string;
+}): Promise<AttributionIntent>;