@framers/agentos 0.1.97 → 0.1.99

package/dist/api/strategies/review-loop.js

@@ -0,0 +1,153 @@
+import { AgencyConfigError } from '../types.js';
+import { resolveAgent, checkBeforeAgent } from './shared.js';
+/**
+ * Attempts to parse a reviewer response as JSON with an `approved` field.
+ *
+ * The reviewer is instructed to respond with `{ "approved": true/false, "feedback": "..." }`.
+ * When the response is not valid JSON, or lacks an `approved` boolean, the entire
+ * text is treated as feedback and the draft is considered not approved.
+ *
+ * @param text - Raw reviewer output text.
+ * @returns Parsed review with approval status and feedback string.
+ */
+function parseReview(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.approved === 'boolean') {
+            return {
+                approved: parsed.approved,
+                feedback: parsed.feedback ?? text,
+            };
+        }
+    }
+    catch {
+        /* Not valid JSON — fall through to treat entire text as feedback. */
+    }
+    return { approved: false, feedback: text };
+}
+/**
+ * Compiles a review-loop execution strategy.
+ *
+ * The first declared agent acts as the producer, the second as the reviewer.
+ * The producer generates or revises a draft, then the reviewer evaluates it.
+ * If the reviewer approves (responds with `{ "approved": true }`), the loop
+ * terminates early. Otherwise the reviewer's feedback is fed back into the
+ * producer for revision, up to `maxRounds` iterations.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ *   At least two agents are required (producer + reviewer).
+ * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
+ * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ * @throws {AgencyConfigError} When fewer than two agents are provided.
+ */
+export function compileReviewLoop(agents, agencyConfig) {
+    const entries = Object.entries(agents);
+    if (entries.length < 2) {
+        throw new AgencyConfigError('Review-loop strategy requires at least two agents (producer + reviewer).');
+    }
+    const maxRounds = agencyConfig.maxRounds ?? 3;
+    const [producerName, producerConfig] = entries[0];
+    const [reviewerName, reviewerConfig] = entries[1];
+    return {
+        async execute(prompt, opts) {
+            const agentCalls = [];
+            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            const producer = resolveAgent(producerConfig, agencyConfig);
+            const reviewer = resolveAgent(reviewerConfig, agencyConfig);
+            let draft = '';
+            let feedback = '';
+            for (let round = 0; round < maxRounds; round++) {
+                /* ---- HITL: check beforeAgent gate for the producer ---- */
+                const prodDecision = await checkBeforeAgent(producerName, prompt, agentCalls, agencyConfig);
+                if (prodDecision && !prodDecision.approved) {
+                    /* Producer rejected — terminate the loop early. */
+                    break;
+                }
+                /* ---- Producer creates or revises ---- */
+                const prodPrompt = round === 0
+                    ? prompt
+                    : `${prompt}\n\nYour previous draft:\n${draft}\n\nReviewer feedback:\n${feedback}\n\nRevise your work.`;
+                const prodStart = Date.now();
+                const prodResult = (await producer.generate(prodPrompt, opts));
+                const prodDuration = Date.now() - prodStart;
+                const prodText = prodResult.text ?? '';
+                const prodUsage = prodResult.usage ?? {};
+                const prodToolCalls = prodResult.toolCalls ?? [];
+                draft = prodText;
+                agentCalls.push({
+                    agent: producerName,
+                    input: prodPrompt,
+                    output: prodText,
+                    toolCalls: prodToolCalls,
+                    usage: {
+                        promptTokens: prodUsage.promptTokens ?? 0,
+                        completionTokens: prodUsage.completionTokens ?? 0,
+                        totalTokens: prodUsage.totalTokens ?? 0,
+                    },
+                    durationMs: prodDuration,
+                });
+                totalUsage.promptTokens += prodUsage.promptTokens ?? 0;
+                totalUsage.completionTokens += prodUsage.completionTokens ?? 0;
+                totalUsage.totalTokens += prodUsage.totalTokens ?? 0;
+                /* ---- HITL: check beforeAgent gate for the reviewer ---- */
+                const revDecision = await checkBeforeAgent(reviewerName, prompt, agentCalls, agencyConfig);
+                if (revDecision && !revDecision.approved) {
+                    /* Reviewer rejected — accept the current draft and break. */
+                    break;
+                }
+                /* ---- Reviewer evaluates ---- */
+                const revPrompt = `Review this work for the task: "${prompt}"\n\n` +
+                    `Draft:\n${draft}\n\n` +
+                    `Respond with JSON: { "approved": true/false, "feedback": "..." }`;
+                const revStart = Date.now();
+                const revResult = (await reviewer.generate(revPrompt, opts));
+                const revDuration = Date.now() - revStart;
+                const revText = revResult.text ?? '';
+                const revUsage = revResult.usage ?? {};
+                const revToolCalls = revResult.toolCalls ?? [];
+                agentCalls.push({
+                    agent: reviewerName,
+                    input: revPrompt,
+                    output: revText,
+                    toolCalls: revToolCalls,
+                    usage: {
+                        promptTokens: revUsage.promptTokens ?? 0,
+                        completionTokens: revUsage.completionTokens ?? 0,
+                        totalTokens: revUsage.totalTokens ?? 0,
+                    },
+                    durationMs: revDuration,
+                });
+                totalUsage.promptTokens += revUsage.promptTokens ?? 0;
+                totalUsage.completionTokens += revUsage.completionTokens ?? 0;
+                totalUsage.totalTokens += revUsage.totalTokens ?? 0;
+                /* Parse the review decision. */
+                const review = parseReview(revText);
+                if (review.approved)
+                    break;
+                feedback = review.feedback;
+            }
+            return { text: draft, agentCalls, usage: totalUsage };
+        },
+        stream(prompt, opts) {
+            /*
+             * For v1: streaming delegates to execute() and wraps the resolved text
+             * as a single-chunk async iterable. A future version will stream the
+             * producer's output in real-time during the final round.
+             */
+            const resultPromise = this.execute(prompt, opts);
+            const textPromise = resultPromise.then((r) => r.text ?? '');
+            return {
+                textStream: (async function* () {
+                    yield await textPromise;
+                })(),
+                fullStream: (async function* () {
+                    const text = await textPromise;
+                    yield { type: 'text', text };
+                })(),
+                text: textPromise,
+                usage: resultPromise.then((r) => r.usage),
+            };
+        },
+    };
+}
+//# sourceMappingURL=review-loop.js.map

package/dist/api/strategies/review-loop.js.map

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

package/dist/api/strategies/sequential.d.ts

@@ -0,0 +1,15 @@
+import type { AgencyOptions, CompiledStrategy, Agent, BaseAgentConfig } from '../types.js';
+/**
+ * Compiles a sequential execution strategy.
+ *
+ * Agents are invoked one-by-one in their declared iteration order. Each agent
+ * after the first receives a prompt that includes both the original task and
+ * the preceding agent's output, enabling progressive refinement chains such as
+ * researcher -> editor -> reviewer.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
+ * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ */
+export declare function compileSequential(agents: Record<string, BaseAgentConfig | Agent>, agencyConfig: AgencyOptions): CompiledStrategy;
+//# sourceMappingURL=sequential.d.ts.map

package/dist/api/strategies/sequential.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sequential.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/sequential.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,KAAK,EACL,eAAe,EAGhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,KAAK,CAAC,EAC/C,YAAY,EAAE,aAAa,GAC1B,gBAAgB,CAgFlB"}

package/dist/api/strategies/sequential.js

@@ -0,0 +1,94 @@
+/**
+ * @file sequential.ts
+ * Sequential strategy compiler for the Agency API.
+ *
+ * Iterates agents in declaration order. Each agent receives the previous
+ * agent's output as context, forming a chain where the final agent's response
+ * is the overall result. Token usage is aggregated across all agent calls.
+ */
+import { agent as createAgent } from '../agent.js';
+import { isAgent } from './index.js';
+import { mergeDefaults, checkBeforeAgent } from './shared.js';
+/**
+ * Compiles a sequential execution strategy.
+ *
+ * Agents are invoked one-by-one in their declared iteration order. Each agent
+ * after the first receives a prompt that includes both the original task and
+ * the preceding agent's output, enabling progressive refinement chains such as
+ * researcher -> editor -> reviewer.
+ *
+ * @param agents - Named roster of agent configs or pre-built `Agent` instances.
+ * @param agencyConfig - Agency-level configuration providing fallback model/provider/tools.
+ * @returns A {@link CompiledStrategy} with `execute` and `stream` methods.
+ */
+export function compileSequential(agents, agencyConfig) {
+    return {
+        async execute(prompt, opts) {
+            const agentCalls = [];
+            let context = prompt;
+            let lastResult = null;
+            const totalUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+            for (const [name, agentOrConfig] of Object.entries(agents)) {
+                /* HITL: check beforeAgent gate before invoking this agent. */
+                const decision = await checkBeforeAgent(name, context, agentCalls, agencyConfig);
+                if (decision && !decision.approved) {
+                    /* Agent was rejected — skip and continue to the next agent. */
+                    continue;
+                }
+                const a = isAgent(agentOrConfig)
+                    ? agentOrConfig
+                    : createAgent({ ...mergeDefaults(agentOrConfig, agencyConfig) });
+                /* Apply instruction modifications from the approval decision if any. */
+                const effectiveContext = decision?.modifications?.instructions
+                    ? `${context}\n\n[Additional instructions]: ${decision.modifications.instructions}`
+                    : context;
+                const start = Date.now();
+                const result = (await a.generate(effectiveContext, opts));
+                const durationMs = Date.now() - start;
+                const resultText = result.text ?? '';
+                const resultUsage = result.usage ?? {};
+                const resultToolCalls = result.toolCalls ?? [];
+                agentCalls.push({
+                    agent: name,
+                    input: context,
+                    output: resultText,
+                    toolCalls: resultToolCalls,
+                    usage: {
+                        promptTokens: resultUsage.promptTokens ?? 0,
+                        completionTokens: resultUsage.completionTokens ?? 0,
+                        totalTokens: resultUsage.totalTokens ?? 0,
+                    },
+                    durationMs,
+                });
+                totalUsage.promptTokens += resultUsage.promptTokens ?? 0;
+                totalUsage.completionTokens += resultUsage.completionTokens ?? 0;
+                totalUsage.totalTokens += resultUsage.totalTokens ?? 0;
+                /* Chain: subsequent agents see the original task plus previous output. */
+                context = `Original task: ${prompt}\n\nPrevious agent (${name}) output:\n${resultText}`;
+                lastResult = result;
+            }
+            return { ...lastResult, agentCalls, usage: totalUsage };
+        },
+        stream(prompt, opts) {
+            /*
+             * For v1: streaming delegates to execute() and wraps the resolved text
+             * as a single-chunk async iterable. A future version will pipe real
+             * streaming tokens from the final agent.
+             */
+            const resultPromise = this.execute(prompt, opts);
+            const textPromise = resultPromise.then((r) => r.text ?? '');
+            return {
+                textStream: (async function* () {
+                    yield await textPromise;
+                })(),
+                fullStream: (async function* () {
+                    const text = await textPromise;
+                    yield { type: 'text', text };
+                })(),
+                text: textPromise,
+                usage: resultPromise.then((r) => r.usage),
+            };
+        },
+    };
+}
+//# sourceMappingURL=sequential.js.map

package/dist/api/strategies/sequential.js.map

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

package/dist/api/strategies/shared.d.ts

@@ -0,0 +1,36 @@
+import type { AgencyOptions, Agent, BaseAgentConfig, AgentCallRecord, ApprovalDecision } from '../types.js';
+/**
+ * Merge agency-level defaults into an agent config.
+ *
+ * Agent-level values take precedence; tools are merged (agency tools serve as
+ * a base layer, agent tools override on name collision).
+ *
+ * @param agentConfig - Per-agent configuration.
+ * @param agencyConfig - Agency-level fallback values.
+ * @returns A merged config suitable for passing to `agent()`.
+ */
+export declare function mergeDefaults(agentConfig: BaseAgentConfig, agencyConfig: AgencyOptions): BaseAgentConfig;
+/**
+ * Resolves an agent-or-config value into a usable {@link Agent} instance.
+ *
+ * @param agentOrConfig - Either a pre-built Agent or a raw BaseAgentConfig.
+ * @param agencyConfig - Agency-level fallback values for config merging.
+ * @returns A ready-to-call Agent instance.
+ */
+export declare function resolveAgent(agentOrConfig: BaseAgentConfig | Agent, agencyConfig: AgencyOptions): Agent;
+/**
+ * Checks the HITL `beforeAgent` gate for a named agent.
+ *
+ * When the agency-level `hitl.approvals.beforeAgent` list includes the agent
+ * name, this function invokes the HITL handler and returns the decision.
+ * If the agent name is not in the approval list, or no handler is configured,
+ * returns `null` (meaning "no gate — proceed normally").
+ *
+ * @param name - The agent's declared name in the roster.
+ * @param context - The input/context string the agent would receive.
+ * @param agentCalls - Agent call records accumulated so far in this run.
+ * @param agencyConfig - The full agency configuration.
+ * @returns The approval decision, or `null` when no gate applies.
+ */
+export declare function checkBeforeAgent(name: string, context: string, agentCalls: AgentCallRecord[], agencyConfig: AgencyOptions): Promise<ApprovalDecision | null>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/api/strategies/shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EACb,KAAK,EACL,eAAe,EACf,eAAe,EAEf,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAGrB;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,WAAW,EAAE,eAAe,EAC5B,YAAY,EAAE,aAAa,GAC1B,eAAe,CAUjB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,aAAa,EAAE,eAAe,GAAG,KAAK,EACtC,YAAY,EAAE,aAAa,GAC1B,KAAK,CAIP;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,eAAe,EAAE,EAC7B,YAAY,EAAE,aAAa,GAC1B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CA4BlC"}

package/dist/api/strategies/shared.js

@@ -0,0 +1,82 @@
+/**
+ * @file shared.ts
+ * Shared utilities for strategy compilers.
+ *
+ * Centralises `mergeDefaults()`, `resolveAgent()`, and `checkBeforeAgent()`
+ * so every strategy compiler uses a single implementation.
+ */
+import { agent as createAgent } from '../agent.js';
+import { isAgent } from './index.js';
+/**
+ * Merge agency-level defaults into an agent config.
+ *
+ * Agent-level values take precedence; tools are merged (agency tools serve as
+ * a base layer, agent tools override on name collision).
+ *
+ * @param agentConfig - Per-agent configuration.
+ * @param agencyConfig - Agency-level fallback values.
+ * @returns A merged config suitable for passing to `agent()`.
+ */
+export function mergeDefaults(agentConfig, agencyConfig) {
+    return {
+        model: agentConfig.model ?? agencyConfig.model,
+        provider: agentConfig.provider ?? agencyConfig.provider,
+        apiKey: agentConfig.apiKey ?? agencyConfig.apiKey,
+        baseUrl: agentConfig.baseUrl ?? agencyConfig.baseUrl,
+        ...agentConfig,
+        /* Merge tool maps: agency tools as base, agent tools overlay. */
+        tools: { ...(agencyConfig.tools ?? {}), ...(agentConfig.tools ?? {}) },
+    };
+}
+/**
+ * Resolves an agent-or-config value into a usable {@link Agent} instance.
+ *
+ * @param agentOrConfig - Either a pre-built Agent or a raw BaseAgentConfig.
+ * @param agencyConfig - Agency-level fallback values for config merging.
+ * @returns A ready-to-call Agent instance.
+ */
+export function resolveAgent(agentOrConfig, agencyConfig) {
+    return isAgent(agentOrConfig)
+        ? agentOrConfig
+        : createAgent({ ...mergeDefaults(agentOrConfig, agencyConfig) });
+}
+/**
+ * Checks the HITL `beforeAgent` gate for a named agent.
+ *
+ * When the agency-level `hitl.approvals.beforeAgent` list includes the agent
+ * name, this function invokes the HITL handler and returns the decision.
+ * If the agent name is not in the approval list, or no handler is configured,
+ * returns `null` (meaning "no gate — proceed normally").
+ *
+ * @param name - The agent's declared name in the roster.
+ * @param context - The input/context string the agent would receive.
+ * @param agentCalls - Agent call records accumulated so far in this run.
+ * @param agencyConfig - The full agency configuration.
+ * @returns The approval decision, or `null` when no gate applies.
+ */
+export async function checkBeforeAgent(name, context, agentCalls, agencyConfig) {
+    const beforeAgent = agencyConfig.hitl?.approvals?.beforeAgent;
+    const handler = agencyConfig.hitl?.handler;
+    if (!beforeAgent?.includes(name) || !handler) {
+        return null;
+    }
+    const request = {
+        id: crypto.randomUUID(),
+        type: 'agent',
+        agent: name,
+        action: 'execute',
+        description: `Agent "${name}" is about to execute`,
+        details: { input: context },
+        context: {
+            agentCalls,
+            totalTokens: 0,
+            totalCostUSD: 0,
+            elapsedMs: 0,
+        },
+    };
+    agencyConfig.on?.approvalRequested?.(request);
+    const decision = await handler(request);
+    agencyConfig.on?.approvalDecided?.(decision);
+    return decision;
+}
+//# sourceMappingURL=shared.js.map

package/dist/api/strategies/shared.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.js","sourceRoot":"","sources":["../../../src/api/strategies/shared.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,KAAK,IAAI,WAAW,EAAE,MAAM,aAAa,CAAC;AASnD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAErC;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,WAA4B,EAC5B,YAA2B;IAE3B,OAAO;QACL,KAAK,EAAE,WAAW,CAAC,KAAK,IAAI,YAAY,CAAC,KAAK;QAC9C,QAAQ,EAAE,WAAW,CAAC,QAAQ,IAAI,YAAY,CAAC,QAAQ;QACvD,MAAM,EAAE,WAAW,CAAC,MAAM,IAAI,YAAY,CAAC,MAAM;QACjD,OAAO,EAAE,WAAW,CAAC,OAAO,IAAI,YAAY,CAAC,OAAO;QACpD,GAAG,WAAW;QACd,iEAAiE;QACjE,KAAK,EAAE,EAAE,GAAG,CAAC,YAAY,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE;KACvE,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAC1B,aAAsC,EACtC,YAA2B;IAE3B,OAAO,OAAO,CAAC,aAAa,CAAC;QAC3B,CAAC,CAAC,aAAa;QACf,CAAC,CAAC,WAAW,CAAC,EAAE,GAAG,aAAa,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,OAAe,EACf,UAA6B,EAC7B,YAA2B;IAE3B,MAAM,WAAW,GAAG,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC;IAC9D,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC;IAE3C,IAAI,CAAC,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,OAAO,GAAoB;QAC/B,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,IAAI,EAAE,OAAO;QACb,KAAK,EAAE,IAAI;QACX,MAAM,EAAE,SAAS;QACjB,WAAW,EAAE,UAAU,IAAI,uBAAuB;QAClD,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE;QAC3B,OAAO,EAAE;YACP,UAAU;YACV,WAAW,EAAE,CAAC;YACd,YAAY,EAAE,CAAC;YACf,SAAS,EAAE,CAAC;SACb;KACF,CAAC;IAEF,YAAY,CAAC,EAAE,EAAE,iBAAiB,EAAE,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IACxC,YAAY,CAAC,EAAE,EAAE,eAAe,EAAE,CAAC,QAAQ,CAAC,CAAC;IAE7C,OAAO,QAAQ,CAAC;AAClB,CAAC"}