@cogenta/agents 0.2.1 → 0.4.0

package/dist/agents/builtins.d.ts

@@ -0,0 +1,51 @@
+import type { AgentDeclarationInput, AgentDeclarationStore } from './store.js';
+/**
+ * L22 task 1 items 2 and 5, plus task 3 — the four agents every site starts
+ * with.
+ *
+ * `SUPERAGENT_NAME` ("Cogenta Agent") is active by default, with every
+ * content/media/site/document tool this build actually implements (never a
+ * placeholder permission with no tool behind it — `deps.scan` is the one
+ * this lot adds for exactly this agent). Its autonomy defaults to `propose`
+ * (the UI's "co-pilot") rather than `autonomous`: "actif par défaut" is
+ * about the agent *existing and being enabled*, not about every write it
+ * might make happening unattended from the first boot — a judgment call,
+ * flagged in this lot's report, that a site operator can raise to
+ * `autonomous` per tool or by default once they trust it.
+ *
+ * The security scanner, the content-watch example and the site monitor
+ * (task 3) are disabled by default, exactly as the lot asks, and all three
+ * ship as editable seeds: nothing about `builtin: true` freezes their tools,
+ * autonomy, budget or triggers, it only prevents deletion
+ * (`AgentDeclarationStore.remove`).
+ *
+ * `SITE_MONITOR_AGENT_NAME` ("Site Monitor") is task 3's own agent, kept
+ * separate from `SUPERAGENT_NAME` rather than folded into it: the
+ * superagent's tools are whatever an operator talks to it about, one
+ * instruction at a time, while this one exists to run unattended on a cron
+ * trigger with a narrow, fixed toolset (read the 404 log, browse content,
+ * propose or create a redirect) — a different shape of agent, not a bigger
+ * one. Its default autonomy is `propose` (co-pilot), same reasoning as the
+ * superagent's: a monitoring agent that can silently rewrite routing on its
+ * first boot is not what "disabled by default" is supposed to soften into
+ * once enabled. Raising it to `autonomous` (autopilot) is the one thing
+ * task 3's spec names as the condition for an applied, not merely
+ * suggested, redirect.
+ */
+export declare const SUPERAGENT_NAME = "Cogenta Agent";
+export declare const SECURITY_AGENT_NAME = "Security Scanner";
+export declare const CONTENT_WATCH_AGENT_NAME = "Content Watch";
+export declare const SITE_MONITOR_AGENT_NAME = "Site Monitor";
+export declare const THEME_CREATOR_AGENT_NAME = "Cogenta Theme Creator";
+export declare function builtinAgentSeeds(): readonly AgentDeclarationInput[];
+/**
+ * Idempotent: called both by `create-cogenta` at install and defensively by
+ * `cogenta serve` at every boot (an upgrade from an older site gains
+ * whichever of these it does not already have the first time it starts on
+ * the new version, not only a freshly scaffolded one). Matched by name — a
+ * seed already present (its `builtin: true` record cannot be removed, only
+ * disabled or edited) is left untouched, never overwritten with the seed's
+ * defaults again.
+ */
+export declare function ensureBuiltinAgents(store: AgentDeclarationStore): Promise<void>;
+//# sourceMappingURL=builtins.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"builtins.d.ts","sourceRoot":"","sources":["../../src/agents/builtins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAe,MAAM,YAAY,CAAA;AAE3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,eAAe,kBAAkB,CAAA;AAC9C,eAAO,MAAM,mBAAmB,qBAAqB,CAAA;AACrD,eAAO,MAAM,wBAAwB,kBAAkB,CAAA;AACvD,eAAO,MAAM,uBAAuB,iBAAiB,CAAA;AACrD,eAAO,MAAM,wBAAwB,0BAA0B,CAAA;AAK/D,wBAAgB,iBAAiB,IAAI,SAAS,qBAAqB,EAAE,CAiHpE;AAED;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAMrF"}

package/dist/agents/builtins.js

@@ -0,0 +1,190 @@
+/**
+ * L22 task 1 items 2 and 5, plus task 3 — the four agents every site starts
+ * with.
+ *
+ * `SUPERAGENT_NAME` ("Cogenta Agent") is active by default, with every
+ * content/media/site/document tool this build actually implements (never a
+ * placeholder permission with no tool behind it — `deps.scan` is the one
+ * this lot adds for exactly this agent). Its autonomy defaults to `propose`
+ * (the UI's "co-pilot") rather than `autonomous`: "actif par défaut" is
+ * about the agent *existing and being enabled*, not about every write it
+ * might make happening unattended from the first boot — a judgment call,
+ * flagged in this lot's report, that a site operator can raise to
+ * `autonomous` per tool or by default once they trust it.
+ *
+ * The security scanner, the content-watch example and the site monitor
+ * (task 3) are disabled by default, exactly as the lot asks, and all three
+ * ship as editable seeds: nothing about `builtin: true` freezes their tools,
+ * autonomy, budget or triggers, it only prevents deletion
+ * (`AgentDeclarationStore.remove`).
+ *
+ * `SITE_MONITOR_AGENT_NAME` ("Site Monitor") is task 3's own agent, kept
+ * separate from `SUPERAGENT_NAME` rather than folded into it: the
+ * superagent's tools are whatever an operator talks to it about, one
+ * instruction at a time, while this one exists to run unattended on a cron
+ * trigger with a narrow, fixed toolset (read the 404 log, browse content,
+ * propose or create a redirect) — a different shape of agent, not a bigger
+ * one. Its default autonomy is `propose` (co-pilot), same reasoning as the
+ * superagent's: a monitoring agent that can silently rewrite routing on its
+ * first boot is not what "disabled by default" is supposed to soften into
+ * once enabled. Raising it to `autonomous` (autopilot) is the one thing
+ * task 3's spec names as the condition for an applied, not merely
+ * suggested, redirect.
+ */
+export const SUPERAGENT_NAME = 'Cogenta Agent';
+export const SECURITY_AGENT_NAME = 'Security Scanner';
+export const CONTENT_WATCH_AGENT_NAME = 'Content Watch';
+export const SITE_MONITOR_AGENT_NAME = 'Site Monitor';
+export const THEME_CREATOR_AGENT_NAME = 'Cogenta Theme Creator';
+/** Passed to `AgentDeclarationInput.model` — every seed prefers the same provider/model names an operator is most likely to configure first; `agents/orchestrator.ts` never fails to resolve a provider just because the *name* differs from what the site has enabled, it only needs `providers/store.ts` to have configured at least one. */
+const DEFAULT_MODEL = { preferred: 'anthropic', fallback: 'openai' };
+export function builtinAgentSeeds() {
+    return [
+        {
+            name: SUPERAGENT_NAME,
+            identity: {
+                role: 'The default, general-purpose agent for this Cogenta site — reads and writes content, media and configuration on behalf of the operator who talks to it, within whatever an admin actor may do.',
+                objectives: [
+                    'Carry out the instruction it is given, using the smallest set of tool calls that does it.',
+                    'Prefer reading before writing, and ask for a specific, named sub-agent when a task is squarely that sub-agent’s specialty.',
+                    'Never claim an action succeeded without the tool result to show for it.',
+                ],
+                style: 'Direct, concrete, and honest about what it did and did not do.',
+            },
+            model: DEFAULT_MODEL,
+            tools: [
+                'content.read',
+                // The browse pair (L22 task 3) — without them the superagent could
+                // only read an entry whose id it already knew, and a live run
+                // against DeepSeek showed it guessing ids 1..10 to count a site's
+                // posts. Same permission as `content.read`, read-only.
+                'content.collections',
+                'content.list',
+                // `content.schema` — the missing half of the browse pair: without it
+                // the superagent could see *that* a collection or entry exists, but
+                // never *what fields* it takes, and a live run asked "peux-tu
+                // générer un template ?" answered by asking the human to specify
+                // every field itself. Same permission as `content.read`, read-only.
+                'content.schema',
+                'content.write_draft',
+                'content.publish',
+                'content.delete',
+                'media.read',
+                'media.write',
+                'site.config_read',
+                'document.extract_text',
+            ],
+            autonomy: { default: 'propose' },
+            budget: { tokensPerDay: 200_000, callsPerHour: 60 },
+            memory: { episodic: true, scope: 'site' },
+            enabled: true,
+        },
+        {
+            name: SECURITY_AGENT_NAME,
+            identity: {
+                role: 'Scans this site’s own declared dependencies for risky version pins on a schedule, and reports what it finds — it never patches anything itself.',
+                objectives: [
+                    'Run deps.scan and summarise anything it flags (an unpinned or wildcard version).',
+                    'Report findings; never call a write tool.',
+                ],
+                style: 'Terse, factual, one line per finding.',
+            },
+            model: DEFAULT_MODEL,
+            tools: ['deps.scan', 'content.read'],
+            autonomy: { default: 'observe' },
+            budget: { tokensPerDay: 50_000, callsPerHour: 10 },
+            triggers: [{ on: 'schedule', cron: '0 6 * * *' }],
+            enabled: false,
+        },
+        {
+            name: CONTENT_WATCH_AGENT_NAME,
+            identity: {
+                role: 'An example agent: wakes up periodically, looks over recently published content, and proposes new draft titles worth writing about — a starting point meant to be edited, not a fixed feature.',
+                objectives: [
+                    'Read recent published entries in the configured collection.',
+                    'Propose 1-3 new draft entries (title + a one-line outline) via content.write_draft — never publish them.',
+                ],
+                style: 'Editorial, brief, no filler.',
+            },
+            model: DEFAULT_MODEL,
+            tools: ['content.read', 'content.write_draft'],
+            autonomy: { default: 'propose' },
+            budget: { tokensPerDay: 50_000, callsPerHour: 10 },
+            triggers: [{ on: 'schedule', cron: '0 8 * * 1' }],
+            enabled: false,
+        },
+        {
+            name: SITE_MONITOR_AGENT_NAME,
+            identity: {
+                role: 'Watches this site’s own 404 log for a broken link worth fixing, and either proposes or creates a redirect to a page it picks — never anything else (it never touches content, media or site config).',
+                objectives: [
+                    'Call logs.read_not_found and look at the paths with the most hits.',
+                    'For the top one with no redirect yet, call content.collections then content.list to find a genuinely related, routed page.',
+                    'Call redirects.create with that path as "to" — under co-pilot autonomy this only ever proposes the change for an admin to confirm in the Redirections screen; nothing is written until it does.',
+                    'Skip a 404 with too few hits to be worth a redirect, or when nothing in the site’s content is actually related — proposing a bad redirect is worse than proposing none.',
+                ],
+                style: 'Terse, factual, one finding per turn.',
+            },
+            model: DEFAULT_MODEL,
+            tools: ['logs.read_not_found', 'content.collections', 'content.list', 'redirects.create'],
+            autonomy: { default: 'propose' },
+            budget: { tokensPerDay: 50_000, callsPerHour: 10 },
+            triggers: [{ on: 'schedule', cron: '0 7 * * *' }],
+            enabled: false,
+        },
+        {
+            name: THEME_CREATOR_AGENT_NAME,
+            identity: {
+                role: 'Designs and adjusts this site’s visual theme from a description and, optionally, attached files (documents, screenshots) — the Appearance screen’s theme generator workshop talks to this agent, not the other way around.',
+                objectives: [
+                    'Read the brief and any attachments, then call theme.propose_theme with them.',
+                    'Pick the base theme from the packages this instance actually ships — never invent one.',
+                    'Produce contract D skin tokens only, never raw HTML or CSS.',
+                    'Propose 1-3 candidates and stop — this tool never applies anything itself (sideEffects: false); an admin activates a candidate from the workshop.',
+                ],
+                style: 'Concrete design rationale, one sentence per candidate, no filler.',
+            },
+            model: DEFAULT_MODEL,
+            tools: ['theme.propose_theme'],
+            autonomy: { default: 'propose' },
+            budget: { tokensPerDay: 100_000, callsPerHour: 20 },
+            enabled: true,
+        },
+    ];
+}
+/**
+ * Idempotent: called both by `create-cogenta` at install and defensively by
+ * `cogenta serve` at every boot (an upgrade from an older site gains
+ * whichever of these it does not already have the first time it starts on
+ * the new version, not only a freshly scaffolded one). Matched by name — a
+ * seed already present (its `builtin: true` record cannot be removed, only
+ * disabled or edited) is left untouched, never overwritten with the seed's
+ * defaults again.
+ */
+export async function ensureBuiltinAgents(store) {
+    for (const seed of builtinAgentSeeds()) {
+        const existing = await store.get(seed.name);
+        if (existing === undefined)
+            await store.create(seed, true);
+        else
+            await grantContentBrowse(store, existing);
+    }
+}
+/**
+ * The one exception to "never touch an existing seed": `content.collections`,
+ * `content.list` and `content.schema` are all read-only, all under
+ * `content.read` (same permission, each added after the superagent first
+ * shipped), so a built-in that already holds `content.read` gains nothing it
+ * could not already do — it only stops having to guess entry ids or field
+ * shapes. An operator who removed `content.read` on purpose is left alone.
+ */
+const CONTENT_BROWSE_TOOLS = ['content.collections', 'content.list', 'content.schema'];
+async function grantContentBrowse(store, existing) {
+    if (!existing.tools.includes('content.read'))
+        return;
+    const missing = CONTENT_BROWSE_TOOLS.filter((tool) => !existing.tools.includes(tool));
+    if (missing.length === 0)
+        return;
+    await store.update(existing.name, { tools: [...existing.tools, ...missing] });
+}
+//# sourceMappingURL=builtins.js.map

package/dist/agents/builtins.js.map

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

package/dist/agents/orchestrator.d.ts

@@ -0,0 +1,95 @@
+import type { AuditLogLike } from '../audit/types.js';
+import type { ApprovalQueue } from '../autonomy/types.js';
+import type { BudgetTracker, KillSwitch } from '../budget/types.js';
+import type { ChatMessage, ProviderClient } from '../providers/types.js';
+import type { RunResult, RunStopReason } from '../runtime/types.js';
+import type { AgentSkillStore } from '../skills/library.js';
+import { type ToolRegistry } from '../tools/registry.js';
+import type { AgentDeclarationStore, StoredAgent } from './store.js';
+/**
+ * Two different "site" shapes meet here on purpose, not by accident:
+ * `ToolContext.site` (what `buildManifest` needs — `defaultLocale`
+ * required, no `brand`/`tone`/`constraints`) and `identity/context.js`'s
+ * `SiteContext` (what `assembleContext` needs — the reverse). `RunnerSite`
+ * is the superset a caller supplies once; `siteContextOf`/`toolSiteOf` below
+ * project it down to whichever shape a given call actually needs.
+ */
+export interface RunnerSite {
+    readonly name: string;
+    readonly url?: string;
+    readonly locales: readonly string[];
+    readonly defaultLocale: string;
+    readonly brand?: string;
+    readonly tone?: string;
+    readonly constraints?: readonly string[];
+}
+/**
+ * L22 task 1's actual deliverable: the wiring `AgentRegistry` never had.
+ * Everything this function calls already existed and was already tested
+ * (`runAgentLoop`, `buildManifest`, `withAutonomyForManifest`,
+ * `withAuditForManifest`, `createAgentDelegateTool`, `assembleContext`,
+ * `createBudgetTracker`) — this module's own job is only to put them
+ * together in the right order for one named agent, never to reimplement any
+ * of them.
+ *
+ * Order of wrapping matters: `withAudit` is the outermost layer, so the
+ * audit trail records what actually happened (executed, observed, or
+ * proposed-and-not-yet-decided) rather than the raw tool's own behaviour —
+ * `withAutonomy` sits directly on the raw tool underneath it.
+ */
+export interface AgentProviderRegistryLike {
+    has(name: string): boolean;
+    get(name: string): ProviderClient;
+}
+export interface RunAgentOptions {
+    /** Runtime-generated instruction (a trigger, an operator's typed request) — never external content (R8's own distinction, see `identity/context.ts`). */
+    readonly instruction: string;
+    /**
+     * Prior turns of a standing conversation with this agent, oldest first —
+     * plain `user`/`assistant` text, no `toolCalls`/`toolCallId` (a past run's
+     * tool instances are gone by the next call; replaying raw tool_use/
+     * tool_result blocks across runs would assume a continuity the runtime
+     * does not have). Spliced between the R8 `dataMessages` and the fixed
+     * trigger turn, so a multi-turn caller (the chat surfaces) gets real
+     * conversational memory without folding it into `instruction`'s own
+     * `<task>` tag — the string-concatenation hack this replaces.
+     */
+    readonly history?: readonly ChatMessage[];
+    /** What started this run — recorded in the run-level audit entry. */
+    readonly trigger?: string;
+    readonly signal?: AbortSignal;
+    readonly maxTokens?: number;
+}
+/** One tool call the run made, folded down for a caller that only wants "what did it touch", not the full `StepRecord` shape. */
+export interface AgentRunToolCallSummary {
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+export interface AgentRunSummary {
+    readonly agent: string;
+    readonly stopReason: RunStopReason;
+    readonly finalText: string | null;
+    readonly steps: number;
+    readonly usage: RunResult['usage'];
+    /** Every tool call across every step, in call order — `[]` when the run made none. */
+    readonly toolCalls: readonly AgentRunToolCallSummary[];
+}
+export interface AgentRunnerOptions {
+    readonly agents: AgentDeclarationStore;
+    readonly skills: AgentSkillStore;
+    /** The site's full contract-C tool registry — content/media/site-config/http-fetch/document-extract/deps-scan, whatever this build/deployment actually implements. `buildManifest` refuses (at call time) any name an agent declares that is not in here. */
+    readonly tools: ToolRegistry;
+    readonly providers: AgentProviderRegistryLike;
+    readonly auditLog: AuditLogLike;
+    readonly approvalQueue: ApprovalQueue;
+    readonly site: RunnerSite;
+    readonly killSwitchFor: (name: string) => KillSwitch;
+    readonly now?: () => number;
+    /** Injectable for tests — defaults to a real `Date.now`-bucketed tracker per agent, cached for the runner's lifetime. */
+    readonly budgetTrackerFor?: (agent: StoredAgent) => BudgetTracker;
+}
+export interface AgentRunner {
+    run(name: string, options: RunAgentOptions): Promise<AgentRunSummary>;
+}
+export declare function createAgentRunner(options: AgentRunnerOptions): AgentRunner;
+//# sourceMappingURL=orchestrator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAGzD,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAExE,OAAO,KAAK,EAAkB,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAG3D,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAE5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEpE;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACzC;AAED;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAA;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,yJAAyJ;IACzJ,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;;;;;OASG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,WAAW,EAAE,CAAA;IACzC,qEAAqE;IACrE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,iIAAiI;AACjI,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;CAClD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAA;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IAClC,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,SAAS,uBAAuB,EAAE,CAAA;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAA;IACtC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;IAChC,6PAA6P;IAC7P,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAA;IACrC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;IACzB,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,CAAA;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAC3B,yHAAyH;IACzH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,aAAa,CAAA;CAClE;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CACtE;AAiHD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAiL1E"}

package/dist/agents/orchestrator.js

@@ -0,0 +1,285 @@
+import { CogentaError } from '@cogenta/core';
+import { withAuditForManifest } from '../audit/with-audit.js';
+import { withAutonomyForManifest } from '../autonomy/with-autonomy.js';
+import { createBudgetTracker } from '../budget/tracker.js';
+import { assembleContext } from '../identity/context.js';
+import { runAgentLoop } from '../runtime/loop.js';
+import { createAgentDelegateTool } from '../tools/core/agent-delegate.js';
+import { buildManifest } from '../tools/manifest.js';
+import { createToolRegistry } from '../tools/registry.js';
+/**
+ * `runOptions.maxTokens` is a genuine per-call override, kept for a caller
+ * with a real reason to differ from a run's own default; when absent (every
+ * real caller today), `runAgentLoop` no longer needs a value from here at
+ * all — it falls back to `client.maxOutputTokens`, the admin-configured
+ * property of *which model this run resolved to*
+ * (`/admin/providers`). That per-provider value already fixed a reproduced,
+ * live failure this constant used to paper over with a single guess: the
+ * superagent, asked to draft a real content template, made seven legitimate
+ * tool calls and had its final answer cut off mid-generation
+ * (`stopReason: 'max_tokens'`, DeepSeek's `finish_reason: 'length'`) at a
+ * budget sized for a short conversational reply, not a generation task this
+ * runtime actively encourages — a number no single call site can size
+ * correctly for every model an admin might configure.
+ */
+function toolSiteOf(site) {
+    return {
+        name: site.name,
+        ...(site.url === undefined ? {} : { url: site.url }),
+        locales: site.locales,
+        defaultLocale: site.defaultLocale,
+    };
+}
+function siteContextOf(site) {
+    return {
+        name: site.name,
+        ...(site.brand === undefined ? {} : { brand: site.brand }),
+        ...(site.tone === undefined ? {} : { tone: site.tone }),
+        locales: site.locales,
+        ...(site.constraints === undefined ? {} : { constraints: site.constraints }),
+    };
+}
+function agentUnknown(name) {
+    return new CogentaError({
+        code: 'AGENT_UNKNOWN',
+        message: `No agent named "${name}" is registered.`,
+        hint: 'Check the name against the Agents screen, or create it first.',
+    });
+}
+function agentDisabled(name) {
+    return new CogentaError({
+        code: 'AGENT_DISABLED',
+        message: `"${name}" is disabled and cannot run.`,
+        hint: 'Enable it from the Agents screen first.',
+    });
+}
+/**
+ * R2, applied at the one place a network call would otherwise happen:
+ * resolving a `ProviderClient` is a synchronous registry lookup (`get`
+ * throws `PROVIDER_UNKNOWN` without ever touching the network — see
+ * `providers/registry.ts`), so trying `preferred` then `fallback` and
+ * throwing `AGENT_NO_PROVIDER` when neither resolves guarantees zero
+ * outbound requests for a site with no provider configured — the same
+ * guarantee `packages/cli/test/serve-assistant.test.ts` already proves for
+ * `assist.*`, extended here to the agent runtime.
+ */
+/**
+ * Fiche 55 task 2 — `model.model` is an explicit model id, distinct from the
+ * provider name `resolveProvider` already picked a client by. A
+ * `ProviderClient` is a plain object (`{ name, model, chat }`, see every
+ * `providers/*.ts` adapter); overriding `model` this way changes nothing
+ * about `chat`'s closure over its own config (the vendor URL, the API key)
+ * — only the `model` field `runAgentLoop` reads off the client onto every
+ * `ChatRequest`. Absent or blank means "use whatever the provider config
+ * says", the behaviour every agent had before this field existed.
+ */
+function withModelOverride(client, model) {
+    if (model === undefined || model.trim().length === 0)
+        return client;
+    return { ...client, model: model.trim() };
+}
+function resolveProvider(agentName, model, providers) {
+    if (providers.has(model.preferred)) {
+        return withModelOverride(providers.get(model.preferred), model.model);
+    }
+    if (model.fallback !== undefined && providers.has(model.fallback)) {
+        return withModelOverride(providers.get(model.fallback), model.model);
+    }
+    throw new CogentaError({
+        code: 'AGENT_NO_PROVIDER',
+        message: `"${agentName}" has no configured LLM provider (wants "${model.preferred}"${model.fallback === undefined ? '' : ` or "${model.fallback}"`}).`,
+        hint: 'Configure a provider from the admin\'s "Providers" screen before running this agent.',
+    });
+}
+async function skillInstructionsFor(skills, names) {
+    if (names === undefined || names.length === 0)
+        return '';
+    const all = await skills.list();
+    const byId = new Map(all.map((skill) => [skill.id, skill]));
+    const blocks = names
+        .map((id) => byId.get(id))
+        .filter((skill) => skill !== undefined)
+        .map((skill) => `### ${skill.name}\n${skill.instructions}`);
+    if (blocks.length === 0)
+        return '';
+    return `\n\nAvailable skills:\n${blocks.join('\n\n')}`;
+}
+export function createAgentRunner(options) {
+    const now = options.now ?? Date.now;
+    const budgetTrackers = new Map();
+    function budgetTrackerFor(agent) {
+        const existing = budgetTrackers.get(agent.name);
+        if (existing !== undefined)
+            return existing;
+        const tracker = options.budgetTrackerFor?.(agent) ?? createBudgetTracker({ limits: agent.budget ?? {} });
+        budgetTrackers.set(agent.name, tracker);
+        return tracker;
+    }
+    function actorFor(agentName) {
+        // Full role, bounded not by the actor's own roles but by the manifest
+        // itself (buildManifest only ever exposes the tools this agent's own
+        // `tools` list names) — R4's real gate is what got into the manifest,
+        // not what role string rides along with the call.
+        return { id: `agent:${agentName}`, roles: ['admin', 'agent'] };
+    }
+    async function buildToolsFor(agent) {
+        const context = {
+            site: toolSiteOf(options.site),
+            actor: actorFor(agent.name),
+            logger: silentLogger,
+        };
+        const own = buildManifest(options.tools, agent.tools, context);
+        const delegates = [];
+        for (const subagentName of agent.subagents ?? []) {
+            const subagent = await options.agents.get(subagentName);
+            if (subagent === undefined)
+                continue; // validated at declaration time; a since-removed name is skipped rather than crashing a run
+            const subContext = {
+                site: toolSiteOf(options.site),
+                actor: actorFor(subagent.name),
+                logger: silentLogger,
+            };
+            // The sub-agent's own tool calls (made inside its own `runAgentLoop`,
+            // via `createAgentDelegateTool`) are gated and journalled exactly like
+            // the parent's — its own autonomy config, its own name in the audit
+            // trail — never a bare pass-through just because they were reached one
+            // hop away from the top-level run.
+            const subTools = withAuditForManifest(withAutonomyForManifest(buildManifest(options.tools, subagent.tools, subContext), {
+                agentName: subagent.name,
+                autonomy: subagent.autonomy ?? { default: 'observe' },
+                approvalQueue: options.approvalQueue,
+            }), {
+                auditLog: options.auditLog,
+                agentName: subagent.name,
+                actor: actorFor(subagent.name),
+                ...(subagent.autonomy?.default === undefined
+                    ? {}
+                    : { autonomyLevel: subagent.autonomy.default }),
+            });
+            let subClient;
+            try {
+                subClient = resolveProvider(subagent.name, subagent.model, options.providers);
+            }
+            catch {
+                continue; // no provider for the sub-agent: it simply is not offered as a delegate tool this run (R2)
+            }
+            const identity = await options.agents.readIdentity(subagent.name);
+            const { system } = assembleContext({
+                site: siteContextOf(options.site),
+                agent: { name: subagent.name, ...identity },
+                task: { instruction: 'Carry out whatever task the parent agent delegates to you.' },
+            });
+            const delegateDefinition = createAgentDelegateTool({
+                subagentName: subagent.name,
+                client: subClient,
+                tools: subTools,
+                system,
+            });
+            // `createAgentDelegateTool` returns a contract-C `ToolDefinition`, the
+            // same shape every other core tool does — `buildManifest` is the one
+            // place that already knows how to turn one into the `ExecutableTool`
+            // the loop calls, so it is reused here for a one-tool "registry"
+            // rather than duplicating that conversion.
+            const [delegateExecutable] = buildManifest(createToolRegistry([delegateDefinition]), [delegateDefinition.name], context);
+            if (delegateExecutable !== undefined)
+                delegates.push(delegateExecutable);
+        }
+        return [...own, ...delegates];
+    }
+    return {
+        async run(name, runOptions) {
+            const agent = await options.agents.get(name);
+            if (agent === undefined)
+                throw agentUnknown(name);
+            if (!agent.enabled || options.killSwitchFor(name).isActive())
+                throw agentDisabled(name);
+            // Resolved and possibly thrown (AGENT_NO_PROVIDER) *before* any tool is
+            // built or any message assembled — the R2 guarantee this module exists
+            // to keep: no provider configured means no network call, full stop.
+            const client = resolveProvider(agent.name, agent.model, options.providers);
+            const tools = withAuditForManifest(withAutonomyForManifest(await buildToolsFor(agent), {
+                agentName: agent.name,
+                autonomy: agent.autonomy ?? { default: 'observe' },
+                approvalQueue: options.approvalQueue,
+            }), {
+                auditLog: options.auditLog,
+                agentName: agent.name,
+                actor: actorFor(agent.name),
+                model: client.model,
+                ...(agent.autonomy?.default === undefined
+                    ? {}
+                    : { autonomyLevel: agent.autonomy.default }),
+            });
+            const identity = await options.agents.readIdentity(agent.name);
+            const skillsText = await skillInstructionsFor(options.skills, agent.skills);
+            const { system, dataMessages } = assembleContext({
+                site: siteContextOf(options.site),
+                agent: { name: agent.name, ...identity },
+                task: { instruction: `${runOptions.instruction}${skillsText}` },
+            });
+            const startedAt = now();
+            let result;
+            try {
+                result = await runAgentLoop({
+                    client,
+                    system,
+                    messages: [
+                        ...dataMessages,
+                        ...(runOptions.history ?? []),
+                        { role: 'user', content: 'Carry out the TASK described in your system context.' },
+                    ],
+                    tools,
+                    ...(runOptions.maxTokens === undefined ? {} : { maxTokens: runOptions.maxTokens }),
+                    budget: budgetTrackerFor(agent),
+                    killSwitch: options.killSwitchFor(agent.name),
+                    ...(runOptions.signal === undefined ? {} : { signal: runOptions.signal }),
+                });
+            }
+            catch (error) {
+                await recordRun(options.auditLog, agent.name, runOptions.trigger, {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    durationMs: now() - startedAt,
+                });
+                throw error;
+            }
+            await recordRun(options.auditLog, agent.name, runOptions.trigger, {
+                ok: true,
+                stopReason: result.stopReason,
+                steps: result.steps.length,
+                usage: result.usage,
+                durationMs: now() - startedAt,
+            });
+            return {
+                agent: agent.name,
+                stopReason: result.stopReason,
+                finalText: result.finalText,
+                steps: result.steps.length,
+                usage: result.usage,
+                toolCalls: result.steps.flatMap((step) => step.toolOutcomes.map((outcome) => ({
+                    name: outcome.call.name,
+                    input: outcome.call.input,
+                }))),
+            };
+        },
+    };
+}
+const silentLogger = {
+    info: () => undefined,
+    warn: () => undefined,
+    error: () => undefined,
+};
+async function recordRun(auditLog, agentName, trigger, diff) {
+    try {
+        await auditLog.record({
+            actorId: `agent:${agentName}`,
+            actorRoles: ['agent'],
+            action: 'agent.run',
+            diff: { agent: agentName, trigger: trigger ?? 'manual', ...diff },
+        });
+    }
+    catch {
+        // ADR-0018: a write that fails must never fail the action it is auditing.
+    }
+}
+//# sourceMappingURL=orchestrator.js.map