@backendkit-labs/orchestrator-agent 0.1.1

package/AGENT.md

@@ -0,0 +1,69 @@
+# orchestrator-agent
+
+Config-driven orchestration agent. Decomposes natural language tasks into sub-tasks, routes each to the right specialist via `orchestrator.yaml`, and consolidates results. Supports local LLMs (Ollama) and shared knowledge vaults.
+
+## Tools
+
+- `orchestrator_run` — decompose and execute a task end-to-end
+- `orchestrator_list_agents` — list configured specialists
+- `orchestrator_status` — get checkpoint status for resume
+
+## orchestrator.yaml
+
+```yaml
+version: 1
+
+orchestrator:
+  name: "Enterprise Orchestrator"
+  provider: deepseek
+  vault:
+    path: /path/to/shared-vault
+    embedder: simple          # simple (no deps) | ollama (requires Ollama)
+    ollama_host: http://localhost:11434
+    ollama_model: nomic-embed-text
+
+providers:
+  deepseek:
+    api_key: ${DEEPSEEK_API_KEY}
+    base_url: https://api.deepseek.com
+    model: deepseek-chat
+  local:
+    api_key: ollama
+    base_url: http://localhost:11434/v1
+    model: llama3.2:3b
+
+agents:
+  - id: hr
+    name: HR Specialist
+    description: Recursos humanos, nómina, altas y bajas de empleados
+    capabilities: [onboarding, payroll, leave, hr-policies]
+    provider: local               # dato sensible → Ollama, nunca sale de la empresa
+
+  - id: finance
+    name: Finance Specialist
+    description: Presupuestos, facturas y reportes financieros
+    capabilities: [budgeting, invoicing, financial-reports, approvals]
+    provider: local
+
+  - id: code
+    name: Code Specialist
+    description: Desarrollo TypeScript, revisión de código, testing
+    capabilities: [typescript, code-review, testing, refactoring]
+    provider: deepseek
+    transport:
+      type: http
+      url: http://localhost:3001   # optional: connect to specialist MCP server
+```
+
+## Provider rules
+
+| Data type | Provider | Reason |
+|---|---|---|
+| Personal (HR, payroll, legal) | `local` → Ollama | Never leaves the company |
+| Reasoning, reports, code | `deepseek` or `anthropic` | Better quality |
+| Pilot / no Ollama | `simple` embedder | TF-IDF, no dependencies |
+
+## Adding agents
+
+Add an entry to `agents:` in `orchestrator.yaml`. No code changes needed.
+The orchestrator's system prompt is generated from the config at runtime.

package/dist/config.d.ts

@@ -0,0 +1,342 @@
+import { z } from 'zod';
+declare const AgentConfigSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    capabilities: z.ZodArray<z.ZodString, "many">;
+    provider: z.ZodDefault<z.ZodString>;
+    system_prompt: z.ZodOptional<z.ZodString>;
+    transport: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+        type: z.ZodLiteral<"stdio">;
+        command: z.ZodString;
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        type: "stdio";
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    }, {
+        type: "stdio";
+        command: string;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>, z.ZodObject<{
+        type: z.ZodLiteral<"http">;
+        url: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: "http";
+        url: string;
+    }, {
+        type: "http";
+        url: string;
+    }>]>>;
+    gate: z.ZodOptional<z.ZodBoolean>;
+    gate_criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    domain: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    provider: string;
+    id: string;
+    description: string;
+    capabilities: string[];
+    system_prompt?: string | undefined;
+    transport?: {
+        type: "stdio";
+        command: string;
+        args: string[];
+        env?: Record<string, string> | undefined;
+    } | {
+        type: "http";
+        url: string;
+    } | undefined;
+    gate?: boolean | undefined;
+    gate_criteria?: string[] | undefined;
+    domain?: string | undefined;
+}, {
+    name: string;
+    id: string;
+    description: string;
+    capabilities: string[];
+    provider?: string | undefined;
+    system_prompt?: string | undefined;
+    transport?: {
+        type: "stdio";
+        command: string;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    } | {
+        type: "http";
+        url: string;
+    } | undefined;
+    gate?: boolean | undefined;
+    gate_criteria?: string[] | undefined;
+    domain?: string | undefined;
+}>;
+declare const ProviderConfigSchema: z.ZodObject<{
+    api_key: z.ZodOptional<z.ZodString>;
+    base_url: z.ZodOptional<z.ZodString>;
+    model: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    api_key?: string | undefined;
+    base_url?: string | undefined;
+}, {
+    model: string;
+    api_key?: string | undefined;
+    base_url?: string | undefined;
+}>;
+declare const VaultConfigSchema: z.ZodObject<{
+    path: z.ZodString;
+    embedder: z.ZodDefault<z.ZodEnum<["simple", "ollama"]>>;
+    ollama_host: z.ZodDefault<z.ZodString>;
+    ollama_model: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    embedder: "simple" | "ollama";
+    ollama_host: string;
+    ollama_model: string;
+}, {
+    path: string;
+    embedder?: "simple" | "ollama" | undefined;
+    ollama_host?: string | undefined;
+    ollama_model?: string | undefined;
+}>;
+export declare const OrchestratorConfigSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodNumber>;
+    orchestrator: z.ZodObject<{
+        name: z.ZodDefault<z.ZodString>;
+        provider: z.ZodDefault<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        vault: z.ZodOptional<z.ZodObject<{
+            path: z.ZodString;
+            embedder: z.ZodDefault<z.ZodEnum<["simple", "ollama"]>>;
+            ollama_host: z.ZodDefault<z.ZodString>;
+            ollama_model: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            path: string;
+            embedder: "simple" | "ollama";
+            ollama_host: string;
+            ollama_model: string;
+        }, {
+            path: string;
+            embedder?: "simple" | "ollama" | undefined;
+            ollama_host?: string | undefined;
+            ollama_model?: string | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        provider: string;
+        model?: string | undefined;
+        vault?: {
+            path: string;
+            embedder: "simple" | "ollama";
+            ollama_host: string;
+            ollama_model: string;
+        } | undefined;
+    }, {
+        name?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        vault?: {
+            path: string;
+            embedder?: "simple" | "ollama" | undefined;
+            ollama_host?: string | undefined;
+            ollama_model?: string | undefined;
+        } | undefined;
+    }>;
+    providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        api_key: z.ZodOptional<z.ZodString>;
+        base_url: z.ZodOptional<z.ZodString>;
+        model: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        model: string;
+        api_key?: string | undefined;
+        base_url?: string | undefined;
+    }, {
+        model: string;
+        api_key?: string | undefined;
+        base_url?: string | undefined;
+    }>>>;
+    agents: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodString;
+        capabilities: z.ZodArray<z.ZodString, "many">;
+        provider: z.ZodDefault<z.ZodString>;
+        system_prompt: z.ZodOptional<z.ZodString>;
+        transport: z.ZodOptional<z.ZodDiscriminatedUnion<"type", [z.ZodObject<{
+            type: z.ZodLiteral<"stdio">;
+            command: z.ZodString;
+            args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        }, "strip", z.ZodTypeAny, {
+            type: "stdio";
+            command: string;
+            args: string[];
+            env?: Record<string, string> | undefined;
+        }, {
+            type: "stdio";
+            command: string;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        }>, z.ZodObject<{
+            type: z.ZodLiteral<"http">;
+            url: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            type: "http";
+            url: string;
+        }, {
+            type: "http";
+            url: string;
+        }>]>>;
+        gate: z.ZodOptional<z.ZodBoolean>;
+        gate_criteria: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        domain: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        provider: string;
+        id: string;
+        description: string;
+        capabilities: string[];
+        system_prompt?: string | undefined;
+        transport?: {
+            type: "stdio";
+            command: string;
+            args: string[];
+            env?: Record<string, string> | undefined;
+        } | {
+            type: "http";
+            url: string;
+        } | undefined;
+        gate?: boolean | undefined;
+        gate_criteria?: string[] | undefined;
+        domain?: string | undefined;
+    }, {
+        name: string;
+        id: string;
+        description: string;
+        capabilities: string[];
+        provider?: string | undefined;
+        system_prompt?: string | undefined;
+        transport?: {
+            type: "stdio";
+            command: string;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        } | {
+            type: "http";
+            url: string;
+        } | undefined;
+        gate?: boolean | undefined;
+        gate_criteria?: string[] | undefined;
+        domain?: string | undefined;
+    }>, "many">;
+    flows: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        file: z.ZodString;
+        trigger: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        file: string;
+        trigger?: string | undefined;
+    }, {
+        id: string;
+        file: string;
+        trigger?: string | undefined;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: number;
+    orchestrator: {
+        name: string;
+        provider: string;
+        model?: string | undefined;
+        vault?: {
+            path: string;
+            embedder: "simple" | "ollama";
+            ollama_host: string;
+            ollama_model: string;
+        } | undefined;
+    };
+    providers: Record<string, {
+        model: string;
+        api_key?: string | undefined;
+        base_url?: string | undefined;
+    }>;
+    agents: {
+        name: string;
+        provider: string;
+        id: string;
+        description: string;
+        capabilities: string[];
+        system_prompt?: string | undefined;
+        transport?: {
+            type: "stdio";
+            command: string;
+            args: string[];
+            env?: Record<string, string> | undefined;
+        } | {
+            type: "http";
+            url: string;
+        } | undefined;
+        gate?: boolean | undefined;
+        gate_criteria?: string[] | undefined;
+        domain?: string | undefined;
+    }[];
+    flows?: {
+        id: string;
+        file: string;
+        trigger?: string | undefined;
+    }[] | undefined;
+}, {
+    orchestrator: {
+        name?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+        vault?: {
+            path: string;
+            embedder?: "simple" | "ollama" | undefined;
+            ollama_host?: string | undefined;
+            ollama_model?: string | undefined;
+        } | undefined;
+    };
+    agents: {
+        name: string;
+        id: string;
+        description: string;
+        capabilities: string[];
+        provider?: string | undefined;
+        system_prompt?: string | undefined;
+        transport?: {
+            type: "stdio";
+            command: string;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        } | {
+            type: "http";
+            url: string;
+        } | undefined;
+        gate?: boolean | undefined;
+        gate_criteria?: string[] | undefined;
+        domain?: string | undefined;
+    }[];
+    version?: number | undefined;
+    providers?: Record<string, {
+        model: string;
+        api_key?: string | undefined;
+        base_url?: string | undefined;
+    }> | undefined;
+    flows?: {
+        id: string;
+        file: string;
+        trigger?: string | undefined;
+    }[] | undefined;
+}>;
+export type OrchestratorConfig = z.infer<typeof OrchestratorConfigSchema>;
+export type AgentConfig = z.infer<typeof AgentConfigSchema>;
+export type ProviderConfig = z.infer<typeof ProviderConfigSchema>;
+export type VaultConfig = z.infer<typeof VaultConfigSchema>;
+export declare function loadConfig(configPath: string): OrchestratorConfig;
+export declare function resolveProviderConfig(config: OrchestratorConfig, providerId: string): ProviderConfig | null;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAoBxB,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWrB,CAAC;AAEH,QAAA,MAAM,oBAAoB;;;;;;;;;;;;EAIxB,CAAC;AAEH,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;EAKrB,CAAC;AAQH,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAWnC,CAAC;AAIH,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAC1E,MAAM,MAAM,WAAW,GAAU,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AACnE,MAAM,MAAM,cAAc,GAAO,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AACtE,MAAM,MAAM,WAAW,GAAU,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAInE,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,CAajE;AAiBD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,GAAG,cAAc,GAAG,IAAI,CAE3G"}

package/dist/config.js

@@ -0,0 +1,88 @@
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'node:fs';
+import * as path from 'node:path';
+import * as yaml from 'yaml';
+// ── Schemas ───────────────────────────────────────────────────────────────────
+const TransportSchema = z.discriminatedUnion('type', [
+    z.object({
+        type: z.literal('stdio'),
+        command: z.string(),
+        args: z.array(z.string()).default([]),
+        env: z.record(z.string()).optional(),
+    }),
+    z.object({
+        type: z.literal('http'),
+        url: z.string(),
+    }),
+]);
+const AgentConfigSchema = z.object({
+    id: z.string(),
+    name: z.string(),
+    description: z.string(),
+    capabilities: z.array(z.string()),
+    provider: z.string().default('default'),
+    system_prompt: z.string().optional(),
+    transport: TransportSchema.optional(),
+    gate: z.boolean().optional(), // pause for human approval after this agent
+    gate_criteria: z.array(z.string()).optional(), // criteria shown to the approver
+    domain: z.string().optional(), // enterprise reflection domain (e.g. 'rrhh', 'legal')
+});
+const ProviderConfigSchema = z.object({
+    api_key: z.string().optional(),
+    base_url: z.string().optional(),
+    model: z.string(),
+});
+const VaultConfigSchema = z.object({
+    path: z.string(),
+    embedder: z.enum(['simple', 'ollama']).default('simple'),
+    ollama_host: z.string().default('http://localhost:11434'),
+    ollama_model: z.string().default('nomic-embed-text'),
+});
+const FlowEntryConfigSchema = z.object({
+    id: z.string(),
+    file: z.string(),
+    trigger: z.string().optional(),
+});
+export const OrchestratorConfigSchema = z.object({
+    version: z.number().default(1),
+    orchestrator: z.object({
+        name: z.string().default('Orchestrator'),
+        provider: z.string().default('default'),
+        model: z.string().optional(),
+        vault: VaultConfigSchema.optional(),
+    }),
+    providers: z.record(ProviderConfigSchema).default({}),
+    agents: z.array(AgentConfigSchema).min(1, 'At least one agent must be configured'),
+    flows: z.array(FlowEntryConfigSchema).optional(),
+});
+// ── Loader ────────────────────────────────────────────────────────────────────
+export function loadConfig(configPath) {
+    const resolved = path.resolve(configPath);
+    if (!existsSync(resolved)) {
+        throw new Error(`Config not found: ${resolved}`);
+    }
+    const raw = yaml.parse(readFileSync(resolved, 'utf-8'));
+    const expanded = expandEnv(raw);
+    const result = OrchestratorConfigSchema.safeParse(expanded);
+    if (!result.success) {
+        const issues = result.error.issues.map(i => `  ${i.path.join('.')}: ${i.message}`).join('\n');
+        throw new Error(`Invalid orchestrator config:\n${issues}`);
+    }
+    return result.data;
+}
+// ── Helpers ───────────────────────────────────────────────────────────────────
+function expandEnv(obj) {
+    if (typeof obj === 'string') {
+        return obj.replace(/\$\{(\w+)\}/g, (_, key) => process.env[key] ?? '');
+    }
+    if (Array.isArray(obj))
+        return obj.map(expandEnv);
+    if (obj !== null && typeof obj === 'object') {
+        return Object.fromEntries(Object.entries(obj).map(([k, v]) => [k, expandEnv(v)]));
+    }
+    return obj;
+}
+export function resolveProviderConfig(config, providerId) {
+    return config.providers[providerId] ?? null;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/executor.d.ts

@@ -0,0 +1,99 @@
+import { AgentEngine, defineTool } from '@backendkit-labs/agent-core';
+import type { AgentProfile } from '@backendkit-labs/agent-core';
+import type { OrchestratorConfig } from './config.js';
+import type { TaskPlan } from './planner.js';
+export interface ExecutionResult {
+    subtask_id: string;
+    agent_id: string;
+    task: string;
+    result: string;
+    success: boolean;
+    duration_ms: number;
+}
+export interface PlanExecution {
+    plan: TaskPlan;
+    results: ExecutionResult[];
+    summary: string;
+    complete: boolean;
+}
+/** Returned instead of PlanExecution when a gate step is reached. */
+export interface GateHit {
+    gateRequired: true;
+    stepId: string;
+    agentId: string;
+    output: string;
+    criteria: string[];
+    completedSoFar: ExecutionResult[];
+    /** IDs of policyRules that forced this gate (empty when gate is explicit in YAML/config). */
+    appliedRuleIds: string[];
+}
+/**
+ * Minimal interface for the enterprise reflection adapter (Cable 2).
+ * EnterpriseReflection from @backendkit-labs/agent-enterprise satisfies this
+ * structurally — no direct import needed, avoiding circular dep on publish cycle.
+ */
+export interface ReflectionAdapter {
+    activeRules(filter?: {
+        domain?: string;
+    }): Promise<Array<{
+        id: string;
+        name: string;
+        trigger: {
+            domain: string;
+            pattern: string;
+            minOccurrences: number;
+        };
+        if: {
+            domain?: string | string[];
+            keywords?: string[];
+            [k: string]: unknown;
+        };
+        then: {
+            mustInclude?: string[];
+            mustPass?: string[];
+            mustExecute?: string[];
+            requireArchitectureReview?: boolean;
+            requireSecurityReview?: boolean;
+            requireQaApproval?: boolean;
+            [k: string]: unknown;
+        };
+    }>>;
+    recordRuleOutcome(ruleId: string, outcome: 'success' | 'failure'): Promise<void>;
+}
+export interface ExecutorOptions {
+    config: OrchestratorConfig;
+    ragSearchFn?: (query: string) => Promise<string>;
+    onProgress?: (msg: string) => void;
+    /** Enterprise reflection adapter for deterministic rule enforcement (Cable 2). */
+    reflection?: ReflectionAdapter;
+}
+export declare class PlanExecutor {
+    private readonly config;
+    private readonly ragSearchFn;
+    private readonly onProgress;
+    private readonly reflection;
+    constructor(opts: ExecutorOptions);
+    /**
+     * Execute a plan from scratch or resume after a gate approval.
+     *
+     * @param plan           Full task plan.
+     * @param priorResults   Steps already completed in a previous execution segment
+     *                       (used when resuming after a gate). Those steps are treated
+     *                       as done and skipped.
+     */
+    execute(plan: TaskPlan, priorResults?: ExecutionResult[]): Promise<PlanExecution | GateHit>;
+    private runSubTask;
+    private runSpecialist;
+    /**
+     * Cable 2: query active policyRules and match against this subtask.
+     * Returns matched rule IDs and the criteria text to show the human approver.
+     * No-op when reflection is not configured.
+     */
+    private checkActiveRules;
+    private consolidate;
+}
+export declare function buildOrchestratorEngine(opts: ExecutorOptions & {
+    orchestratorProfile: AgentProfile;
+    ragTool?: ReturnType<typeof defineTool>;
+}): AgentEngine;
+//# sourceMappingURL=executor.d.ts.map

package/dist/executor.d.ts.map

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