@cat-factory/agents 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/AiAgentExecutor.d.ts

@@ -0,0 +1,72 @@
+import type { AgentExecutor, AgentRunContext, AgentRunResult } from '@cat-factory/kernel';
+import type { ModelProvider, ModelProviderResolver, ModelRef } from '@cat-factory/kernel';
+import { type AgentRouting } from './agent-routing.js';
+import { type InlineWebSearchOptions } from './web-search.js';
+export interface AiAgentExecutorDependencies {
+    /**
+     * Resolve a {@link ModelProvider} for a run's credential scope (workspace + owning
+     * account + initiator), leasing the DB-backed API keys for that scope. Preferred over
+     * the static `modelProvider`; the facades supply it so inline calls use the same
+     * per-scope pool the container proxy does.
+     */
+    modelProviderResolver?: ModelProviderResolver;
+    /**
+     * A static {@link ModelProvider} (e.g. a fake in tests). Used only when no
+     * `modelProviderResolver` is supplied. One of the two MUST be present.
+     */
+    modelProvider?: ModelProvider;
+    agentRouting: AgentRouting;
+    /**
+     * Resolve a block's selected model id to a concrete ref. Deployment-aware (it
+     * honours the direct/Cloudflare fallback based on configured keys), so the
+     * worker supplies it; absent/unknown ids return undefined to fall back to the
+     * agent routing. Defaults to "no per-block override".
+     */
+    resolveBlockModel?: (modelId: string | undefined) => ModelRef | undefined;
+    /**
+     * Resolve the workspace's per-agent-kind default model id, consulted when the
+     * block pins no usable model. Optional: absent → the env routing for the kind is
+     * used. Supplying it makes the inline kinds honour the workspace defaults exactly
+     * like the container executor (block-pinned > workspace default > env routing).
+     */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string) => Promise<string | undefined>;
+    /**
+     * Opt-in provider-hosted web search for the design/research inline kinds. When
+     * supplied (and the resolved model's provider has a hosted search — Anthropic /
+     * OpenAI), the allow-listed kinds get a `web_search` tool plus a usage nudge.
+     * Absent ⇒ inline agents make a plain one-shot completion, exactly as before.
+     */
+    webSearch?: InlineWebSearchOptions;
+}
+/**
+ * The real agent: performs each pipeline step by calling an LLM through the
+ * Vercel AI SDK. The model and generation settings come from the {@link
+ * AgentRouting} (configurable per agent kind), and the concrete model is
+ * resolved through the {@link ModelProvider} port — so this class never imports
+ * a provider SDK or an API key directly.
+ */
+export declare class AiAgentExecutor implements AgentExecutor {
+    private readonly modelProviderResolver?;
+    private readonly modelProvider?;
+    private readonly agentRouting;
+    private readonly resolveBlockModel;
+    private readonly resolveWorkspaceModelDefault?;
+    private readonly webSearch?;
+    constructor({ modelProviderResolver, modelProvider, agentRouting, resolveBlockModel, resolveWorkspaceModelDefault, webSearch, }: AiAgentExecutorDependencies);
+    /** Resolve the model provider for a run's scope (per-scope DB pool, else the static one). */
+    private providerFor;
+    /**
+     * Resolve the step's model ref with the shared step precedence: a block's pinned
+     * model wins, else the workspace's per-kind default, else the env routing for the
+     * kind. A pinned subscription model (Claude Code / Codex), which can run only in
+     * the container harness, is degraded to the kind's env-routing default here — this
+     * is an inline executor — via the shared `resolveInlineModelRef` seam. Side-effect-
+     * free, so it backs both `run` and the up-front `resolveModel` (which thus reports
+     * the model that will actually run, not the un-servable subscription ref).
+     */
+    private resolveRef;
+    /** Preview the model this step will run, without making the LLM call. */
+    resolveModel(context: AgentRunContext): Promise<string>;
+    run(context: AgentRunContext): Promise<AgentRunResult>;
+}
+//# sourceMappingURL=AiAgentExecutor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"AiAgentExecutor.d.ts","sourceRoot":"","sources":["../../src/agents/AiAgentExecutor.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACzF,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AAGzF,OAAO,EAAE,KAAK,YAAY,EAA6C,MAAM,oBAAoB,CAAA;AAEjG,OAAO,EACL,KAAK,sBAAsB,EAG5B,MAAM,iBAAiB,CAAA;AAExB,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,YAAY,EAAE,YAAY,CAAA;IAC1B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,QAAQ,GAAG,SAAS,CAAA;IACzE;;;;;OAKG;IACH,4BAA4B,CAAC,EAAE,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAChC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAA;CACnC;AAED;;;;;;GAMG;AACH,qBAAa,eAAgB,YAAW,aAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAuB;IAC9D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAe;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAC3C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAuD;IACzF,OAAO,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAGd;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAwB;IAEnD,YAAY,EACV,qBAAqB,EACrB,aAAa,EACb,YAAY,EACZ,iBAAiB,EACjB,4BAA4B,EAC5B,SAAS,GACV,EAAE,2BAA2B,EAU7B;IAED,6FAA6F;YAC/E,WAAW;IAgBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAelB,yEAAyE;IACnE,YAAY,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAG5D;IAEK,GAAG,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAsD3D;CACF"}

package/dist/agents/AiAgentExecutor.js

@@ -0,0 +1,125 @@
+import { generateText } from 'ai';
+import { systemPromptFor, userPromptFor } from './agent-catalog.js';
+import { catFactoryObservability } from '../providers/instrumented.js';
+import { resolveAgentConfig, resolveInlineModelRef } from './agent-routing.js';
+import { composeBlockSystemPrompt } from './prompt-fragments.js';
+import { providerWebSearchTools, webResearchGuidanceFor, } from './web-search.js';
+/**
+ * The real agent: performs each pipeline step by calling an LLM through the
+ * Vercel AI SDK. The model and generation settings come from the {@link
+ * AgentRouting} (configurable per agent kind), and the concrete model is
+ * resolved through the {@link ModelProvider} port — so this class never imports
+ * a provider SDK or an API key directly.
+ */
+export class AiAgentExecutor {
+    modelProviderResolver;
+    modelProvider;
+    agentRouting;
+    resolveBlockModel;
+    resolveWorkspaceModelDefault;
+    webSearch;
+    constructor({ modelProviderResolver, modelProvider, agentRouting, resolveBlockModel, resolveWorkspaceModelDefault, webSearch, }) {
+        if (!modelProviderResolver && !modelProvider) {
+            throw new Error('AiAgentExecutor requires a modelProviderResolver or a modelProvider');
+        }
+        this.modelProviderResolver = modelProviderResolver;
+        this.modelProvider = modelProvider;
+        this.agentRouting = agentRouting;
+        this.resolveBlockModel = resolveBlockModel ?? (() => undefined);
+        this.resolveWorkspaceModelDefault = resolveWorkspaceModelDefault;
+        this.webSearch = webSearch;
+    }
+    /** Resolve the model provider for a run's scope (per-scope DB pool, else the static one). */
+    async providerFor(context) {
+        if (this.modelProviderResolver && context.workspaceId) {
+            return this.modelProviderResolver.forScope({
+                workspaceId: context.workspaceId,
+                userId: context.initiatedByUserId,
+            });
+        }
+        if (this.modelProvider)
+            return this.modelProvider;
+        if (this.modelProviderResolver) {
+            // No workspace scope (rare): lease from no scope — only the opt-in registries
+            // (Cloudflare/Bedrock) can resolve.
+            return this.modelProviderResolver.forScope({ workspaceId: context.workspaceId ?? '' });
+        }
+        throw new Error('AiAgentExecutor: no model provider available');
+    }
+    /**
+     * Resolve the step's model ref with the shared step precedence: a block's pinned
+     * model wins, else the workspace's per-kind default, else the env routing for the
+     * kind. A pinned subscription model (Claude Code / Codex), which can run only in
+     * the container harness, is degraded to the kind's env-routing default here — this
+     * is an inline executor — via the shared `resolveInlineModelRef` seam. Side-effect-
+     * free, so it backs both `run` and the up-front `resolveModel` (which thus reports
+     * the model that will actually run, not the un-servable subscription ref).
+     */
+    resolveRef(context) {
+        return resolveInlineModelRef({
+            agentRouting: this.agentRouting,
+            resolveBlockModel: this.resolveBlockModel,
+            resolveWorkspaceModelDefault: this.resolveWorkspaceModelDefault,
+        }, {
+            agentKind: context.agentKind,
+            blockModelId: context.block.modelId,
+            workspaceId: context.workspaceId,
+        });
+    }
+    /** Preview the model this step will run, without making the LLM call. */
+    async resolveModel(context) {
+        const ref = await this.resolveRef(context);
+        return `${ref.provider}:${ref.model}`;
+    }
+    async run(context) {
+        const config = resolveAgentConfig(this.agentRouting, context.agentKind);
+        // `resolveRef` already degrades a pinned subscription model (Claude Code / Codex,
+        // which run only in the container harness and have no provider key here) to this
+        // kind's env-routing default, so the ModelProvider always gets a servable ref.
+        const ref = await this.resolveRef(context);
+        const provider = await this.providerFor(context);
+        const model = provider.resolve(ref);
+        // Base role prompt, then fold in the best-practice fragments selected for the
+        // block — the engine-resolved tenant catalog when present, else the manual ids.
+        const baseSystem = config.system ?? systemPromptFor(context.agentKind);
+        const composed = composeBlockSystemPrompt(baseSystem, context.block);
+        // Provider-hosted web search for the allow-listed design/research kinds, when
+        // enabled AND the resolved provider has one. The usage nudge is appended only
+        // when the tool is actually attached, so the model is never told about a tool
+        // it lacks (mirrors the harness's AGENTS.md guidance gating).
+        const tools = this.webSearch && this.webSearch.kinds.has(context.agentKind)
+            ? providerWebSearchTools(ref.provider, this.webSearch.maxUses)
+            : undefined;
+        // Inline tool is web_search only (no web_fetch); the per-kind hint is resolved
+        // from the registry/catalog so a custom kind gets its own nudge.
+        const system = tools
+            ? `${composed}${webResearchGuidanceFor(context.agentKind, { fetch: false })}`
+            : composed;
+        const { text, usage } = await generateText({
+            model,
+            system,
+            prompt: userPromptFor(context),
+            temperature: config.temperature,
+            maxOutputTokens: config.maxOutputTokens,
+            ...(tools ? { tools } : {}),
+            // Tag the call so an instrumented provider can group it under its run's trace
+            // (a no-op when no trace sink is wired; ignored by every model provider).
+            providerOptions: catFactoryObservability({
+                agentKind: context.agentKind,
+                workspaceId: context.workspaceId,
+                executionId: context.executionId,
+            }),
+        });
+        return {
+            output: text.trim(),
+            model: `${ref.provider}:${ref.model}`,
+            // Report metered tokens so the spend safeguard can price this call. The
+            // AI SDK leaves either field undefined when a provider omits it.
+            usage: {
+                inputTokens: usage.inputTokens ?? 0,
+                outputTokens: usage.outputTokens ?? 0,
+            },
+        };
+    }
+}
+//# sourceMappingURL=AiAgentExecutor.js.map

package/dist/agents/AiAgentExecutor.js.map

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

package/dist/agents/acceptance-prompts.d.ts

@@ -0,0 +1,29 @@
+import type { AgentKind } from '@cat-factory/kernel';
+import type { AgentRunContext } from '@cat-factory/kernel';
+/** The agent kinds that make up the acceptance-testing track. */
+export type AcceptanceAgentKind = 'playwright';
+export declare const ACCEPTANCE_AGENT_KINDS: readonly AcceptanceAgentKind[];
+/** True when the agent kind is part of the acceptance-testing track. */
+export declare function isAcceptanceKind(kind: AgentKind): kind is AcceptanceAgentKind;
+/**
+ * The built-out system (role) prompt for an acceptance-testing agent kind, or
+ * `undefined` when the kind is not part of this track (so callers can fall
+ * through to the standard phases / generic role).
+ */
+export declare function acceptanceSystemPrompt(kind: AgentKind): string | undefined;
+/**
+ * The "where do the tests run" section for an acceptance-testing step, rendered
+ * from the block's contributed `playwright.e2eTarget` config value. Empty for
+ * non-track kinds or when no target is recorded, so callers can append it
+ * unconditionally.
+ */
+export declare function e2eTargetSection(context: AgentRunContext): string;
+/**
+ * The "how should these tests be written" section for the runnable-tests step
+ * (`playwright` kind), chosen from the block type: Playwright for user-facing
+ * blocks, the project's own test framework for backend blocks. Empty for the
+ * scenario-writing step and any non-track kind, so callers can append it
+ * unconditionally. The scenario author stays framework-agnostic by design.
+ */
+export declare function testApproachSection(context: AgentRunContext): string;
+//# sourceMappingURL=acceptance-prompts.d.ts.map

package/dist/agents/acceptance-prompts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acceptance-prompts.d.ts","sourceRoot":"","sources":["../../src/agents/acceptance-prompts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAa,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAwB1D,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,YAAY,CAAA;AAE9C,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EAAmB,CAAA;AAsCpF,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,mBAAmB,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAE1E;AAoBD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAMjE;AAqBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAIpE"}

package/dist/agents/acceptance-prompts.js

@@ -0,0 +1,112 @@
+import { PLATFORM_DELIVERY_CONTRACT } from './ci-gate.js';
+import { PLAYWRIGHT_E2E_TARGET_CONFIG_ID } from './agent-configs.js';
+import { STANDARDS_FOOTER } from './prompt-shared.js';
+export const ACCEPTANCE_AGENT_KINDS = ['playwright'];
+// The runnable-tests step commits tests through a pull request. Tests only earn
+// their keep once they actually run in CI, so "done" means the suite is wired into
+// the project's CI configuration AND passes locally. The agent does NOT push or wait
+// on CI itself (it has no push credentials) — the platform pushes, opens the PR and
+// drives CI per the shared PLATFORM_DELIVERY_CONTRACT; the agent's job is to author
+// the tests and hook them into the CI config.
+const PLAYWRIGHT_DELIVERY_GATE = [
+    'Definition of done: the acceptance tests are written, wired into the project CI configuration, and pass when you run them locally.',
+    '- Make sure the suite is actually hooked into the project CI workflow: confirm the workflow executes this suite on a pull request, and add or update the CI configuration if it does not yet run them. (Editing the CI config is part of the work; running CI is not — the platform does that.)',
+    PLATFORM_DELIVERY_CONTRACT,
+].join('\n');
+const SYSTEM_PROMPTS = {
+    playwright: [
+        'You are a test automation engineer owning the runnable ACCEPTANCE TESTS for a building block.',
+        'Translate the agreed acceptance scenarios into runnable tests that live in the repository.',
+        '',
+        'Pick the test tool to match the surface under test:',
+        '- Frontend / user-facing UI: write Playwright end-to-end tests that drive the app through the browser.',
+        "- Backend (services, APIs, queues, integrations, data): write the acceptance tests with the project's EXISTING test framework — discover it from the repository (test config, dev dependencies, the tests already present) and match it. Do not pull in Playwright or a browser for behaviour that has no UI.",
+        'The run context below states the test approach for this specific block; follow it.',
+        '',
+        'Approach:',
+        '- Treat the acceptance scenarios as the source of truth: prefer the Gherkin scenarios in `spec/features/*.feature` when present (each `Scenario` becomes one runnable test, named after it), else the scenarios provided above. One test per scenario so the mapping is obvious.',
+        '- Be additive and idempotent: only create tests for scenarios that do not already have one; never duplicate or silently rewrite an existing test.',
+        '- Exercise the system through its outermost interface and assert on observable behaviour — user-facing locators (roles, labels, text) for UI, public API / HTTP / message contracts for backend — never on internal implementation.',
+        '- Keep tests isolated and deterministic: no shared mutable state, await every action, and rely on auto-retrying assertions instead of fixed sleeps.',
+        '- Reach the system under test at the URL / entry point from the run context; read any access credentials from the harness, never hard-code secrets.',
+        '- Output the test files to commit, each in the conventional test directory for its tool (e.g. the e2e/Playwright directory for UI tests), ready to run in CI.',
+        '',
+        PLAYWRIGHT_DELIVERY_GATE,
+        '',
+        STANDARDS_FOOTER,
+    ].join('\n'),
+};
+/** True when the agent kind is part of the acceptance-testing track. */
+export function isAcceptanceKind(kind) {
+    return kind === 'playwright';
+}
+/**
+ * The built-out system (role) prompt for an acceptance-testing agent kind, or
+ * `undefined` when the kind is not part of this track (so callers can fall
+ * through to the standard phases / generic role).
+ */
+export function acceptanceSystemPrompt(kind) {
+    return isAcceptanceKind(kind) ? SYSTEM_PROMPTS[kind] : undefined;
+}
+// Where the generated tests run is a per-block choice, so it is dynamic context
+// rather than part of the static role prompt. These blurbs tell the agent how
+// to wire and where to point the tests for each target.
+const TEST_TARGET_GUIDANCE = {
+    ci: [
+        'Test execution target: project CI (GitHub Actions).',
+        '- Add the tests to the project so they run in a GitHub Actions workflow on each push / pull request.',
+        '- Spin the system under test up inside the same workflow run (e.g. a build/start step or a `services:` container) and wait for it to be healthy before the tests run.',
+        '- Point Playwright at the locally started service (e.g. http://localhost:<port>) via its config/baseURL; do not rely on an external environment.',
+    ].join('\n'),
+    ephemeral: [
+        'Test execution target: the provisioned ephemeral environment for this run.',
+        '- Run the tests against the ephemeral environment URL from the run context, not a locally started service.',
+        '- Read any access credentials for that environment from the test harness/secrets; never hard-code them.',
+        '- Assume the environment is already deployed and healthy before the tests start.',
+    ].join('\n'),
+};
+/**
+ * The "where do the tests run" section for an acceptance-testing step, rendered
+ * from the block's contributed `playwright.e2eTarget` config value. Empty for
+ * non-track kinds or when no target is recorded, so callers can append it
+ * unconditionally.
+ */
+export function e2eTargetSection(context) {
+    if (!isAcceptanceKind(context.agentKind))
+        return '';
+    const raw = context.block.agentConfig?.[PLAYWRIGHT_E2E_TARGET_CONFIG_ID];
+    const target = raw === 'ci' || raw === 'ephemeral' ? raw : undefined;
+    if (!target)
+        return '';
+    return `\n${TEST_TARGET_GUIDANCE[target]}`;
+}
+// Block types whose behaviour is exercised through a browser UI, so the runnable
+// tests should be Playwright e2e. Everything else is backend behaviour that gets
+// tested with the project's own framework. Mirrors how the `playwright.e2e`
+// best-practice fragment is scoped in @cat-factory/prompt-fragments.
+const UI_BLOCK_TYPES = ['frontend', 'environment'];
+const UI_TEST_APPROACH = [
+    'Test approach for this block: Playwright end-to-end tests.',
+    '- This block has a user-facing surface, so cover its scenarios with Playwright tests that drive the app through the browser.',
+    '- Select elements by user-facing locators (getByRole, getByLabel, getByText) and assert on what the user observes.',
+].join('\n');
+const BACKEND_TEST_APPROACH = [
+    "Test approach for this block: the project's existing test framework (do NOT use Playwright).",
+    '- This block has no user-facing UI, so do not add Playwright or a browser to it.',
+    "- Discover the test framework already used in the repository (test config, dev dependencies, the tests already present) and write the acceptance tests with it, matching the project's conventions.",
+    '- Drive the system through its public interface (API / HTTP calls, queue messages, exported functions) and assert on observable behaviour, never on internals.',
+].join('\n');
+/**
+ * The "how should these tests be written" section for the runnable-tests step
+ * (`playwright` kind), chosen from the block type: Playwright for user-facing
+ * blocks, the project's own test framework for backend blocks. Empty for the
+ * scenario-writing step and any non-track kind, so callers can append it
+ * unconditionally. The scenario author stays framework-agnostic by design.
+ */
+export function testApproachSection(context) {
+    if (context.agentKind !== 'playwright')
+        return '';
+    const isUi = UI_BLOCK_TYPES.includes(context.block.type);
+    return `\n${isUi ? UI_TEST_APPROACH : BACKEND_TEST_APPROACH}`;
+}
+//# sourceMappingURL=acceptance-prompts.js.map

package/dist/agents/acceptance-prompts.js.map

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

package/dist/agents/agent-catalog.d.ts

@@ -0,0 +1,6 @@
+import type { AgentKind } from '@cat-factory/kernel';
+import type { AgentRunContext } from '@cat-factory/kernel';
+export declare function systemPromptFor(kind: AgentKind): string;
+/** Build the user prompt from the block context and the run so far. */
+export declare function userPromptFor(context: AgentRunContext): string;
+//# sourceMappingURL=agent-catalog.d.ts.map

package/dist/agents/agent-catalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-catalog.d.ts","sourceRoot":"","sources":["../../src/agents/agent-catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAqE1D,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAUvD;AAmED,uEAAuE;AACvE,wBAAgB,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAE9D"}

package/dist/agents/agent-catalog.js

@@ -0,0 +1,197 @@
+import { acceptanceSystemPrompt, testApproachSection, e2eTargetSection, } from './acceptance-prompts.js';
+import { companionSystemPrompt } from './companion-prompts.js';
+import { companionTargets, isCompanionKind } from './companions.js';
+import { READ_ONLY_GUARDRAIL, isReadOnlyAgentKind } from './read-only.js';
+import { businessLogicSystemPrompt } from './business-logic-prompts.js';
+import { mockSystemPrompt } from './mock-prompts.js';
+import { testingSystemPrompt, testerEnvironmentSection } from './test-prompts.js';
+import { registeredSystemPrompt, registeredUserPrompt } from './registry.js';
+import { traitGuidanceFor } from './traits.js';
+import { environmentSection, linkedContextSection, phaseForKind, renderStandardUserPrompt, standardSystemPrompt, } from './standard-prompts.js';
+// Role definitions and prompt construction for the built-in agent kinds. These
+// turn an agent kind + block context into the system/user prompts handed to the
+// LLM. The four standard solution phases — design (architect), build (coder),
+// review (reviewer) and test (tester) — use the built-out prompts in
+// ./standard-prompts; the acceptance-testing track (acceptance, playwright) uses
+// the built-out prompts in ./acceptance-prompts; the mock builder (mocker) uses
+// the built-out prompt in ./mock-prompts; the business-logic / domain-rules track
+// (business-documenter, business-reviewer) uses the built-out prompts in
+// ./business-logic-prompts; the remaining kinds use the thin roles below, and
+// custom agent kinds (free-form ids) fall back to a generic role.
+const ROLES = {
+    researcher: 'You are a technical researcher. Investigate prior art, libraries and constraints relevant to the building block and summarise concrete recommendations.',
+    // Opens the tech-debt recurring pipeline. Clones the repo and inspects it for the
+    // highest-value technical debt; it MUST be read-only (make no edits / commits) and
+    // produce a single, prioritized, actionable markdown report that a downstream
+    // `tracker` step files as an issue and a `coder` step then implements.
+    analysis: 'You are a senior engineer performing a technical-debt audit of this service. Explore the repository (build scripts, dependencies, tests, hot spots, TODO/FIXME markers, outdated patterns) and identify the highest-value technical debt to address now. Produce a single prioritized markdown report: for each item give a short title, the affected area, why it matters, and a concrete suggested fix. Lead with the one item most worth doing first, since it will be turned into a tracked issue and implemented.',
+    documenter: 'You are a technical writer. Produce concise developer documentation and a usage example for the building block.',
+    integrator: 'You are an integration engineer. Describe how to wire this building block into the surrounding system, including contracts and rollout.',
+    // Runs before the architect: reviews the collected CONTEXT (the linked-prose brief)
+    // and surfaces what would block confident implementation. Its findings are presented
+    // to a human at an approval gate (to reject items or supply missing information)
+    // before the architect proceeds, so it must read as a clear, editable list.
+    'requirements-review': 'You are a meticulous product / requirements analyst reviewing the collected requirements for a single building block before an engineer designs or builds it. Surface everything that would block confident implementation: missing information (gaps), ambiguities that need clarification, unstated assumptions, risks, and open questions. Be specific, concrete and actionable, and phrase each item so a product owner can answer it directly. Do NOT invent answers or requirements. Group your findings under clear headings and present a concise, readable markdown list — a human will review and edit it before the architect proceeds.',
+    // Runs in a container against the PR head branch when CI is red. It must make the
+    // failing build/tests pass with the smallest correct change and push to the same
+    // branch (no new branch / PR) so CI re-runs.
+    'ci-fixer': 'You are a CI/build engineer. The pull request on this branch has failing CI. Reproduce the failure locally (run the project build / tests), diagnose the root cause, and make the minimal correct change to get every check passing. Do not disable or skip tests to make them pass. Commit your fix to the current branch.',
+    // Runs in a container against the PR head branch when the PR conflicts with its
+    // base. The harness has already merged the base in, leaving conflict markers; the
+    // agent resolves every one and the harness completes the merge commit + pushes to
+    // the same branch (no new branch / PR).
+    'conflict-resolver': 'You are a software engineer resolving a merge conflict. The base branch has been merged into this pull-request branch, leaving Git conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) in one or more files. Find every conflicted file, understand both sides of each conflict, and edit the files to a correct, coherent result that preserves the intent of BOTH the PR changes and the base changes — never just discard one side. Remove all conflict markers and leave the project building. Do not open a new branch or PR; commit your resolution to the current branch.',
+    // Runs in a container against the PR head branch as the final pipeline step. It
+    // ONLY assesses — it must not modify the repo — and returns a JSON score object.
+    merger: 'You are a release manager assessing a pull request before merge. Inspect the change against the base branch and judge three axes, each from 0 (trivial/safe) to 1 (severe): complexity, risk and impact. Be conservative. Make no commits. Respond with ONLY a JSON object {"complexity":0.0,"risk":0.0,"impact":0.0,"rationale":"…"} — no prose, no code fences.',
+};
+export function systemPromptFor(kind) {
+    const base = baseSystemPromptFor(kind);
+    // Read-only kinds (architect, analysis) explore a real checkout but must never edit
+    // it; append the shared guardrail so the harness `/explore` run stays edit-free.
+    const withGuardrail = isReadOnlyAgentKind(kind) ? `${base}\n\n${READ_ONLY_GUARDRAIL}` : base;
+    // Fold in any guidance contributed by the kind's traits (e.g. the spec-aware kinds get
+    // the in-repo-spec reading guidance). Marker traits like `code-aware` add nothing here —
+    // their effect (folding the service's fragments) is applied by the execution engine.
+    const guidance = traitGuidanceFor(kind);
+    return guidance.length ? `${withGuardrail}\n\n${guidance.join('\n\n')}` : withGuardrail;
+}
+function baseSystemPromptFor(kind) {
+    // Companion kinds (reviewer, architect-companion, spec-companion, …) win over every
+    // built-in track: they grade a prior step's output and return a JSON rating.
+    const companion = companionSystemPrompt(kind);
+    if (companion)
+        return companion;
+    const phase = phaseForKind(kind);
+    if (phase)
+        return standardSystemPrompt(phase);
+    // The Tester/Fixer track runs in a container and returns a structured report /
+    // pushes fixes; it owns its own prompts rather than the generic `test` phase.
+    const testing = testingSystemPrompt(kind);
+    if (testing)
+        return testing;
+    const acceptance = acceptanceSystemPrompt(kind);
+    if (acceptance)
+        return acceptance;
+    const mock = mockSystemPrompt(kind);
+    if (mock)
+        return mock;
+    const businessLogic = businessLogicSystemPrompt(kind);
+    if (businessLogic)
+        return businessLogic;
+    // Custom kinds registered by a deployment (e.g. a proprietary org package) win over
+    // the generic fallback below, but never shadow the built-in tracks above.
+    const registered = registeredSystemPrompt(kind);
+    if (registered !== undefined)
+        return registered;
+    return (ROLES[kind] ??
+        `You are the "${kind}" agent. Do your part of the work for the given building block and report the result concisely.`);
+}
+/**
+ * When a human requested changes on this step's gated proposal, append their
+ * feedback and the previous proposal so the agent revises rather than restarts.
+ * Applied to every inline agent kind (standard-phase and generic alike).
+ */
+function withRevision(prompt, context) {
+    const revision = context.revision;
+    if (!revision)
+        return prompt;
+    const lines = [
+        prompt,
+        '',
+        'A human reviewed your previous proposal and requested changes. Revise that',
+        'proposal to address their feedback — keep what still holds, change what they',
+        'flagged. Do not start from scratch.',
+        '',
+        'Your previous proposal:',
+        revision.previousProposal || '(empty)',
+        '',
+        'Reviewer feedback:',
+        revision.feedback || '(none given)',
+    ];
+    // Per-block comments the reviewer left on specific parts of the proposal. Each
+    // quotes the exact text it targets, so the agent can locate and revise it.
+    if (revision.comments?.length) {
+        lines.push('', 'Comments on specific parts of your proposal:');
+        for (const c of revision.comments) {
+            lines.push('', 'On this part:', c.quotedSource || '(empty)', 'Comment:', c.body || '(none given)');
+        }
+    }
+    return lines.join('\n');
+}
+/** Build the user prompt from the block context and the run so far. */
+export function userPromptFor(context) {
+    return withRevision(buildBaseUserPrompt(context), context);
+}
+function buildBaseUserPrompt(context) {
+    // Standard phases get their built-out, templated user prompt.
+    const phase = phaseForKind(context.agentKind);
+    if (phase)
+        return renderStandardUserPrompt(phase, context);
+    // A registered custom kind may supply its own user prompt; otherwise it falls through
+    // to the generic block-context prompt below, like any other non-standard-phase kind.
+    const registered = registeredUserPrompt(context);
+    if (registered !== undefined)
+        return registered;
+    const { block, pipelineName, priorOutputs, decisions, resolvedDecision } = context;
+    const lines = [
+        `Pipeline: ${pipelineName}`,
+        `Block: ${block.title} (${block.type})`,
+        `Description: ${block.description || '(none provided)'}`,
+    ];
+    // A companion grades a specific preceding producer; name it explicitly so the
+    // model rates the right output rather than guessing among the prior-agent sections.
+    const companionTarget = companionTargetSection(context);
+    if (companionTarget)
+        lines.push(companionTarget);
+    const linked = linkedContextSection(context);
+    if (linked)
+        lines.push(linked);
+    const envSection = environmentSection(context);
+    if (envSection)
+        lines.push(envSection);
+    const approachSection = testApproachSection(context);
+    if (approachSection)
+        lines.push(approachSection);
+    const targetSection = e2eTargetSection(context);
+    if (targetSection)
+        lines.push(targetSection);
+    const testerEnv = testerEnvironmentSection(context);
+    if (testerEnv)
+        lines.push(testerEnv);
+    const allDecisions = resolvedDecision ? [...decisions, resolvedDecision] : decisions;
+    if (allDecisions.length) {
+        lines.push('', 'Resolved decisions:');
+        for (const d of allDecisions)
+            lines.push(`- ${d.question} → ${d.chosen}`);
+    }
+    if (priorOutputs.length) {
+        lines.push('', 'Work from earlier agents in this pipeline:');
+        for (const p of priorOutputs) {
+            lines.push(`### ${p.agentKind}`, p.output);
+        }
+    }
+    lines.push('', 'Produce your contribution. Be concise and concrete.');
+    return lines.join('\n');
+}
+/**
+ * For a companion step, name the specific producer output it must grade: the NEAREST
+ * preceding step whose kind is one of the companion's targets. Without this the model
+ * has to infer which "### <agentKind>" section is the one under review — fine when the
+ * producer is adjacent, ambiguous when other steps sit in between. Undefined for
+ * non-companion kinds or when no target output is present yet.
+ */
+function companionTargetSection(context) {
+    if (!isCompanionKind(context.agentKind))
+        return undefined;
+    const targets = companionTargets(context.agentKind);
+    for (let i = context.priorOutputs.length - 1; i >= 0; i--) {
+        const produced = context.priorOutputs[i];
+        if (targets.includes(produced.agentKind)) {
+            return (`You are grading the output of the \`${produced.agentKind}\` step (shown under ` +
+                `"### ${produced.agentKind}" below). Base your rating on THAT output.`);
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent-catalog.js.map

package/dist/agents/agent-catalog.js.map

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

package/dist/agents/agent-configs.d.ts

@@ -0,0 +1,17 @@
+import type { AgentConfigDescriptor, AgentKind } from '@cat-factory/kernel';
+/** The Tester's environment choice: stand infra up locally, or use the ephemeral env. */
+export declare const TESTER_ENVIRONMENT_CONFIG_ID = "tester.environment";
+/** The acceptance/e2e execution target: project CI, or the ephemeral env. */
+export declare const PLAYWRIGHT_E2E_TARGET_CONFIG_ID = "playwright.e2eTarget";
+/**
+ * The config descriptors an agent kind contributes: the built-in ones plus any a
+ * deployment registered for the kind. Empty for kinds that contribute none.
+ */
+export declare function configContributionsFor(kind: AgentKind): AgentConfigDescriptor[];
+/**
+ * The deduplicated catalog of config descriptors contributed across a set of agent
+ * kinds (e.g. all the kinds used by a workspace's pipelines), keyed by descriptor
+ * id (first contribution wins). This is what the workspace snapshot carries.
+ */
+export declare function configContributionCatalog(kinds: Iterable<AgentKind>): AgentConfigDescriptor[];
+//# sourceMappingURL=agent-configs.d.ts.map