@cat-factory/agents 0.6.0

package/dist/agents/test-prompts.js

@@ -0,0 +1,92 @@
+import { STANDARDS_FOOTER } from './prompt-shared.js';
+import { TESTER_ENVIRONMENT_CONFIG_ID } from './agent-configs.js';
+// Built-out role prompts for the Tester → Fixer loop. The `tester` clones the PR
+// branch, brings its dependencies up (locally via docker-compose, or against the
+// provisioned ephemeral environment — the task's `tester.environment` config picks
+// which), exercises this task's requirements plus best-judgement regression of
+// related behaviour, and returns ONLY a structured JSON report (it makes no commits,
+// like the `merger`). When the report withholds its greenlight the engine dispatches
+// the `fixer` with the report folded in; the fixer commits fixes to the same branch
+// and the Tester re-runs, until greenlight or the attempt budget is spent.
+const TESTER_AGENT_KIND = 'tester';
+const FIXER_AGENT_KIND = 'fixer';
+/** The JSON shape the Tester must emit, kept in sync with `testReportSchema`. */
+const TEST_REPORT_SHAPE = [
+    'Respond with ONLY a JSON object (no prose, no code fences) of this shape:',
+    '{',
+    '  "greenlight": boolean,            // true only when the change is safe to release',
+    '  "summary": string,               // overall prose summary of the session',
+    '  "tested": string[],              // what you chose to exercise (requirements + regression areas)',
+    '  "outcomes": [                    // per-area results',
+    '    { "name": string, "status": "passed" | "failed" | "skipped", "detail"?: string }',
+    '  ],',
+    '  "concerns": [                    // bugs/risks to fix before re-testing; non-empty ⇒ greenlight false',
+    '    { "title": string, "detail": string, "severity": "low" | "medium" | "high" | "critical" }',
+    '  ],',
+    '  "environment"?: "local" | "ephemeral"',
+    '}',
+].join('\n');
+const TESTER_SYSTEM_PROMPT = [
+    'You are a meticulous test engineer doing EXPLORATORY testing of a pull request before release.',
+    'You actually run the software and observe its behaviour — you do NOT pass judgement by reading the diff or restating what the implementer says they did. A greenlight that is not backed by something you actually exercised is worthless.',
+    '',
+    'Bootstrap your environment from the repository:',
+    "- Read the repo's README.md (and any CONTRIBUTING / docs it points to) to learn how to install dependencies, configure the service, run migrations and start it.",
+    "- Local mode: the platform has stood up the service's infra dependencies from its docker-compose file (including the WireMock mocks the mocker step added for the service's external dependencies) and exposed them on localhost. Connect to them, run any DB migrations, then start the service and exercise it against those mocks. If the service was marked as having no infra dependencies, just run the suite directly.",
+    '- Ephemeral mode: a deployed environment URL (and access credentials) is provided in the run context; test against it rather than starting anything locally.',
+    '',
+    'What to test:',
+    "- Start from the specs written in earlier steps: the unified spec under `spec/` and especially its Gherkin acceptance scenarios in `spec/features/*.feature`. Walk the scenarios that cover THIS task's new functionality and confirm the running service actually behaves that way.",
+    '- Explore the new functionality beyond the happy path: probe edge cases, bad input, error and boundary conditions, and the failure responses the external mocks can return — the kinds of things a scripted suite tends to miss.',
+    '- Then do a REASONABLE amount of regression testing of related behaviour the change could plausibly affect — target the blast radius, do not re-test the whole system.',
+    '- Run the existing automated suite where present, and add your own ad-hoc checks (API calls, flows, UI interactions) on top of it.',
+    '',
+    'Rules:',
+    "- Make NO commits and open NO pull request — you only assess and report. Fixes are another agent's job (the engine dispatches a fixer when you withhold the greenlight, then re-runs you).",
+    '- Base every outcome on something you actually observed. Greenlight ONLY when you have exercised the change and are confident it is correct and safe; any blocking bug or unresolved risk means greenlight=false with the concern listed. Minor, sub-blocking issues go in `concerns` at low/medium severity without necessarily withholding the greenlight.',
+    '',
+    TEST_REPORT_SHAPE,
+].join('\n');
+const FIXER_SYSTEM_PROMPT = [
+    'You are a software engineer fixing problems a tester found on this pull-request branch.',
+    'The tester’s structured report (what was tested, the outcomes, and the concerns/bugs to fix) is provided in the run context below.',
+    '',
+    'Address every concern the tester raised:',
+    '- Reproduce each issue, find the root cause, and make the minimal correct change to fix it.',
+    '- Do not disable, skip or weaken tests to make them pass; fix the underlying behaviour.',
+    '- Keep the project building and the existing tests green.',
+    '',
+    'Commit your fixes to the current branch (no new branch, no new PR) so the tester can re-run against them.',
+    '',
+    STANDARDS_FOOTER,
+].join('\n');
+/** True when the kind is part of the Tester/Fixer track. */
+export function isTestingKind(kind) {
+    return kind === TESTER_AGENT_KIND || kind === FIXER_AGENT_KIND;
+}
+/** The built-out system prompt for a Tester/Fixer kind, or undefined otherwise. */
+export function testingSystemPrompt(kind) {
+    if (kind === TESTER_AGENT_KIND)
+        return TESTER_SYSTEM_PROMPT;
+    if (kind === FIXER_AGENT_KIND)
+        return FIXER_SYSTEM_PROMPT;
+    return undefined;
+}
+/**
+ * The "which environment to run in" section for a Tester step, rendered from the
+ * block's contributed `tester.environment` config value. Empty for non-tester kinds
+ * or when nothing is set, so callers can append it unconditionally.
+ */
+export function testerEnvironmentSection(context) {
+    if (context.agentKind !== TESTER_AGENT_KIND)
+        return '';
+    const env = context.block.agentConfig?.[TESTER_ENVIRONMENT_CONFIG_ID];
+    if (env === 'ephemeral') {
+        return '\nRun mode: ephemeral environment — test against the provided environment URL; do not start the service locally.';
+    }
+    if (env === 'local') {
+        return '\nRun mode: local — the service’s infra dependencies have been stood up on localhost; start the service yourself and test it there.';
+    }
+    return '';
+}
+//# sourceMappingURL=test-prompts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"test-prompts.js","sourceRoot":"","sources":["../../src/agents/test-prompts.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAA;AAEjE,iFAAiF;AACjF,iFAAiF;AACjF,mFAAmF;AACnF,+EAA+E;AAC/E,qFAAqF;AACrF,qFAAqF;AACrF,oFAAoF;AACpF,2EAA2E;AAE3E,MAAM,iBAAiB,GAAG,QAAQ,CAAA;AAClC,MAAM,gBAAgB,GAAG,OAAO,CAAA;AAEhC,iFAAiF;AACjF,MAAM,iBAAiB,GAAG;IACxB,2EAA2E;IAC3E,GAAG;IACH,qFAAqF;IACrF,4EAA4E;IAC5E,oGAAoG;IACpG,wDAAwD;IACxD,sFAAsF;IACtF,MAAM;IACN,yGAAyG;IACzG,+FAA+F;IAC/F,MAAM;IACN,yCAAyC;IACzC,GAAG;CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,MAAM,oBAAoB,GAAG;IAC3B,gGAAgG;IAChG,4OAA4O;IAC5O,EAAE;IACF,iDAAiD;IACjD,kKAAkK;IAClK,+ZAA+Z;IAC/Z,8JAA8J;IAC9J,EAAE;IACF,eAAe;IACf,sRAAsR;IACtR,kOAAkO;IAClO,wKAAwK;IACxK,oIAAoI;IACpI,EAAE;IACF,QAAQ;IACR,4LAA4L;IAC5L,8VAA8V;IAC9V,EAAE;IACF,iBAAiB;CAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,MAAM,mBAAmB,GAAG;IAC1B,yFAAyF;IACzF,oIAAoI;IACpI,EAAE;IACF,0CAA0C;IAC1C,6FAA6F;IAC7F,yFAAyF;IACzF,2DAA2D;IAC3D,EAAE;IACF,2GAA2G;IAC3G,EAAE;IACF,gBAAgB;CACjB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAEZ,4DAA4D;AAC5D,MAAM,UAAU,aAAa,CAAC,IAAe;IAC3C,OAAO,IAAI,KAAK,iBAAiB,IAAI,IAAI,KAAK,gBAAgB,CAAA;AAChE,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,mBAAmB,CAAC,IAAe;IACjD,IAAI,IAAI,KAAK,iBAAiB;QAAE,OAAO,oBAAoB,CAAA;IAC3D,IAAI,IAAI,KAAK,gBAAgB;QAAE,OAAO,mBAAmB,CAAA;IACzD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAwB;IAC/D,IAAI,OAAO,CAAC,SAAS,KAAK,iBAAiB;QAAE,OAAO,EAAE,CAAA;IACtD,MAAM,GAAG,GAAG,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,4BAA4B,CAAC,CAAA;IACrE,IAAI,GAAG,KAAK,WAAW,EAAE,CAAC;QACxB,OAAO,kHAAkH,CAAA;IAC3H,CAAC;IACD,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;QACpB,OAAO,qIAAqI,CAAA;IAC9I,CAAC;IACD,OAAO,EAAE,CAAA;AACX,CAAC"}

package/dist/agents/traits.d.ts

@@ -0,0 +1,56 @@
+import type { AgentKind } from '@cat-factory/kernel';
+/** A trait id. Free-form so deployments can define their own beyond the standard two. */
+export type AgentTrait = string;
+/**
+ * Code-aware kinds read and/or change the service's code. The service's selected
+ * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
+ * their system prompt by the execution engine.
+ */
+export declare const CODE_AWARE_TRAIT: AgentTrait;
+/**
+ * Spec-aware kinds are told to read the in-repo `spec/` artifact (the prescriptive
+ * service specification) and how to interpret it. The instruction is appended to their
+ * system prompt via {@link traitGuidanceFor}.
+ */
+export declare const SPEC_AWARE_TRAIT: AgentTrait;
+/** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
+export declare const SPEC_AWARE_GUIDANCE: string;
+/**
+ * Built-in trait assignment per agent kind.
+ *  - `code-aware`: the kinds that read/modify the service's code, so the service's
+ *    best-practice fragments are relevant to them.
+ *  - `spec-aware`: every code-touching kind (anything that clones and reads the repo),
+ *    so each is pointed at the in-repo spec. The `spec-writer` is intentionally absent —
+ *    it AUTHORS the spec rather than consuming it.
+ */
+export declare const STANDARD_AGENT_TRAITS: Partial<Record<AgentKind, AgentTrait[]>>;
+/** Definition of a (custom) trait: its id and optional system-prompt guidance. */
+export interface AgentTraitDefinition {
+    /** The trait id used in `STANDARD_AGENT_TRAITS` / `AgentKindDefinition.traits`. */
+    id: AgentTrait;
+    /**
+     * Guidance folded into the system prompt of every kind carrying this trait. A function
+     * form receives the kind id. Omit for a pure marker trait whose effect lives in the
+     * engine (like `code-aware`).
+     */
+    guidance?: string | ((kind: AgentKind) => string);
+}
+/** Register a custom trait definition. A later registration of the same id replaces it. */
+export declare function registerAgentTrait(definition: AgentTraitDefinition): void;
+/** Register several custom trait definitions at once. */
+export declare function registerAgentTraits(definitions: Iterable<AgentTraitDefinition>): void;
+/** The definition for a trait id, or undefined when it is a pure marker / unregistered. */
+export declare function registeredAgentTrait(id: AgentTrait): AgentTraitDefinition | undefined;
+/** Drop all registered (custom) traits. Intended for tests; standard traits re-register below. */
+export declare function clearRegisteredAgentTraits(): void;
+/** The traits a kind carries: its built-in set unioned with a registered custom kind's. */
+export declare function traitsFor(kind: AgentKind): Set<AgentTrait>;
+/** Whether `kind` carries `trait`. */
+export declare function hasTrait(kind: AgentKind, trait: AgentTrait): boolean;
+/**
+ * The guidance lines contributed by the traits a kind carries, in trait order. Folded
+ * into the kind's system prompt by `systemPromptFor`. Marker traits (no guidance, e.g.
+ * `code-aware`) contribute nothing here.
+ */
+export declare function traitGuidanceFor(kind: AgentKind): string[];
+//# sourceMappingURL=traits.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../../src/agents/traits.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAapD,yFAAyF;AACzF,MAAM,MAAM,UAAU,GAAG,MAAM,CAAA;AAE/B;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAAyB,CAAA;AAExD,6FAA6F;AAC7F,eAAO,MAAM,mBAAmB,QAOpB,CAAA;AAEZ;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAe1E,CAAA;AAED,kFAAkF;AAClF,MAAM,WAAW,oBAAoB;IACnC,mFAAmF;IACnF,EAAE,EAAE,UAAU,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;CAClD;AAKD,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,GAAG,IAAI,CAEzE;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,QAAQ,CAAC,oBAAoB,CAAC,GAAG,IAAI,CAErF;AAED,2FAA2F;AAC3F,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,UAAU,GAAG,oBAAoB,GAAG,SAAS,CAErF;AAED,kGAAkG;AAClG,wBAAgB,0BAA0B,IAAI,IAAI,CAGjD;AAED,2FAA2F;AAC3F,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,GAAG,CAAC,UAAU,CAAC,CAI1D;AAED,sCAAsC;AACtC,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,UAAU,GAAG,OAAO,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE,CAQ1D"}

package/dist/agents/traits.js

@@ -0,0 +1,100 @@
+import { SPEC_FEATURES_DIR, SPEC_JSON_PATH, SPEC_OVERVIEW_PATH, SPEC_RULES_PATH, } from '@cat-factory/contracts';
+import { registeredAgentKind } from './registry.js';
+/**
+ * Code-aware kinds read and/or change the service's code. The service's selected
+ * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
+ * their system prompt by the execution engine.
+ */
+export const CODE_AWARE_TRAIT = 'code-aware';
+/**
+ * Spec-aware kinds are told to read the in-repo `spec/` artifact (the prescriptive
+ * service specification) and how to interpret it. The instruction is appended to their
+ * system prompt via {@link traitGuidanceFor}.
+ */
+export const SPEC_AWARE_TRAIT = 'spec-aware';
+/** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
+export const SPEC_AWARE_GUIDANCE = [
+    `This repository may contain a prescriptive SPECIFICATION for the service under the \`spec/\` directory — the source of truth for what the service must do. When it is present, read it before doing the work:`,
+    `- \`${SPEC_OVERVIEW_PATH}\` first, for the high-level product intent.`,
+    `- \`${SPEC_RULES_PATH}\` for cross-cutting domain rules, invariants and constraints.`,
+    `- \`${SPEC_FEATURES_DIR}/*.feature\` for the Gherkin (Given/When/Then) acceptance scenarios.`,
+    `- \`${SPEC_JSON_PATH}\` is the canonical machine-readable tree the markdown/feature files are rendered from; consult it when you need exact detail.`,
+    `Treat the spec as authoritative for required behaviour: make your change satisfy it, and if your change conflicts with the spec, follow the spec or call out the discrepancy rather than silently diverging.`,
+].join('\n');
+/**
+ * Built-in trait assignment per agent kind.
+ *  - `code-aware`: the kinds that read/modify the service's code, so the service's
+ *    best-practice fragments are relevant to them.
+ *  - `spec-aware`: every code-touching kind (anything that clones and reads the repo),
+ *    so each is pointed at the in-repo spec. The `spec-writer` is intentionally absent —
+ *    it AUTHORS the spec rather than consuming it.
+ */
+export const STANDARD_AGENT_TRAITS = {
+    architect: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    coder: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    reviewer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    'ci-fixer': [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    fixer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
+    'conflict-resolver': [SPEC_AWARE_TRAIT],
+    tester: [SPEC_AWARE_TRAIT],
+    playwright: [SPEC_AWARE_TRAIT],
+    blueprints: [SPEC_AWARE_TRAIT],
+    'business-documenter': [SPEC_AWARE_TRAIT],
+    'business-reviewer': [SPEC_AWARE_TRAIT],
+    analysis: [SPEC_AWARE_TRAIT],
+    mocker: [SPEC_AWARE_TRAIT],
+    merger: [SPEC_AWARE_TRAIT],
+};
+// Process-wide trait registry, mirroring the agent-kind / model-provider registries.
+const traitRegistry = new Map();
+/** Register a custom trait definition. A later registration of the same id replaces it. */
+export function registerAgentTrait(definition) {
+    traitRegistry.set(definition.id, definition);
+}
+/** Register several custom trait definitions at once. */
+export function registerAgentTraits(definitions) {
+    for (const definition of definitions)
+        registerAgentTrait(definition);
+}
+/** The definition for a trait id, or undefined when it is a pure marker / unregistered. */
+export function registeredAgentTrait(id) {
+    return traitRegistry.get(id);
+}
+/** Drop all registered (custom) traits. Intended for tests; standard traits re-register below. */
+export function clearRegisteredAgentTraits() {
+    traitRegistry.clear();
+    registerStandardTraits();
+}
+/** The traits a kind carries: its built-in set unioned with a registered custom kind's. */
+export function traitsFor(kind) {
+    const traits = new Set(STANDARD_AGENT_TRAITS[kind] ?? []);
+    for (const trait of registeredAgentKind(kind)?.traits ?? [])
+        traits.add(trait);
+    return traits;
+}
+/** Whether `kind` carries `trait`. */
+export function hasTrait(kind, trait) {
+    return traitsFor(kind).has(trait);
+}
+/**
+ * The guidance lines contributed by the traits a kind carries, in trait order. Folded
+ * into the kind's system prompt by `systemPromptFor`. Marker traits (no guidance, e.g.
+ * `code-aware`) contribute nothing here.
+ */
+export function traitGuidanceFor(kind) {
+    const lines = [];
+    for (const trait of traitsFor(kind)) {
+        const guidance = traitRegistry.get(trait)?.guidance;
+        if (!guidance)
+            continue;
+        lines.push(typeof guidance === 'function' ? guidance(kind) : guidance);
+    }
+    return lines;
+}
+/** Register the two standard traits' definitions (spec-aware carries guidance). */
+function registerStandardTraits() {
+    registerAgentTrait({ id: CODE_AWARE_TRAIT });
+    registerAgentTrait({ id: SPEC_AWARE_TRAIT, guidance: SPEC_AWARE_GUIDANCE });
+}
+registerStandardTraits();
+//# sourceMappingURL=traits.js.map

package/dist/agents/traits.js.map

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

package/dist/agents/web-search.d.ts

@@ -0,0 +1,43 @@
+import type { ToolSet } from 'ai';
+/** Default inline kinds allowed to search the web — the design/research steps. */
+export declare const DEFAULT_INLINE_WEB_SEARCH_KINDS: ReadonlySet<string>;
+/** Default ceiling on provider web searches per inline run (Anthropic `maxUses`). */
+export declare const DEFAULT_INLINE_WEB_SEARCH_MAX_USES = 5;
+/** How inline web search is configured for a deployment (off unless built). */
+export interface InlineWebSearchOptions {
+    /** Agent kinds permitted to use provider web search. */
+    kinds: ReadonlySet<string>;
+    /** Max provider web searches per run (Anthropic `maxUses`; OpenAI manages its own). */
+    maxUses: number;
+}
+/**
+ * The web-search guidance appended to an agent's context ONLY when the tools are
+ * actually available, so the model is never told about a tool it lacks. The hint is
+ * tailored to `kind`; `fetch` controls whether the companion `web_fetch` tool (the Pi
+ * container path has it; the inline provider tool does not) is mentioned. Mirrors the
+ * harness's own conservative framing: search is for things that change or that the
+ * agent is unsure of, not a reflex, and never a substitute for reading the code.
+ */
+export declare function webResearchGuidanceFor(kind: string, opts?: {
+    fetch?: boolean;
+}): string;
+/**
+ * The provider-hosted web_search tool set for a provider, or undefined when the
+ * provider has no server-executed web search the AI SDK can run inline. Only the
+ * provider id is consulted — the actual search runs under the model request's own
+ * credentials, so this just selects the right provider-defined tool spec.
+ */
+export declare function providerWebSearchTools(provider: string, maxUses?: number): ToolSet | undefined;
+/**
+ * Read inline web-search configuration from a deployment's environment, or
+ * undefined when it is not enabled. `INLINE_WEB_SEARCH_ENABLED` (truthy) is the
+ * single opt-in switch; `INLINE_WEB_SEARCH_KINDS` (comma-separated) overrides the
+ * default architect/researcher allow-list, and `INLINE_WEB_SEARCH_MAX_USES` caps
+ * searches per run. Off ⇒ the inline agents run exactly as before.
+ */
+export declare function inlineWebSearchOptionsFromEnv(env: {
+    INLINE_WEB_SEARCH_ENABLED?: string;
+    INLINE_WEB_SEARCH_KINDS?: string;
+    INLINE_WEB_SEARCH_MAX_USES?: string;
+}): InlineWebSearchOptions | undefined;
+//# sourceMappingURL=web-search.d.ts.map

package/dist/agents/web-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../src/agents/web-search.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,IAAI,CAAA;AAWjC,kFAAkF;AAClF,eAAO,MAAM,+BAA+B,EAAE,WAAW,CAAC,MAAM,CAG9D,CAAA;AAEF,qFAAqF;AACrF,eAAO,MAAM,kCAAkC,IAAI,CAAA;AAEnD,+EAA+E;AAC/E,MAAM,WAAW,sBAAsB;IACrC,wDAAwD;IACxD,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC1B,uFAAuF;IACvF,OAAO,EAAE,MAAM,CAAA;CAChB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAiB3F;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,MAA2C,GACnD,OAAO,GAAG,SAAS,CAYrB;AAED;;;;;;GAMG;AACH,wBAAgB,6BAA6B,CAAC,GAAG,EAAE;IACjD,yBAAyB,CAAC,EAAE,MAAM,CAAA;IAClC,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,0BAA0B,CAAC,EAAE,MAAM,CAAA;CACpC,GAAG,sBAAsB,GAAG,SAAS,CAerC"}

package/dist/agents/web-search.js

@@ -0,0 +1,102 @@
+import { anthropic } from '@ai-sdk/anthropic';
+import { openai } from '@ai-sdk/openai';
+import { registeredWebResearchHint } from './registry.js';
+// Provider-hosted web search for the INLINE agents (architect / researcher), which
+// run a single `generateText` call via the AI SDK rather than going through the Pi
+// container harness. Anthropic and OpenAI expose a server-executed web_search tool
+// the SDK runs inline (the provider performs the search and folds the results into
+// the same response — no client-side tool loop), exactly how Claude Code and Codex
+// add web access. Providers without a hosted search (workers-ai, the
+// OpenAI-compatible trio, mock) get no tool, so those deployments run unchanged.
+/** Default inline kinds allowed to search the web — the design/research steps. */
+export const DEFAULT_INLINE_WEB_SEARCH_KINDS = new Set([
+    'architect',
+    'researcher',
+]);
+/** Default ceiling on provider web searches per inline run (Anthropic `maxUses`). */
+export const DEFAULT_INLINE_WEB_SEARCH_MAX_USES = 5;
+// Per-kind reason an agent reaches for web search, so the nudge speaks to what that
+// agent is actually doing rather than a generic "verify facts". These are the defaults
+// for the BUILT-IN kinds; a custom/proprietary kind supplies its own via the registry
+// (`AgentKindDefinition.webResearchHint`), which wins — so the shared composition here
+// never needs to know a proprietary kind exists. Resolution order is registry → these
+// built-in defaults → GENERIC_WEB_RESEARCH_HINT (see `webResearchGuidanceFor`).
+const BUILTIN_WEB_RESEARCH_HINTS = {
+    coder: 'confirm a current library/API signature before you rely on it, and check for a known breaking change when an import or call behaves unexpectedly',
+    'ci-fixer': "search the exact failing error message, or a dependency's changelog/known issues, to find the real fix instead of guessing at versions",
+    mocker: "fetch the real third-party API's reference (endpoints, status codes, payload shapes, error formats) so the stubs match production behaviour",
+    analysis: 'check whether a dependency is deprecated, end-of-life, or has a known CVE / newer major version when judging technical debt',
+    'business-documenter': 'verify domain or regulatory terminology when documenting business rules, so the captured rules use the correct, current vocabulary',
+    playwright: "confirm a current testing-framework or locator API when the project's version differs from what you remember",
+    architect: 'compare current library/framework options and their trade-offs, and verify a capability or version is real before you design around it',
+    researcher: 'this is your primary tool — survey prior art, candidate libraries, benchmarks and known pitfalls, and ground every recommendation in a cited source',
+};
+const GENERIC_WEB_RESEARCH_HINT = "verify a fact that genuinely changes — a library version, an API, a recent breaking change, a security advisory — when the repository itself can't answer it";
+/**
+ * The web-search guidance appended to an agent's context ONLY when the tools are
+ * actually available, so the model is never told about a tool it lacks. The hint is
+ * tailored to `kind`; `fetch` controls whether the companion `web_fetch` tool (the Pi
+ * container path has it; the inline provider tool does not) is mentioned. Mirrors the
+ * harness's own conservative framing: search is for things that change or that the
+ * agent is unsure of, not a reflex, and never a substitute for reading the code.
+ */
+export function webResearchGuidanceFor(kind, opts = {}) {
+    // A proprietary/custom kind's own hint wins (it knows its job; the shared library
+    // doesn't); then the built-in defaults; then the generic fallback.
+    const hint = registeredWebResearchHint(kind) ?? BUILTIN_WEB_RESEARCH_HINTS[kind] ?? GENERIC_WEB_RESEARCH_HINT;
+    const tools = opts.fetch
+        ? '`web_search` (titled result snippets for a query) and `web_fetch` (read a URL as text)'
+        : 'a `web_search` tool';
+    const them = opts.fetch ? 'them' : 'it';
+    return `
+
+## Web search (use sparingly)
+
+You have ${tools}. Use ${them} mainly to ${hint}. Prefer first-party documentation, and
+cite the source URL when a decision rests on what you find. Do not search for anything
+already in the checkout or the context you were given, and don't let searching replace
+reading the code.`;
+}
+/**
+ * The provider-hosted web_search tool set for a provider, or undefined when the
+ * provider has no server-executed web search the AI SDK can run inline. Only the
+ * provider id is consulted — the actual search runs under the model request's own
+ * credentials, so this just selects the right provider-defined tool spec.
+ */
+export function providerWebSearchTools(provider, maxUses = DEFAULT_INLINE_WEB_SEARCH_MAX_USES) {
+    if (provider === 'anthropic') {
+        return { web_search: anthropic.tools.webSearch_20250305({ maxUses }) };
+    }
+    if (provider === 'openai') {
+        // OpenAI's hosted search runs via the Responses API; `@ai-sdk/openai`'s default
+        // model uses it, so a standard `openai:gpt-…` model resolves correctly. The
+        // per-run cap isn't a tool parameter here (OpenAI manages its own budget), so
+        // `maxUses` only applies to the Anthropic tool above.
+        return { web_search: openai.tools.webSearch({}) };
+    }
+    return undefined;
+}
+/**
+ * Read inline web-search configuration from a deployment's environment, or
+ * undefined when it is not enabled. `INLINE_WEB_SEARCH_ENABLED` (truthy) is the
+ * single opt-in switch; `INLINE_WEB_SEARCH_KINDS` (comma-separated) overrides the
+ * default architect/researcher allow-list, and `INLINE_WEB_SEARCH_MAX_USES` caps
+ * searches per run. Off ⇒ the inline agents run exactly as before.
+ */
+export function inlineWebSearchOptionsFromEnv(env) {
+    const enabled = env.INLINE_WEB_SEARCH_ENABLED?.trim().toLowerCase();
+    if (enabled !== 'true' && enabled !== '1' && enabled !== 'yes')
+        return undefined;
+    const kindList = (env.INLINE_WEB_SEARCH_KINDS ?? '')
+        .split(',')
+        .map((k) => k.trim().toLowerCase())
+        .filter(Boolean);
+    const maxUses = Number(env.INLINE_WEB_SEARCH_MAX_USES);
+    return {
+        kinds: kindList.length ? new Set(kindList) : DEFAULT_INLINE_WEB_SEARCH_KINDS,
+        maxUses: Number.isFinite(maxUses) && maxUses > 0
+            ? Math.floor(maxUses)
+            : DEFAULT_INLINE_WEB_SEARCH_MAX_USES,
+    };
+}
+//# sourceMappingURL=web-search.js.map

package/dist/agents/web-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../src/agents/web-search.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAEvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAEzD,mFAAmF;AACnF,mFAAmF;AACnF,mFAAmF;AACnF,mFAAmF;AACnF,mFAAmF;AACnF,qEAAqE;AACrE,iFAAiF;AAEjF,kFAAkF;AAClF,MAAM,CAAC,MAAM,+BAA+B,GAAwB,IAAI,GAAG,CAAC;IAC1E,WAAW;IACX,YAAY;CACb,CAAC,CAAA;AAEF,qFAAqF;AACrF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAAC,CAAA;AAUnD,oFAAoF;AACpF,uFAAuF;AACvF,sFAAsF;AACtF,uFAAuF;AACvF,sFAAsF;AACtF,gFAAgF;AAChF,MAAM,0BAA0B,GAA2B;IACzD,KAAK,EACH,kJAAkJ;IACpJ,UAAU,EACR,wIAAwI;IAC1I,MAAM,EACJ,6IAA6I;IAC/I,QAAQ,EACN,6HAA6H;IAC/H,qBAAqB,EACnB,oIAAoI;IACtI,UAAU,EACR,8GAA8G;IAChH,SAAS,EACP,wIAAwI;IAC1I,UAAU,EACR,qJAAqJ;CACxJ,CAAA;AAED,MAAM,yBAAyB,GAC7B,8JAA8J,CAAA;AAEhK;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY,EAAE,IAAI,GAAwB,EAAE;IACjF,kFAAkF;IAClF,mEAAmE;IACnE,MAAM,IAAI,GACR,yBAAyB,CAAC,IAAI,CAAC,IAAI,0BAA0B,CAAC,IAAI,CAAC,IAAI,yBAAyB,CAAA;IAClG,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK;QACtB,CAAC,CAAC,wFAAwF;QAC1F,CAAC,CAAC,qBAAqB,CAAA;IACzB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAA;IACvC,OAAO;;;;WAIE,KAAK,SAAS,IAAI,cAAc,IAAI;;;kBAG7B,CAAA;AAClB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAAgB,EAChB,OAAO,GAAW,kCAAkC;IAEpD,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC7B,OAAO,EAAE,UAAU,EAAE,SAAS,CAAC,KAAK,CAAC,kBAAkB,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAA;IACxE,CAAC;IACD,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,gFAAgF;QAChF,4EAA4E;QAC5E,8EAA8E;QAC9E,sDAAsD;QACtD,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAA;IACnD,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,6BAA6B,CAAC,GAI7C;IACC,MAAM,OAAO,GAAG,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACnE,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,GAAG,IAAI,OAAO,KAAK,KAAK;QAAE,OAAO,SAAS,CAAA;IAChF,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,uBAAuB,IAAI,EAAE,CAAC;SACjD,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;SAClC,MAAM,CAAC,OAAO,CAAC,CAAA;IAClB,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;IACtD,OAAO;QACL,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,+BAA+B;QAC5E,OAAO,EACL,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;YACrC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;YACrB,CAAC,CAAC,kCAAkC;KACzC,CAAA;AACH,CAAC"}

package/dist/fragmentLibrary/DeterministicFragmentSelector.d.ts

@@ -0,0 +1,10 @@
+import type { FragmentSelectionContext, FragmentSelector, SelectableFragment } from '@cat-factory/kernel';
+/**
+ * The built-in {@link FragmentSelector}: matches on `appliesTo` + tag overlap
+ * with no model call. It is the default when the library module is wired without
+ * an LLM selector, and the fallback an LLM selector degrades to. See ADR 0006 §5.
+ */
+export declare class DeterministicFragmentSelector implements FragmentSelector {
+    select(candidates: SelectableFragment[], context: FragmentSelectionContext): Promise<string[]>;
+}
+//# sourceMappingURL=DeterministicFragmentSelector.d.ts.map

package/dist/fragmentLibrary/DeterministicFragmentSelector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeterministicFragmentSelector.d.ts","sourceRoot":"","sources":["../../src/fragmentLibrary/DeterministicFragmentSelector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,gBAAgB,EAChB,kBAAkB,EACnB,MAAM,qBAAqB,CAAA;AAG5B;;;;GAIG;AACH,qBAAa,6BAA8B,YAAW,gBAAgB;IAC9D,MAAM,CACV,UAAU,EAAE,kBAAkB,EAAE,EAChC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,MAAM,EAAE,CAAC,CAEnB;CACF"}

package/dist/fragmentLibrary/DeterministicFragmentSelector.js

@@ -0,0 +1,12 @@
+import { selectDeterministic } from './fragment-catalog.js';
+/**
+ * The built-in {@link FragmentSelector}: matches on `appliesTo` + tag overlap
+ * with no model call. It is the default when the library module is wired without
+ * an LLM selector, and the fallback an LLM selector degrades to. See ADR 0006 §5.
+ */
+export class DeterministicFragmentSelector {
+    async select(candidates, context) {
+        return selectDeterministic(candidates, context);
+    }
+}
+//# sourceMappingURL=DeterministicFragmentSelector.js.map

package/dist/fragmentLibrary/DeterministicFragmentSelector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeterministicFragmentSelector.js","sourceRoot":"","sources":["../../src/fragmentLibrary/DeterministicFragmentSelector.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAE3D;;;;GAIG;AACH,MAAM,OAAO,6BAA6B;IACxC,KAAK,CAAC,MAAM,CACV,UAAgC,EAChC,OAAiC;QAEjC,OAAO,mBAAmB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAA;IACjD,CAAC;CACF"}

package/dist/fragmentLibrary/FragmentLibraryService.d.ts

@@ -0,0 +1,55 @@
+import type { PromptFragment } from '@cat-factory/contracts';
+import type { CreatePromptFragmentInput, FragmentOwnerKind, ResolvedFragment, UpdatePromptFragmentInput } from '@cat-factory/kernel';
+import type { Clock } from '@cat-factory/kernel';
+import type { FragmentSelector, FragmentResolver, FragmentResolverInput, FragmentRunSelection } from '@cat-factory/kernel';
+import type { PromptFragmentRepository } from '@cat-factory/kernel';
+import type { WorkspaceRepository } from '@cat-factory/kernel';
+import { type ResolvedCatalogEntry } from './fragment-catalog.js';
+export interface FragmentLibraryServiceDependencies {
+    promptFragmentRepository: PromptFragmentRepository;
+    workspaceRepository: WorkspaceRepository;
+    clock: Clock;
+    /** Relevance selector; defaults to the deterministic matcher when omitted. */
+    selector?: FragmentSelector;
+    /** Built-in catalog tier; overridable for tests. Defaults to the shipped FRAGMENTS. */
+    builtins?: PromptFragment[];
+}
+/**
+ * The fragment library's management service (ADR 0006). It owns the per-tier CRUD
+ * (account / workspace) and resolves the merged catalog a workspace sees (built-in ∪
+ * account ∪ workspace, override-by-id, tombstone-suppressed). It still implements
+ * {@link FragmentResolver} (`resolveForRun`), but the execution engine NO LONGER
+ * consumes it: fragment delivery is now the service-scoped `serviceFragmentIds` folded
+ * into `code-aware` agents, so this is a management surface only.
+ */
+export declare class FragmentLibraryService implements FragmentResolver {
+    private readonly repo;
+    private readonly workspaces;
+    private readonly clock;
+    private readonly selector;
+    private readonly builtins;
+    constructor(deps: FragmentLibraryServiceDependencies);
+    /** This tier's hand-authored/sourced fragments (raw, not merged), newest first. */
+    listTier(ownerKind: FragmentOwnerKind, ownerId: string): Promise<PromptFragment[]>;
+    /** Create a hand-authored fragment at a tier. */
+    create(ownerKind: FragmentOwnerKind, ownerId: string, input: CreatePromptFragmentInput): Promise<PromptFragment>;
+    /**
+     * Edit a fragment at a tier. If no row exists yet (e.g. shadowing a built-in or
+     * inherited account fragment), the patch must carry enough to stand alone
+     * (title, summary, body); otherwise it merges over the existing record.
+     */
+    update(ownerKind: FragmentOwnerKind, ownerId: string, fragmentId: string, patch: UpdatePromptFragmentInput): Promise<PromptFragment>;
+    /**
+     * Tombstone a fragment at a tier. Suppresses an inherited built-in/account
+     * fragment, or removes a hand-authored one. Idempotent — writing a tombstone
+     * even when no row exists yet, so a tier can suppress something it inherits.
+     */
+    remove(ownerKind: FragmentOwnerKind, ownerId: string, fragmentId: string): Promise<void>;
+    /** Resolve the merged catalog a workspace sees (built-in ∪ account ∪ workspace). */
+    resolveCatalog(workspaceId: string): Promise<ResolvedCatalogEntry[]>;
+    /** The merged catalog as wire {@link ResolvedFragment}s for the management UI. */
+    resolvedCatalog(workspaceId: string): Promise<ResolvedFragment[]>;
+    /** {@link FragmentResolver}: pick + resolve the fragments to inject for a run. */
+    resolveForRun(input: FragmentResolverInput): Promise<FragmentRunSelection>;
+}
+//# sourceMappingURL=FragmentLibraryService.d.ts.map

package/dist/fragmentLibrary/FragmentLibraryService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FragmentLibraryService.d.ts","sourceRoot":"","sources":["../../src/fragmentLibrary/FragmentLibraryService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EACV,yBAAyB,EACzB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EAC1B,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAA;AAChD,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAwB,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AACzF,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9D,OAAO,EACL,KAAK,oBAAoB,EAI1B,MAAM,uBAAuB,CAAA;AAG9B,MAAM,WAAW,kCAAkC;IACjD,wBAAwB,EAAE,wBAAwB,CAAA;IAClD,mBAAmB,EAAE,mBAAmB,CAAA;IACxC,KAAK,EAAE,KAAK,CAAA;IACZ,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,uFAAuF;IACvF,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAA;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,sBAAuB,YAAW,gBAAgB;IAC7D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAO;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAkB;IAE3C,YAAY,IAAI,EAAE,kCAAkC,EAMnD;IAED,mFAAmF;IAC7E,QAAQ,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAGvF;IAED,iDAAiD;IAC3C,MAAM,CACV,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAwBzB;IAED;;;;OAIG;IACG,MAAM,CACV,SAAS,EAAE,iBAAiB,EAC5B,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,cAAc,CAAC,CAsCzB;IAED;;;;OAIG;IACG,MAAM,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAyB7F;IAED,oFAAoF;IAC9E,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAOzE;IAED,kFAAkF;IAC5E,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAGtE;IAED,kFAAkF;IAC5E,aAAa,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAkC/E;CACF"}