@cat-factory/agents 0.6.0

package/dist/agents/read-only.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only.d.ts","sourceRoot":"","sources":["../../src/agents/read-only.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AAepD,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,aAA6C,CAAA;AAE/E,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAIiB,CAAA"}

package/dist/agents/read-only.js

@@ -0,0 +1,29 @@
+// Read-only container agents. Some agent kinds need a real checkout to do their
+// work but only ever READ it: they clone the repo, explore it, and return a prose
+// report/proposal — making no edits, no commits and opening no pull request. They
+// run through the harness `/explore` endpoint (not `/run`), where an edit-free run
+// is the expected, correct outcome rather than an "implementation produced no
+// changes" failure, and where no work branch or PR is created.
+//
+// Today that is the `architect` (proposes a design after reading the existing code,
+// whose prose proposal feeds the human gate / architect-companion) and the tech-debt
+// `analysis` agent (audits the repo and emits a prioritized report). Both share the
+// single reusable read-only execution path (see ContainerAgentExecutor's explore
+// body + the harness `handleExplore`).
+/** Container agent kinds that operate read-only (explore + report; no edits/commits/PR). */
+export const READ_ONLY_AGENT_KINDS = new Set(['architect', 'analysis']);
+/** Whether `kind` is a read-only container agent (runs the harness `/explore` path). */
+export function isReadOnlyAgentKind(kind) {
+    return READ_ONLY_AGENT_KINDS.has(kind);
+}
+/**
+ * Appended to a read-only agent's system prompt so it never tries to edit, commit or
+ * open a PR — the prose report it returns is its sole deliverable. Centralised here
+ * (rather than repeated in each role prompt) so every read-only kind states the same
+ * guardrail exactly once.
+ */
+export const READ_ONLY_GUARDRAIL = 'IMPORTANT — this is a READ-ONLY exploration: you may read and inspect any file in ' +
+    'the repository, but you MUST NOT modify, create or delete files, run commands that ' +
+    'change the repository, commit, or open a pull request. Your written report is the ' +
+    'only deliverable; return it as your response.';
+//# sourceMappingURL=read-only.js.map

package/dist/agents/read-only.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-only.js","sourceRoot":"","sources":["../../src/agents/read-only.ts"],"names":[],"mappings":"AAEA,gFAAgF;AAChF,kFAAkF;AAClF,kFAAkF;AAClF,mFAAmF;AACnF,8EAA8E;AAC9E,+DAA+D;AAC/D,EAAE;AACF,oFAAoF;AACpF,qFAAqF;AACrF,oFAAoF;AACpF,iFAAiF;AACjF,uCAAuC;AAEvC,4FAA4F;AAC5F,MAAM,CAAC,MAAM,qBAAqB,GAAG,IAAI,GAAG,CAAS,CAAC,WAAW,EAAE,UAAU,CAAC,CAAC,CAAA;AAE/E,wFAAwF;AACxF,MAAM,UAAU,mBAAmB,CAAC,IAAe;IACjD,OAAO,qBAAqB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACxC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,oFAAoF;IACpF,qFAAqF;IACrF,oFAAoF;IACpF,+CAA+C,CAAA"}

package/dist/agents/registry.d.ts

@@ -0,0 +1,70 @@
+import type { AgentConfigDescriptor, AgentKind, AgentRunContext } from '@cat-factory/kernel';
+import type { AgentTrait } from './traits.js';
+export interface AgentKindDefinition {
+    /** The free-form agent-kind id used in pipelines and steps (e.g. `security-auditor`). */
+    kind: AgentKind;
+    /**
+     * The system prompt (role) for this kind. A function form receives the kind id so a
+     * single definition object can serve a family of related kinds.
+     */
+    systemPrompt: string | ((kind: AgentKind) => string);
+    /**
+     * Optional custom user-prompt builder. When omitted the kind uses the generic user
+     * prompt (block context + prior pipeline outputs), exactly like any other
+     * non-standard-phase kind. Human revision feedback is appended automatically.
+     */
+    userPrompt?: (context: AgentRunContext) => string;
+    /**
+     * When true this kind needs a real checkout (clone/edit/commit/PR) and must run in a
+     * container rather than as a one-shot inline LLM call — see the Worker's
+     * `CompositeAgentExecutor`. Defaults to false (an inline LLM agent). NOTE: a container
+     * kind ALSO needs harness support for its dispatch endpoint; inline kinds work
+     * end-to-end with no harness changes.
+     */
+    requiresContainer?: boolean;
+    /**
+     * Optional one-clause reason this kind should reach for web search, phrased to
+     * complete "Use it mainly to …" (e.g. "verify the vendor's current API contract
+     * before generating a client"). When web search is enabled for the deployment, this
+     * is folded into the kind's web-search guidance so a proprietary kind gets a nudge
+     * tailored to its job — without the shared library needing to know the kind exists.
+     * Omitted ⇒ the generic "verify a fact that changes" hint. See `webResearchGuidanceFor`.
+     */
+    webResearchHint?: string;
+    /**
+     * Task-level configuration parameters this kind contributes (see the agent-config
+     * contracts). When a pipeline that includes this kind is selected for a task, these
+     * descriptors are surfaced on task creation + the inspector, editable until the
+     * kind's step starts. Each descriptor's `agentKind` should match this `kind` so the
+     * freeze targets the right step. Omitted ⇒ the kind contributes no config.
+     */
+    configContributions?: AgentConfigDescriptor[];
+    /**
+     * Capability traits this kind carries (see ./traits). `code-aware` makes the engine
+     * fold the running service's selected best-practice fragments into the agent's prompt;
+     * `spec-aware` appends the in-repo-spec reading guidance. Deployments can also assign
+     * their own traits registered via `registerAgentTrait`. Omitted ⇒ no traits.
+     */
+    traits?: AgentTrait[];
+}
+/** Register a custom agent kind. A later registration of the same id replaces the earlier one. */
+export declare function registerAgentKind(definition: AgentKindDefinition): void;
+/** Register several custom agent kinds at once. */
+export declare function registerAgentKinds(definitions: Iterable<AgentKindDefinition>): void;
+/** The registered definition for a kind, or undefined for built-in / unregistered kinds. */
+export declare function registeredAgentKind(kind: AgentKind): AgentKindDefinition | undefined;
+/** All registered custom agent kinds (registration order). */
+export declare function registeredAgentKinds(): AgentKindDefinition[];
+/** Whether a registered kind asked to run in a container. False for built-in / unregistered kinds. */
+export declare function registeredKindRequiresContainer(kind: AgentKind): boolean;
+/** Drop all registered kinds. Intended for tests that exercise registration. */
+export declare function clearRegisteredAgentKinds(): void;
+/** A registered kind's system prompt, or undefined when the kind is not registered. */
+export declare function registeredSystemPrompt(kind: AgentKind): string | undefined;
+/** A registered kind's user prompt, or undefined when the kind is not registered / has no builder. */
+export declare function registeredUserPrompt(context: AgentRunContext): string | undefined;
+/** A registered kind's web-research hint, or undefined when unregistered / not supplied. */
+export declare function registeredWebResearchHint(kind: AgentKind): string | undefined;
+/** A registered kind's contributed config descriptors, or an empty array when none. */
+export declare function registeredConfigContributions(kind: AgentKind): AgentConfigDescriptor[];
+//# sourceMappingURL=registry.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAA;AAC5F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAY7C,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,IAAI,EAAE,SAAS,CAAA;IACf;;;OAGG;IACH,YAAY,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,MAAM,CAAC,CAAA;IACpD;;;;OAIG;IACH,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,MAAM,CAAA;IACjD;;;;;;OAMG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAC3B;;;;;;;OAOG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,EAAE,CAAA;IAC7C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAA;CACtB;AAOD,kGAAkG;AAClG,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAEvE;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,QAAQ,CAAC,mBAAmB,CAAC,GAAG,IAAI,CAEnF;AAED,4FAA4F;AAC5F,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,GAAG,mBAAmB,GAAG,SAAS,CAEpF;AAED,8DAA8D;AAC9D,wBAAgB,oBAAoB,IAAI,mBAAmB,EAAE,CAE5D;AAED,sGAAsG;AACtG,wBAAgB,+BAA+B,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAExE;AAED,gFAAgF;AAChF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAM1E;AAED,sGAAsG;AACtG,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAEjF;AAED,4FAA4F;AAC5F,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAE7E;AAED,uFAAuF;AACvF,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,SAAS,GAAG,qBAAqB,EAAE,CAEtF"}

package/dist/agents/registry.js

@@ -0,0 +1,51 @@
+// Process-wide registry, mirroring the Worker's model-provider registry. Registration
+// is a startup side effect read by every prompt build / routing decision, so the extra
+// kinds reach all paths — HTTP requests, the durable driver and the cron sweeper.
+const registry = new Map();
+/** Register a custom agent kind. A later registration of the same id replaces the earlier one. */
+export function registerAgentKind(definition) {
+    registry.set(definition.kind, definition);
+}
+/** Register several custom agent kinds at once. */
+export function registerAgentKinds(definitions) {
+    for (const definition of definitions)
+        registerAgentKind(definition);
+}
+/** The registered definition for a kind, or undefined for built-in / unregistered kinds. */
+export function registeredAgentKind(kind) {
+    return registry.get(kind);
+}
+/** All registered custom agent kinds (registration order). */
+export function registeredAgentKinds() {
+    return [...registry.values()];
+}
+/** Whether a registered kind asked to run in a container. False for built-in / unregistered kinds. */
+export function registeredKindRequiresContainer(kind) {
+    return registry.get(kind)?.requiresContainer === true;
+}
+/** Drop all registered kinds. Intended for tests that exercise registration. */
+export function clearRegisteredAgentKinds() {
+    registry.clear();
+}
+/** A registered kind's system prompt, or undefined when the kind is not registered. */
+export function registeredSystemPrompt(kind) {
+    const definition = registry.get(kind);
+    if (!definition)
+        return undefined;
+    return typeof definition.systemPrompt === 'function'
+        ? definition.systemPrompt(kind)
+        : definition.systemPrompt;
+}
+/** A registered kind's user prompt, or undefined when the kind is not registered / has no builder. */
+export function registeredUserPrompt(context) {
+    return registry.get(context.agentKind)?.userPrompt?.(context);
+}
+/** A registered kind's web-research hint, or undefined when unregistered / not supplied. */
+export function registeredWebResearchHint(kind) {
+    return registry.get(kind)?.webResearchHint;
+}
+/** A registered kind's contributed config descriptors, or an empty array when none. */
+export function registeredConfigContributions(kind) {
+    return registry.get(kind)?.configContributions ?? [];
+}
+//# sourceMappingURL=registry.js.map

package/dist/agents/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/agents/registry.ts"],"names":[],"mappings":"AA6DA,sFAAsF;AACtF,uFAAuF;AACvF,kFAAkF;AAClF,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA+B,CAAA;AAEvD,kGAAkG;AAClG,MAAM,UAAU,iBAAiB,CAAC,UAA+B;IAC/D,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,EAAE,UAAU,CAAC,CAAA;AAC3C,CAAC;AAED,mDAAmD;AACnD,MAAM,UAAU,kBAAkB,CAAC,WAA0C;IAC3E,KAAK,MAAM,UAAU,IAAI,WAAW;QAAE,iBAAiB,CAAC,UAAU,CAAC,CAAA;AACrE,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,mBAAmB,CAAC,IAAe;IACjD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AAC3B,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,oBAAoB;IAClC,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;AAC/B,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,+BAA+B,CAAC,IAAe;IAC7D,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,iBAAiB,KAAK,IAAI,CAAA;AACvD,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,yBAAyB;IACvC,QAAQ,CAAC,KAAK,EAAE,CAAA;AAClB,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,sBAAsB,CAAC,IAAe;IACpD,MAAM,UAAU,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACrC,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAA;IACjC,OAAO,OAAO,UAAU,CAAC,YAAY,KAAK,UAAU;QAClD,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,CAAC;QAC/B,CAAC,CAAC,UAAU,CAAC,YAAY,CAAA;AAC7B,CAAC;AAED,sGAAsG;AACtG,MAAM,UAAU,oBAAoB,CAAC,OAAwB;IAC3D,OAAO,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,UAAU,EAAE,CAAC,OAAO,CAAC,CAAA;AAC/D,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,yBAAyB,CAAC,IAAe;IACvD,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,eAAe,CAAA;AAC5C,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,6BAA6B,CAAC,IAAe;IAC3D,OAAO,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,mBAAmB,IAAI,EAAE,CAAA;AACtD,CAAC"}

package/dist/agents/runtime/executor.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 './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=executor.d.ts.map

package/dist/agents/runtime/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/executor.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,cAAc,CAAA;AAE3F,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/runtime/executor.js

@@ -0,0 +1,125 @@
+import { generateText } from 'ai';
+import { systemPromptFor, userPromptFor } from '../catalog.js';
+import { catFactoryObservability } from '../../providers/instrumented.js';
+import { resolveAgentConfig, resolveInlineModelRef } from './routing.js';
+import { composeBlockSystemPrompt } from './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=executor.js.map

package/dist/agents/runtime/executor.js.map

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

package/dist/agents/runtime/fragments.d.ts

@@ -0,0 +1,17 @@
+/** A block's fragment selection, as the prompt composer needs it. */
+export interface ComposableBlock {
+    fragmentIds?: string[];
+    resolvedFragments?: {
+        id: string;
+        body: string;
+    }[];
+}
+export declare function composeSystemPrompt(baseSystem: string, fragmentIds?: string[]): string;
+/**
+ * Compose the system prompt for a block, preferring the engine-resolved tenant
+ * catalog bodies when present and otherwise falling back to static id resolution.
+ * Both inline and container executors use this so the fragment-library feature
+ * applies uniformly to every agent kind, not just the reviewer.
+ */
+export declare function composeBlockSystemPrompt(baseSystem: string, block: ComposableBlock): string;
+//# sourceMappingURL=fragments.d.ts.map

package/dist/agents/runtime/fragments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/fragments.ts"],"names":[],"mappings":"AAgBA,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;IACtB,iBAAiB,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAA;CACnD;AAcD,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,EAAE,WAAW,GAAE,MAAM,EAAO,GAAG,MAAM,CAM1F;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,GAAG,MAAM,CAQ3F"}

package/dist/agents/runtime/fragments.js

@@ -0,0 +1,33 @@
+import { getFragment } from '@cat-factory/prompt-fragments';
+/** Fold a set of fragment bodies into the base system prompt under a header. */
+function foldStandards(baseSystem, bodies) {
+    if (bodies.length === 0)
+        return baseSystem;
+    return [
+        baseSystem,
+        '',
+        'Follow these standards while doing the work:',
+        '',
+        bodies.join('\n\n'),
+    ].join('\n');
+}
+export function composeSystemPrompt(baseSystem, fragmentIds = []) {
+    const bodies = fragmentIds
+        .map((id) => getFragment(id))
+        .filter((fragment) => fragment !== undefined)
+        .map((fragment) => fragment.body);
+    return foldStandards(baseSystem, bodies);
+}
+/**
+ * Compose the system prompt for a block, preferring the engine-resolved tenant
+ * catalog bodies when present and otherwise falling back to static id resolution.
+ * Both inline and container executors use this so the fragment-library feature
+ * applies uniformly to every agent kind, not just the reviewer.
+ */
+export function composeBlockSystemPrompt(baseSystem, block) {
+    if (block.resolvedFragments && block.resolvedFragments.length > 0) {
+        return foldStandards(baseSystem, block.resolvedFragments.map((f) => f.body));
+    }
+    return composeSystemPrompt(baseSystem, block.fragmentIds);
+}
+//# sourceMappingURL=fragments.js.map

package/dist/agents/runtime/fragments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragments.js","sourceRoot":"","sources":["../../../src/agents/runtime/fragments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAsB3D,gFAAgF;AAChF,SAAS,aAAa,CAAC,UAAkB,EAAE,MAAgB;IACzD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAA;IAC1C,OAAO;QACL,UAAU;QACV,EAAE;QACF,8CAA8C;QAC9C,EAAE;QACF,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;KACpB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACd,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,UAAkB,EAAE,WAAW,GAAa,EAAE;IAChF,MAAM,MAAM,GAAG,WAAW;SACvB,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;SAC5B,MAAM,CAAC,CAAC,QAAQ,EAA4C,EAAE,CAAC,QAAQ,KAAK,SAAS,CAAC;SACtF,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;IACnC,OAAO,aAAa,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,wBAAwB,CAAC,UAAkB,EAAE,KAAsB;IACjF,IAAI,KAAK,CAAC,iBAAiB,IAAI,KAAK,CAAC,iBAAiB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,OAAO,aAAa,CAClB,UAAU,EACV,KAAK,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAC3C,CAAA;IACH,CAAC;IACD,OAAO,mBAAmB,CAAC,UAAU,EAAE,KAAK,CAAC,WAAW,CAAC,CAAA;AAC3D,CAAC"}

package/dist/agents/runtime/routing.d.ts

@@ -0,0 +1,57 @@
+import type { AgentKind } from '@cat-factory/kernel';
+import type { ModelRef } from '@cat-factory/kernel';
+export interface AgentModelConfig {
+    ref: ModelRef;
+    temperature?: number;
+    maxOutputTokens?: number;
+    /** Overrides the built-in role system prompt for this agent kind. */
+    system?: string;
+}
+export interface AgentRouting {
+    /** Used for any agent kind without a specific entry (incl. custom agents). */
+    default: AgentModelConfig;
+    byKind: Partial<Record<AgentKind, AgentModelConfig>>;
+}
+/** Resolve the effective config for an agent kind, falling back to the default. */
+export declare function resolveAgentConfig(routing: AgentRouting, kind: AgentKind): AgentModelConfig;
+/** The resolvers a caller supplies so a step's model is picked the same way everywhere. */
+export interface StepModelResolvers {
+    agentRouting: AgentRouting;
+    /** Resolve a model catalog id to a concrete ref; unknown/absent ids return undefined. */
+    resolveBlockModel: (modelId: string | undefined) => ModelRef | undefined;
+    /**
+     * Resolve a 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.
+     */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string) => Promise<string | undefined>;
+}
+/** What a step needs to resolve its model: which kind, the block's pin, the workspace. */
+export interface StepModelInputs {
+    agentKind: string;
+    /** The model catalog id pinned on the block, if any. */
+    blockModelId: string | undefined;
+    /** The workspace the step runs in; required to consult a per-kind default. */
+    workspaceId?: string;
+}
+/**
+ * Resolve the concrete model ref for a pipeline step with the ONE canonical
+ * precedence used across every executor (the inline LLM executor, the container
+ * executor and the requirements reviewer): a block's pinned model wins, else the
+ * workspace's per-agent-kind default, else the env routing for the kind. Each
+ * candidate id is run through {@link StepModelResolvers.resolveBlockModel}, so an
+ * unresolvable pin (e.g. a stale id) falls through to the next source rather than
+ * silently skipping the workspace default.
+ */
+export declare function resolveStepModelRef(resolvers: StepModelResolvers, inputs: StepModelInputs): Promise<ModelRef>;
+/**
+ * Resolve the model ref for an INLINE LLM call (one that runs through the
+ * {@link ModelProvider}, not a container harness). Identical precedence to
+ * {@link resolveStepModelRef}, but a pinned subscription model — one whose ref
+ * carries a container-only `claude-code` / `codex` harness, for which no provider
+ * key exists — is degraded to the kind's env-routing default (a provider model the
+ * ModelProvider can serve). This is the single place every inline executor routes a
+ * block's model through, so a task pinned to a subscription model for its container
+ * steps still runs its inline steps instead of hard-failing. See {@link inlineModelRef}.
+ */
+export declare function resolveInlineModelRef(resolvers: StepModelResolvers, inputs: StepModelInputs): Promise<ModelRef>;
+//# sourceMappingURL=routing.d.ts.map

package/dist/agents/runtime/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAA;AASnD,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,QAAQ,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,gBAAgB,CAAA;IACzB,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC,CAAA;CACrD;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,IAAI,EAAE,SAAS,GAAG,gBAAgB,CAE3F;AAED,2FAA2F;AAC3F,MAAM,WAAW,kBAAkB;IACjC,YAAY,EAAE,YAAY,CAAA;IAC1B,yFAAyF;IACzF,iBAAiB,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,QAAQ,GAAG,SAAS,CAAA;IACxE;;;OAGG;IACH,4BAA4B,CAAC,EAAE,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,KACd,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACjC;AAED,0FAA0F;AAC1F,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,wDAAwD;IACxD,YAAY,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,QAAQ,CAAC,CAYnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,kBAAkB,EAC7B,MAAM,EAAE,eAAe,GACtB,OAAO,CAAC,QAAQ,CAAC,CAGnB"}

package/dist/agents/runtime/routing.js

@@ -0,0 +1,41 @@
+import { inlineModelRef } from '@cat-factory/kernel';
+/** Resolve the effective config for an agent kind, falling back to the default. */
+export function resolveAgentConfig(routing, kind) {
+    return routing.byKind[kind] ?? routing.default;
+}
+/**
+ * Resolve the concrete model ref for a pipeline step with the ONE canonical
+ * precedence used across every executor (the inline LLM executor, the container
+ * executor and the requirements reviewer): a block's pinned model wins, else the
+ * workspace's per-agent-kind default, else the env routing for the kind. Each
+ * candidate id is run through {@link StepModelResolvers.resolveBlockModel}, so an
+ * unresolvable pin (e.g. a stale id) falls through to the next source rather than
+ * silently skipping the workspace default.
+ */
+export async function resolveStepModelRef(resolvers, inputs) {
+    const fromBlock = resolvers.resolveBlockModel(inputs.blockModelId);
+    if (fromBlock)
+        return fromBlock;
+    if (resolvers.resolveWorkspaceModelDefault && inputs.workspaceId) {
+        const defaultId = await resolvers.resolveWorkspaceModelDefault(inputs.workspaceId, inputs.agentKind);
+        const fromDefault = resolvers.resolveBlockModel(defaultId);
+        if (fromDefault)
+            return fromDefault;
+    }
+    return resolveAgentConfig(resolvers.agentRouting, inputs.agentKind).ref;
+}
+/**
+ * Resolve the model ref for an INLINE LLM call (one that runs through the
+ * {@link ModelProvider}, not a container harness). Identical precedence to
+ * {@link resolveStepModelRef}, but a pinned subscription model — one whose ref
+ * carries a container-only `claude-code` / `codex` harness, for which no provider
+ * key exists — is degraded to the kind's env-routing default (a provider model the
+ * ModelProvider can serve). This is the single place every inline executor routes a
+ * block's model through, so a task pinned to a subscription model for its container
+ * steps still runs its inline steps instead of hard-failing. See {@link inlineModelRef}.
+ */
+export async function resolveInlineModelRef(resolvers, inputs) {
+    const ref = await resolveStepModelRef(resolvers, inputs);
+    return inlineModelRef(ref, resolveAgentConfig(resolvers.agentRouting, inputs.agentKind).ref);
+}
+//# sourceMappingURL=routing.js.map

package/dist/agents/runtime/routing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.js","sourceRoot":"","sources":["../../../src/agents/runtime/routing.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAsBpD,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,OAAqB,EAAE,IAAe;IACvE,OAAO,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,OAAO,CAAA;AAChD,CAAC;AA0BD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAA6B,EAC7B,MAAuB;IAEvB,MAAM,SAAS,GAAG,SAAS,CAAC,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;IAClE,IAAI,SAAS;QAAE,OAAO,SAAS,CAAA;IAC/B,IAAI,SAAS,CAAC,4BAA4B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;QACjE,MAAM,SAAS,GAAG,MAAM,SAAS,CAAC,4BAA4B,CAC5D,MAAM,CAAC,WAAW,EAClB,MAAM,CAAC,SAAS,CACjB,CAAA;QACD,MAAM,WAAW,GAAG,SAAS,CAAC,iBAAiB,CAAC,SAAS,CAAC,CAAA;QAC1D,IAAI,WAAW;YAAE,OAAO,WAAW,CAAA;IACrC,CAAC;IACD,OAAO,kBAAkB,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAA;AACzE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,SAA6B,EAC7B,MAAuB;IAEvB,MAAM,GAAG,GAAG,MAAM,mBAAmB,CAAC,SAAS,EAAE,MAAM,CAAC,CAAA;IACxD,OAAO,cAAc,CAAC,GAAG,EAAE,kBAAkB,CAAC,SAAS,CAAC,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAA;AAC9F,CAAC"}

package/dist/agents/runtime/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/runtime/web-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search.d.ts","sourceRoot":"","sources":["../../../src/agents/runtime/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"}