@cat-factory/agents 0.6.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (85) hide show
  1. package/LICENSE +21 -21
  2. package/dist/agents/prompts/roles.js +1 -1
  3. package/dist/agents/prompts/roles.js.map +1 -1
  4. package/dist/agents/runtime/web-search.js +7 -7
  5. package/package.json +9 -4
  6. package/dist/agents/AiAgentExecutor.d.ts +0 -72
  7. package/dist/agents/AiAgentExecutor.d.ts.map +0 -1
  8. package/dist/agents/AiAgentExecutor.js +0 -125
  9. package/dist/agents/AiAgentExecutor.js.map +0 -1
  10. package/dist/agents/acceptance-prompts.d.ts +0 -29
  11. package/dist/agents/acceptance-prompts.d.ts.map +0 -1
  12. package/dist/agents/acceptance-prompts.js +0 -112
  13. package/dist/agents/acceptance-prompts.js.map +0 -1
  14. package/dist/agents/agent-catalog.d.ts +0 -6
  15. package/dist/agents/agent-catalog.d.ts.map +0 -1
  16. package/dist/agents/agent-catalog.js +0 -197
  17. package/dist/agents/agent-catalog.js.map +0 -1
  18. package/dist/agents/agent-configs.d.ts +0 -17
  19. package/dist/agents/agent-configs.d.ts.map +0 -1
  20. package/dist/agents/agent-configs.js +0 -66
  21. package/dist/agents/agent-configs.js.map +0 -1
  22. package/dist/agents/agent-routing.d.ts +0 -57
  23. package/dist/agents/agent-routing.d.ts.map +0 -1
  24. package/dist/agents/agent-routing.js +0 -41
  25. package/dist/agents/agent-routing.js.map +0 -1
  26. package/dist/agents/business-logic-prompts.d.ts +0 -28
  27. package/dist/agents/business-logic-prompts.d.ts.map +0 -1
  28. package/dist/agents/business-logic-prompts.js +0 -96
  29. package/dist/agents/business-logic-prompts.js.map +0 -1
  30. package/dist/agents/ci-gate.d.ts +0 -2
  31. package/dist/agents/ci-gate.d.ts.map +0 -1
  32. package/dist/agents/ci-gate.js +0 -33
  33. package/dist/agents/ci-gate.js.map +0 -1
  34. package/dist/agents/companion-prompts.d.ts +0 -4
  35. package/dist/agents/companion-prompts.d.ts.map +0 -1
  36. package/dist/agents/companion-prompts.js +0 -27
  37. package/dist/agents/companion-prompts.js.map +0 -1
  38. package/dist/agents/companions.d.ts +0 -20
  39. package/dist/agents/companions.d.ts.map +0 -1
  40. package/dist/agents/companions.js +0 -38
  41. package/dist/agents/companions.js.map +0 -1
  42. package/dist/agents/mock-prompts.d.ts +0 -12
  43. package/dist/agents/mock-prompts.d.ts.map +0 -1
  44. package/dist/agents/mock-prompts.js +0 -61
  45. package/dist/agents/mock-prompts.js.map +0 -1
  46. package/dist/agents/prompt-fragments.d.ts +0 -17
  47. package/dist/agents/prompt-fragments.d.ts.map +0 -1
  48. package/dist/agents/prompt-fragments.js +0 -33
  49. package/dist/agents/prompt-fragments.js.map +0 -1
  50. package/dist/agents/prompt-shared.d.ts +0 -7
  51. package/dist/agents/prompt-shared.d.ts.map +0 -1
  52. package/dist/agents/prompt-shared.js +0 -10
  53. package/dist/agents/prompt-shared.js.map +0 -1
  54. package/dist/agents/prompt-versions.d.ts +0 -48
  55. package/dist/agents/prompt-versions.d.ts.map +0 -1
  56. package/dist/agents/prompt-versions.js +0 -55
  57. package/dist/agents/prompt-versions.js.map +0 -1
  58. package/dist/agents/read-only.d.ts +0 -13
  59. package/dist/agents/read-only.d.ts.map +0 -1
  60. package/dist/agents/read-only.js +0 -29
  61. package/dist/agents/read-only.js.map +0 -1
  62. package/dist/agents/registry.d.ts +0 -70
  63. package/dist/agents/registry.d.ts.map +0 -1
  64. package/dist/agents/registry.js +0 -51
  65. package/dist/agents/registry.js.map +0 -1
  66. package/dist/agents/standard-prompt-templates.generated.d.ts +0 -36
  67. package/dist/agents/standard-prompt-templates.generated.d.ts.map +0 -1
  68. package/dist/agents/standard-prompt-templates.generated.js +0 -122
  69. package/dist/agents/standard-prompt-templates.generated.js.map +0 -1
  70. package/dist/agents/standard-prompts.d.ts +0 -36
  71. package/dist/agents/standard-prompts.d.ts.map +0 -1
  72. package/dist/agents/standard-prompts.js +0 -202
  73. package/dist/agents/standard-prompts.js.map +0 -1
  74. package/dist/agents/test-prompts.d.ts +0 -12
  75. package/dist/agents/test-prompts.d.ts.map +0 -1
  76. package/dist/agents/test-prompts.js +0 -92
  77. package/dist/agents/test-prompts.js.map +0 -1
  78. package/dist/agents/traits.d.ts +0 -56
  79. package/dist/agents/traits.d.ts.map +0 -1
  80. package/dist/agents/traits.js +0 -100
  81. package/dist/agents/traits.js.map +0 -1
  82. package/dist/agents/web-search.d.ts +0 -43
  83. package/dist/agents/web-search.d.ts.map +0 -1
  84. package/dist/agents/web-search.js +0 -102
  85. package/dist/agents/web-search.js.map +0 -1
@@ -1,100 +0,0 @@
1
- import { SPEC_FEATURES_DIR, SPEC_JSON_PATH, SPEC_OVERVIEW_PATH, SPEC_RULES_PATH, } from '@cat-factory/contracts';
2
- import { registeredAgentKind } from './registry.js';
3
- /**
4
- * Code-aware kinds read and/or change the service's code. The service's selected
5
- * best-practice / guideline fragments (Node, Fastify, performance, …) are folded into
6
- * their system prompt by the execution engine.
7
- */
8
- export const CODE_AWARE_TRAIT = 'code-aware';
9
- /**
10
- * Spec-aware kinds are told to read the in-repo `spec/` artifact (the prescriptive
11
- * service specification) and how to interpret it. The instruction is appended to their
12
- * system prompt via {@link traitGuidanceFor}.
13
- */
14
- export const SPEC_AWARE_TRAIT = 'spec-aware';
15
- /** The guidance appended to a spec-aware kind's system prompt — explains the spec format. */
16
- export const SPEC_AWARE_GUIDANCE = [
17
- `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:`,
18
- `- \`${SPEC_OVERVIEW_PATH}\` first, for the high-level product intent.`,
19
- `- \`${SPEC_RULES_PATH}\` for cross-cutting domain rules, invariants and constraints.`,
20
- `- \`${SPEC_FEATURES_DIR}/*.feature\` for the Gherkin (Given/When/Then) acceptance scenarios.`,
21
- `- \`${SPEC_JSON_PATH}\` is the canonical machine-readable tree the markdown/feature files are rendered from; consult it when you need exact detail.`,
22
- `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.`,
23
- ].join('\n');
24
- /**
25
- * Built-in trait assignment per agent kind.
26
- * - `code-aware`: the kinds that read/modify the service's code, so the service's
27
- * best-practice fragments are relevant to them.
28
- * - `spec-aware`: every code-touching kind (anything that clones and reads the repo),
29
- * so each is pointed at the in-repo spec. The `spec-writer` is intentionally absent —
30
- * it AUTHORS the spec rather than consuming it.
31
- */
32
- export const STANDARD_AGENT_TRAITS = {
33
- architect: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
34
- coder: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
35
- reviewer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
36
- 'ci-fixer': [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
37
- fixer: [CODE_AWARE_TRAIT, SPEC_AWARE_TRAIT],
38
- 'conflict-resolver': [SPEC_AWARE_TRAIT],
39
- tester: [SPEC_AWARE_TRAIT],
40
- playwright: [SPEC_AWARE_TRAIT],
41
- blueprints: [SPEC_AWARE_TRAIT],
42
- 'business-documenter': [SPEC_AWARE_TRAIT],
43
- 'business-reviewer': [SPEC_AWARE_TRAIT],
44
- analysis: [SPEC_AWARE_TRAIT],
45
- mocker: [SPEC_AWARE_TRAIT],
46
- merger: [SPEC_AWARE_TRAIT],
47
- };
48
- // Process-wide trait registry, mirroring the agent-kind / model-provider registries.
49
- const traitRegistry = new Map();
50
- /** Register a custom trait definition. A later registration of the same id replaces it. */
51
- export function registerAgentTrait(definition) {
52
- traitRegistry.set(definition.id, definition);
53
- }
54
- /** Register several custom trait definitions at once. */
55
- export function registerAgentTraits(definitions) {
56
- for (const definition of definitions)
57
- registerAgentTrait(definition);
58
- }
59
- /** The definition for a trait id, or undefined when it is a pure marker / unregistered. */
60
- export function registeredAgentTrait(id) {
61
- return traitRegistry.get(id);
62
- }
63
- /** Drop all registered (custom) traits. Intended for tests; standard traits re-register below. */
64
- export function clearRegisteredAgentTraits() {
65
- traitRegistry.clear();
66
- registerStandardTraits();
67
- }
68
- /** The traits a kind carries: its built-in set unioned with a registered custom kind's. */
69
- export function traitsFor(kind) {
70
- const traits = new Set(STANDARD_AGENT_TRAITS[kind] ?? []);
71
- for (const trait of registeredAgentKind(kind)?.traits ?? [])
72
- traits.add(trait);
73
- return traits;
74
- }
75
- /** Whether `kind` carries `trait`. */
76
- export function hasTrait(kind, trait) {
77
- return traitsFor(kind).has(trait);
78
- }
79
- /**
80
- * The guidance lines contributed by the traits a kind carries, in trait order. Folded
81
- * into the kind's system prompt by `systemPromptFor`. Marker traits (no guidance, e.g.
82
- * `code-aware`) contribute nothing here.
83
- */
84
- export function traitGuidanceFor(kind) {
85
- const lines = [];
86
- for (const trait of traitsFor(kind)) {
87
- const guidance = traitRegistry.get(trait)?.guidance;
88
- if (!guidance)
89
- continue;
90
- lines.push(typeof guidance === 'function' ? guidance(kind) : guidance);
91
- }
92
- return lines;
93
- }
94
- /** Register the two standard traits' definitions (spec-aware carries guidance). */
95
- function registerStandardTraits() {
96
- registerAgentTrait({ id: CODE_AWARE_TRAIT });
97
- registerAgentTrait({ id: SPEC_AWARE_TRAIT, guidance: SPEC_AWARE_GUIDANCE });
98
- }
99
- registerStandardTraits();
100
- //# sourceMappingURL=traits.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"traits.js","sourceRoot":"","sources":["../../src/agents/traits.ts"],"names":[],"mappings":"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"}
@@ -1,43 +0,0 @@
1
- import type { ToolSet } from 'ai';
2
- /** Default inline kinds allowed to search the web — the design/research steps. */
3
- export declare const DEFAULT_INLINE_WEB_SEARCH_KINDS: ReadonlySet<string>;
4
- /** Default ceiling on provider web searches per inline run (Anthropic `maxUses`). */
5
- export declare const DEFAULT_INLINE_WEB_SEARCH_MAX_USES = 5;
6
- /** How inline web search is configured for a deployment (off unless built). */
7
- export interface InlineWebSearchOptions {
8
- /** Agent kinds permitted to use provider web search. */
9
- kinds: ReadonlySet<string>;
10
- /** Max provider web searches per run (Anthropic `maxUses`; OpenAI manages its own). */
11
- maxUses: number;
12
- }
13
- /**
14
- * The web-search guidance appended to an agent's context ONLY when the tools are
15
- * actually available, so the model is never told about a tool it lacks. The hint is
16
- * tailored to `kind`; `fetch` controls whether the companion `web_fetch` tool (the Pi
17
- * container path has it; the inline provider tool does not) is mentioned. Mirrors the
18
- * harness's own conservative framing: search is for things that change or that the
19
- * agent is unsure of, not a reflex, and never a substitute for reading the code.
20
- */
21
- export declare function webResearchGuidanceFor(kind: string, opts?: {
22
- fetch?: boolean;
23
- }): string;
24
- /**
25
- * The provider-hosted web_search tool set for a provider, or undefined when the
26
- * provider has no server-executed web search the AI SDK can run inline. Only the
27
- * provider id is consulted — the actual search runs under the model request's own
28
- * credentials, so this just selects the right provider-defined tool spec.
29
- */
30
- export declare function providerWebSearchTools(provider: string, maxUses?: number): ToolSet | undefined;
31
- /**
32
- * Read inline web-search configuration from a deployment's environment, or
33
- * undefined when it is not enabled. `INLINE_WEB_SEARCH_ENABLED` (truthy) is the
34
- * single opt-in switch; `INLINE_WEB_SEARCH_KINDS` (comma-separated) overrides the
35
- * default architect/researcher allow-list, and `INLINE_WEB_SEARCH_MAX_USES` caps
36
- * searches per run. Off ⇒ the inline agents run exactly as before.
37
- */
38
- export declare function inlineWebSearchOptionsFromEnv(env: {
39
- INLINE_WEB_SEARCH_ENABLED?: string;
40
- INLINE_WEB_SEARCH_KINDS?: string;
41
- INLINE_WEB_SEARCH_MAX_USES?: string;
42
- }): InlineWebSearchOptions | undefined;
43
- //# sourceMappingURL=web-search.d.ts.map
@@ -1 +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"}
@@ -1,102 +0,0 @@
1
- import { anthropic } from '@ai-sdk/anthropic';
2
- import { openai } from '@ai-sdk/openai';
3
- import { registeredWebResearchHint } from './registry.js';
4
- // Provider-hosted web search for the INLINE agents (architect / researcher), which
5
- // run a single `generateText` call via the AI SDK rather than going through the Pi
6
- // container harness. Anthropic and OpenAI expose a server-executed web_search tool
7
- // the SDK runs inline (the provider performs the search and folds the results into
8
- // the same response — no client-side tool loop), exactly how Claude Code and Codex
9
- // add web access. Providers without a hosted search (workers-ai, the
10
- // OpenAI-compatible trio, mock) get no tool, so those deployments run unchanged.
11
- /** Default inline kinds allowed to search the web — the design/research steps. */
12
- export const DEFAULT_INLINE_WEB_SEARCH_KINDS = new Set([
13
- 'architect',
14
- 'researcher',
15
- ]);
16
- /** Default ceiling on provider web searches per inline run (Anthropic `maxUses`). */
17
- export const DEFAULT_INLINE_WEB_SEARCH_MAX_USES = 5;
18
- // Per-kind reason an agent reaches for web search, so the nudge speaks to what that
19
- // agent is actually doing rather than a generic "verify facts". These are the defaults
20
- // for the BUILT-IN kinds; a custom/proprietary kind supplies its own via the registry
21
- // (`AgentKindDefinition.webResearchHint`), which wins — so the shared composition here
22
- // never needs to know a proprietary kind exists. Resolution order is registry → these
23
- // built-in defaults → GENERIC_WEB_RESEARCH_HINT (see `webResearchGuidanceFor`).
24
- const BUILTIN_WEB_RESEARCH_HINTS = {
25
- 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',
26
- '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",
27
- mocker: "fetch the real third-party API's reference (endpoints, status codes, payload shapes, error formats) so the stubs match production behaviour",
28
- analysis: 'check whether a dependency is deprecated, end-of-life, or has a known CVE / newer major version when judging technical debt',
29
- 'business-documenter': 'verify domain or regulatory terminology when documenting business rules, so the captured rules use the correct, current vocabulary',
30
- playwright: "confirm a current testing-framework or locator API when the project's version differs from what you remember",
31
- architect: 'compare current library/framework options and their trade-offs, and verify a capability or version is real before you design around it',
32
- researcher: 'this is your primary tool — survey prior art, candidate libraries, benchmarks and known pitfalls, and ground every recommendation in a cited source',
33
- };
34
- 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";
35
- /**
36
- * The web-search guidance appended to an agent's context ONLY when the tools are
37
- * actually available, so the model is never told about a tool it lacks. The hint is
38
- * tailored to `kind`; `fetch` controls whether the companion `web_fetch` tool (the Pi
39
- * container path has it; the inline provider tool does not) is mentioned. Mirrors the
40
- * harness's own conservative framing: search is for things that change or that the
41
- * agent is unsure of, not a reflex, and never a substitute for reading the code.
42
- */
43
- export function webResearchGuidanceFor(kind, opts = {}) {
44
- // A proprietary/custom kind's own hint wins (it knows its job; the shared library
45
- // doesn't); then the built-in defaults; then the generic fallback.
46
- const hint = registeredWebResearchHint(kind) ?? BUILTIN_WEB_RESEARCH_HINTS[kind] ?? GENERIC_WEB_RESEARCH_HINT;
47
- const tools = opts.fetch
48
- ? '`web_search` (titled result snippets for a query) and `web_fetch` (read a URL as text)'
49
- : 'a `web_search` tool';
50
- const them = opts.fetch ? 'them' : 'it';
51
- return `
52
-
53
- ## Web search (use sparingly)
54
-
55
- You have ${tools}. Use ${them} mainly to ${hint}. Prefer first-party documentation, and
56
- cite the source URL when a decision rests on what you find. Do not search for anything
57
- already in the checkout or the context you were given, and don't let searching replace
58
- reading the code.`;
59
- }
60
- /**
61
- * The provider-hosted web_search tool set for a provider, or undefined when the
62
- * provider has no server-executed web search the AI SDK can run inline. Only the
63
- * provider id is consulted — the actual search runs under the model request's own
64
- * credentials, so this just selects the right provider-defined tool spec.
65
- */
66
- export function providerWebSearchTools(provider, maxUses = DEFAULT_INLINE_WEB_SEARCH_MAX_USES) {
67
- if (provider === 'anthropic') {
68
- return { web_search: anthropic.tools.webSearch_20250305({ maxUses }) };
69
- }
70
- if (provider === 'openai') {
71
- // OpenAI's hosted search runs via the Responses API; `@ai-sdk/openai`'s default
72
- // model uses it, so a standard `openai:gpt-…` model resolves correctly. The
73
- // per-run cap isn't a tool parameter here (OpenAI manages its own budget), so
74
- // `maxUses` only applies to the Anthropic tool above.
75
- return { web_search: openai.tools.webSearch({}) };
76
- }
77
- return undefined;
78
- }
79
- /**
80
- * Read inline web-search configuration from a deployment's environment, or
81
- * undefined when it is not enabled. `INLINE_WEB_SEARCH_ENABLED` (truthy) is the
82
- * single opt-in switch; `INLINE_WEB_SEARCH_KINDS` (comma-separated) overrides the
83
- * default architect/researcher allow-list, and `INLINE_WEB_SEARCH_MAX_USES` caps
84
- * searches per run. Off ⇒ the inline agents run exactly as before.
85
- */
86
- export function inlineWebSearchOptionsFromEnv(env) {
87
- const enabled = env.INLINE_WEB_SEARCH_ENABLED?.trim().toLowerCase();
88
- if (enabled !== 'true' && enabled !== '1' && enabled !== 'yes')
89
- return undefined;
90
- const kindList = (env.INLINE_WEB_SEARCH_KINDS ?? '')
91
- .split(',')
92
- .map((k) => k.trim().toLowerCase())
93
- .filter(Boolean);
94
- const maxUses = Number(env.INLINE_WEB_SEARCH_MAX_USES);
95
- return {
96
- kinds: kindList.length ? new Set(kindList) : DEFAULT_INLINE_WEB_SEARCH_KINDS,
97
- maxUses: Number.isFinite(maxUses) && maxUses > 0
98
- ? Math.floor(maxUses)
99
- : DEFAULT_INLINE_WEB_SEARCH_MAX_USES,
100
- };
101
- }
102
- //# sourceMappingURL=web-search.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"web-search.js","sourceRoot":"","sources":["../../src/agents/web-search.ts"],"names":[],"mappings":"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"}