@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.
- package/LICENSE +21 -21
- package/dist/agents/prompts/roles.js +1 -1
- package/dist/agents/prompts/roles.js.map +1 -1
- package/dist/agents/runtime/web-search.js +7 -7
- package/package.json +9 -4
- package/dist/agents/AiAgentExecutor.d.ts +0 -72
- package/dist/agents/AiAgentExecutor.d.ts.map +0 -1
- package/dist/agents/AiAgentExecutor.js +0 -125
- package/dist/agents/AiAgentExecutor.js.map +0 -1
- package/dist/agents/acceptance-prompts.d.ts +0 -29
- package/dist/agents/acceptance-prompts.d.ts.map +0 -1
- package/dist/agents/acceptance-prompts.js +0 -112
- package/dist/agents/acceptance-prompts.js.map +0 -1
- package/dist/agents/agent-catalog.d.ts +0 -6
- package/dist/agents/agent-catalog.d.ts.map +0 -1
- package/dist/agents/agent-catalog.js +0 -197
- package/dist/agents/agent-catalog.js.map +0 -1
- package/dist/agents/agent-configs.d.ts +0 -17
- package/dist/agents/agent-configs.d.ts.map +0 -1
- package/dist/agents/agent-configs.js +0 -66
- package/dist/agents/agent-configs.js.map +0 -1
- package/dist/agents/agent-routing.d.ts +0 -57
- package/dist/agents/agent-routing.d.ts.map +0 -1
- package/dist/agents/agent-routing.js +0 -41
- package/dist/agents/agent-routing.js.map +0 -1
- package/dist/agents/business-logic-prompts.d.ts +0 -28
- package/dist/agents/business-logic-prompts.d.ts.map +0 -1
- package/dist/agents/business-logic-prompts.js +0 -96
- package/dist/agents/business-logic-prompts.js.map +0 -1
- package/dist/agents/ci-gate.d.ts +0 -2
- package/dist/agents/ci-gate.d.ts.map +0 -1
- package/dist/agents/ci-gate.js +0 -33
- package/dist/agents/ci-gate.js.map +0 -1
- package/dist/agents/companion-prompts.d.ts +0 -4
- package/dist/agents/companion-prompts.d.ts.map +0 -1
- package/dist/agents/companion-prompts.js +0 -27
- package/dist/agents/companion-prompts.js.map +0 -1
- package/dist/agents/companions.d.ts +0 -20
- package/dist/agents/companions.d.ts.map +0 -1
- package/dist/agents/companions.js +0 -38
- package/dist/agents/companions.js.map +0 -1
- package/dist/agents/mock-prompts.d.ts +0 -12
- package/dist/agents/mock-prompts.d.ts.map +0 -1
- package/dist/agents/mock-prompts.js +0 -61
- package/dist/agents/mock-prompts.js.map +0 -1
- package/dist/agents/prompt-fragments.d.ts +0 -17
- package/dist/agents/prompt-fragments.d.ts.map +0 -1
- package/dist/agents/prompt-fragments.js +0 -33
- package/dist/agents/prompt-fragments.js.map +0 -1
- package/dist/agents/prompt-shared.d.ts +0 -7
- package/dist/agents/prompt-shared.d.ts.map +0 -1
- package/dist/agents/prompt-shared.js +0 -10
- package/dist/agents/prompt-shared.js.map +0 -1
- package/dist/agents/prompt-versions.d.ts +0 -48
- package/dist/agents/prompt-versions.d.ts.map +0 -1
- package/dist/agents/prompt-versions.js +0 -55
- package/dist/agents/prompt-versions.js.map +0 -1
- package/dist/agents/read-only.d.ts +0 -13
- package/dist/agents/read-only.d.ts.map +0 -1
- package/dist/agents/read-only.js +0 -29
- package/dist/agents/read-only.js.map +0 -1
- package/dist/agents/registry.d.ts +0 -70
- package/dist/agents/registry.d.ts.map +0 -1
- package/dist/agents/registry.js +0 -51
- package/dist/agents/registry.js.map +0 -1
- package/dist/agents/standard-prompt-templates.generated.d.ts +0 -36
- package/dist/agents/standard-prompt-templates.generated.d.ts.map +0 -1
- package/dist/agents/standard-prompt-templates.generated.js +0 -122
- package/dist/agents/standard-prompt-templates.generated.js.map +0 -1
- package/dist/agents/standard-prompts.d.ts +0 -36
- package/dist/agents/standard-prompts.d.ts.map +0 -1
- package/dist/agents/standard-prompts.js +0 -202
- package/dist/agents/standard-prompts.js.map +0 -1
- package/dist/agents/test-prompts.d.ts +0 -12
- package/dist/agents/test-prompts.d.ts.map +0 -1
- package/dist/agents/test-prompts.js +0 -92
- package/dist/agents/test-prompts.js.map +0 -1
- package/dist/agents/traits.d.ts +0 -56
- package/dist/agents/traits.d.ts.map +0 -1
- package/dist/agents/traits.js +0 -100
- package/dist/agents/traits.js.map +0 -1
- package/dist/agents/web-search.d.ts +0 -43
- package/dist/agents/web-search.d.ts.map +0 -1
- package/dist/agents/web-search.js +0 -102
- package/dist/agents/web-search.js.map +0 -1
package/dist/agents/traits.js
DELETED
|
@@ -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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"}
|