openbot 0.2.3 → 0.2.6

package/dist/registry/yaml-agent-loader.js

@@ -1,11 +1,11 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import yaml from "js-yaml";
+import matter from "gray-matter";
 import { llmPlugin } from "../plugins/llm/index.js";
 import { PluginRegistry } from "./plugin-registry.js";
 import { createModel } from "../models.js";
 import { loadPluginsFromDir } from "./plugin-loader.js";
-import { resolvePath } from "../config.js";
+import { resolvePath, DEFAULT_AGENT_MD } from "../config.js";
 /**
  * Recursively resolve tilde paths in a configuration object.
  */
@@ -26,12 +26,29 @@ function resolveConfigPaths(config) {
     return config;
 }
 /**
- * Read and parse an agent.yaml file from a directory.
+ * Read and parse an agent configuration from AGENT.md with frontmatter.
  */
 export async function readAgentConfig(agentDir) {
-    const yamlPath = path.join(agentDir, "agent.yaml");
-    const content = await fs.readFile(yamlPath, "utf-8");
-    return yaml.load(content);
+    const mdPath = path.join(agentDir, "AGENT.md");
+    const folderName = path.basename(agentDir);
+    let mdContent = "";
+    try {
+        mdContent = await fs.readFile(mdPath, "utf-8");
+    }
+    catch {
+        // Fallback to a default template if AGENT.md is missing
+        mdContent = DEFAULT_AGENT_MD.replace("name: Agent", `name: ${folderName}`);
+    }
+    const parsed = matter(mdContent);
+    const config = (parsed.data || {});
+    return {
+        name: config.name || folderName,
+        description: config.description || `The ${folderName} agent`,
+        model: config.model,
+        plugins: config.plugins || [],
+        systemPrompt: parsed.content.trim() || "",
+        subscribe: config.subscribe,
+    };
 }
 /**
  * Discover YAML-defined agents from a directory without loading plugins.
@@ -41,6 +58,7 @@ export async function readAgentConfig(agentDir) {
  */
 export async function listYamlAgents(agentsDir) {
     const agents = [];
+    const seenNames = new Set();
     try {
         const entries = await fs.readdir(agentsDir, { withFileTypes: true });
         for (const entry of entries) {
@@ -49,14 +67,42 @@ export async function listYamlAgents(agentsDir) {
             if (entry.name.startsWith(".") || entry.name.startsWith("_"))
                 continue;
             const agentDir = path.join(agentsDir, entry.name);
+            // Check if it's a TS agent (has package.json but NO AGENT.md)
+            const hasMd = await fs.access(path.join(agentDir, "AGENT.md")).then(() => true).catch(() => false);
+            const hasPkg = await fs.access(path.join(agentDir, "package.json")).then(() => true).catch(() => false);
+            if (!hasMd && hasPkg) {
+                let description = "TypeScript Agent (editable via files only)";
+                let name = entry.name;
+                try {
+                    const pkg = JSON.parse(await fs.readFile(path.join(agentDir, "package.json"), "utf-8"));
+                    if (pkg.description)
+                        description = pkg.description;
+                    if (pkg.name)
+                        name = pkg.name;
+                }
+                catch {
+                    // Ignore
+                }
+                if (!seenNames.has(name)) {
+                    agents.push({
+                        name,
+                        description,
+                        folder: agentDir,
+                        isTs: true,
+                    });
+                    seenNames.add(name);
+                }
+                continue;
+            }
             try {
                 const config = await readAgentConfig(agentDir);
-                if (config.name && config.description) {
+                if (config.name && config.description && !seenNames.has(config.name)) {
                     agents.push({
                         name: config.name,
                         description: config.description,
                         folder: agentDir,
                     });
+                    seenNames.add(config.name);
                 }
             }
             catch {
@@ -72,7 +118,7 @@ export async function listYamlAgents(agentsDir) {
 /**
  * Discover and load YAML-defined agents from a directory.
  *
- * Scans `agentsDir` for subdirectories containing an `agent.yaml` file,
+ * Scans `agentsDir` for subdirectories containing an `AGENT.md` file,
  * parses each one, and composes a Melony plugin from the referenced plugins.
  *
  * @param agentsDir  Absolute path to the agents directory (e.g. ~/.openbot/agents)
@@ -83,6 +129,7 @@ export async function listYamlAgents(agentsDir) {
  */
 export async function discoverYamlAgents(agentsDir, pluginRegistry, defaultModel, options) {
     const agents = [];
+    const seenNames = new Set();
     // Ensure the agents directory exists
     try {
         await fs.mkdir(agentsDir, { recursive: true });
@@ -97,15 +144,19 @@ export async function discoverYamlAgents(agentsDir, pluginRegistry, defaultModel
                 continue;
             if (entry.name.startsWith(".") || entry.name.startsWith("_"))
                 continue;
-            const yamlPath = path.join(agentsDir, entry.name, "agent.yaml");
             const agentDir = path.join(agentsDir, entry.name);
+            // Skip TS agents (they don't need AGENT.md)
+            const hasMd = await fs.access(path.join(agentDir, "AGENT.md")).then(() => true).catch(() => false);
+            const hasPkg = await fs.access(path.join(agentDir, "package.json")).then(() => true).catch(() => false);
+            if (!hasMd && hasPkg)
+                continue;
             try {
                 const config = await readAgentConfig(agentDir);
-                // Validate required fields
-                if (!config.name || !config.description || !config.plugins?.length || !config.systemPrompt) {
-                    console.warn(`[agents] "${entry.name}/agent.yaml": missing required fields (name, description, plugins, systemPrompt) — skipping`);
+                // Validate required fields and avoid duplicates
+                if (!config.name || !config.description || seenNames.has(config.name)) {
                     continue;
                 }
+                seenNames.add(config.name);
                 const agentModel = config.model
                     ? createModel({ ...options, model: config.model })
                     : defaultModel;
@@ -122,7 +173,17 @@ export async function discoverYamlAgents(agentsDir, pluginRegistry, defaultModel
                 for (const p of localPlugins) {
                     scopedRegistry.register(p);
                 }
-                const { plugin, toolDefinitions } = composeAgentFromYaml(config, scopedRegistry, agentModel);
+                // Initialize AGENT.md if it doesn't exist (using the template)
+                const agentMdPath = path.join(agentDir, "AGENT.md");
+                try {
+                    await fs.access(agentMdPath);
+                }
+                catch {
+                    const content = DEFAULT_AGENT_MD.replace("name: Agent", `name: ${config.name}`);
+                    await fs.writeFile(agentMdPath, content, "utf-8");
+                    console.log(`[agents] Initialized ${config.name}/AGENT.md`);
+                }
+                const { plugin, toolDefinitions } = composeAgentFromConfig(config, scopedRegistry, agentModel);
                 agents.push({
                     name: config.name,
                     description: config.description,
@@ -136,9 +197,9 @@ export async function discoverYamlAgents(agentsDir, pluginRegistry, defaultModel
                 console.log(`[agents] Loaded: ${config.name} — ${config.description}${config.model ? ` (model: ${config.model})` : ""}`);
             }
             catch (err) {
-                // Invalid or missing agent.yaml — silently skip if missing, warn if invalid
+                // Skip invalid agents
                 if (err.code !== 'ENOENT') {
-                    console.warn(`[agents] Error loading "${entry.name}/agent.yaml":`, err);
+                    console.warn(`[agents] Error loading "${entry.name}":`, err);
                 }
             }
         }
@@ -149,12 +210,12 @@ export async function discoverYamlAgents(agentsDir, pluginRegistry, defaultModel
     return agents;
 }
 /**
- * Compose a Melony plugin from a YAML agent configuration.
+ * Compose a Melony plugin from an agent configuration.
  *
  * Resolves each plugin name against the registry, collects their tool definitions,
  * and wires them with an agent-scoped LLM plugin.
  */
-function composeAgentFromYaml(config, pluginRegistry, model) {
+function composeAgentFromConfig(config, pluginRegistry, model) {
     const allToolDefinitions = {};
     const pluginFactories = [];
     for (const pluginItem of config.plugins) {
@@ -179,9 +240,6 @@ function composeAgentFromYaml(config, pluginRegistry, model) {
             model,
             system: config.systemPrompt,
             toolDefinitions: allToolDefinitions,
-            promptInputType: `agent:${config.name}:input`,
-            actionResultInputType: `agent:${config.name}:result`,
-            completionEventType: `agent:${config.name}:output`,
         }));
     };
     return { plugin, toolDefinitions: allToolDefinitions };

package/dist/runtime/execution-trace.js

@@ -0,0 +1,41 @@
+function nowIso() {
+    return new Date().toISOString();
+}
+export function createTraceId(runId) {
+    return `trace_${runId}_${Date.now()}`;
+}
+export function hasPendingApprovals(state) {
+    const agentStates = state.agentStates || {};
+    return Object.values(agentStates).some((agentState) => !!agentState.pendingApprovals &&
+        Object.keys(agentState.pendingApprovals).length > 0);
+}
+export function setExecutionState(state, patch) {
+    const hasCurrentStepId = Object.prototype.hasOwnProperty.call(patch, "currentStepId");
+    const hasError = Object.prototype.hasOwnProperty.call(patch, "error");
+    const hasIntentType = Object.prototype.hasOwnProperty.call(patch, "intentType");
+    const hasPlanSteps = Object.prototype.hasOwnProperty.call(patch, "planSteps");
+    const next = {
+        traceId: patch.traceId ?? state.execution?.traceId ?? `trace_${Date.now()}`,
+        state: patch.state ?? state.execution?.state ?? "RECEIVED",
+        currentStepId: hasCurrentStepId ? patch.currentStepId : state.execution?.currentStepId,
+        error: hasError ? patch.error : state.execution?.error,
+        intentType: hasIntentType ? patch.intentType : state.execution?.intentType,
+        planSteps: hasPlanSteps ? patch.planSteps : state.execution?.planSteps,
+        updatedAt: nowIso(),
+    };
+    state.execution = next;
+    return next;
+}
+export function executionStateEvent(trace) {
+    return {
+        type: "execution:state",
+        data: {
+            traceId: trace?.traceId,
+            state: trace?.state,
+            currentStepId: trace?.currentStepId,
+            error: trace?.error,
+            intentType: trace?.intentType,
+            planSteps: trace?.planSteps,
+        },
+    };
+}

package/dist/runtime/intent-routing.js

@@ -0,0 +1,26 @@
+const TASK_HINT_REGEX = /\b(create|build|write|fix|update|implement|run|execute|open|edit|delete|list|plan|analyze|research|refactor|install|configure|debug|deploy)\b/i;
+export function parseDirectAgent(content, knownAgents) {
+    const raw = content.trim();
+    if (!raw || (!raw.startsWith("/") && !raw.startsWith("@")))
+        return null;
+    const firstSpace = raw.indexOf(" ");
+    const candidate = firstSpace === -1 ? raw.slice(1) : raw.slice(1, firstSpace);
+    if (!knownAgents.has(candidate))
+        return null;
+    const task = firstSpace === -1 ? "" : raw.slice(firstSpace + 1).trim();
+    return { agentName: candidate, task };
+}
+export function classifyIntent(content, knownAgents) {
+    const raw = content.trim();
+    const direct = parseDirectAgent(raw, knownAgents);
+    if (direct) {
+        return { type: "agent_direct", targetAgent: direct.agentName };
+    }
+    if (!raw) {
+        return { type: "chat" };
+    }
+    if (TASK_HINT_REGEX.test(raw)) {
+        return { type: "task" };
+    }
+    return { type: "chat" };
+}

package/dist/runtime/openbot-runtime.js

@@ -0,0 +1,354 @@
+import { melony } from "melony";
+import { classifyIntent, parseDirectAgent } from "./intent-routing.js";
+import { createTraceId, executionStateEvent, hasPendingApprovals, setExecutionState, } from "./execution-trace.js";
+const AGENT_TEXT_TYPES = new Set(["assistant:text-delta", "assistant:text"]);
+const MAX_DELEGATIONS_PER_MANAGER_RUN = 6;
+const DIRECT_TITLE_CONTEXT_LIMIT = 20;
+function isAgentTextEvent(event) {
+    return AGENT_TEXT_TYPES.has(event.type);
+}
+export class OpenBotRuntime {
+    constructor(options) {
+        this.managerPlugin = options.managerPlugin;
+        this.agents = new Map(options.agents.map((a) => [a.name, a]));
+    }
+    buildManagerRuntime() {
+        const builder = melony();
+        builder.use(this.managerPlugin);
+        builder.on("action:taskResult", async function* (event) {
+            yield { type: "manager:result", data: event.data };
+        });
+        return builder.build();
+    }
+    buildAgentRuntime(agent) {
+        const builder = melony();
+        builder.use(agent.plugin);
+        const name = agent.name;
+        builder.on("action:taskResult", async function* (event) {
+            yield { type: `agent:${name}:result`, data: event.data };
+        });
+        return builder.build();
+    }
+    getAgentState(agentName, sessionState) {
+        if (!sessionState.agentStates)
+            sessionState.agentStates = {};
+        if (!sessionState.agentStates[agentName]) {
+            sessionState.agentStates[agentName] = {};
+        }
+        const agentState = sessionState.agentStates[agentName];
+        if (!agentState.cwd)
+            agentState.cwd = sessionState.cwd;
+        return agentState;
+    }
+    appendSessionMessage(sessionState, message) {
+        if (!sessionState.messages)
+            sessionState.messages = [];
+        sessionState.messages.push(message);
+        if (sessionState.messages.length > DIRECT_TITLE_CONTEXT_LIMIT) {
+            sessionState.messages = sessionState.messages.slice(-DIRECT_TITLE_CONTEXT_LIMIT);
+        }
+    }
+    async *triggerTopicRefresh(sessionState, runId) {
+        const runtime = this.buildManagerRuntime();
+        for await (const yielded of runtime.run({
+            type: "manager:completion",
+            data: { content: "" },
+        }, { state: sessionState, runId })) {
+            yield yielded;
+        }
+    }
+    estimatePlanSteps(planText) {
+        const trimmed = planText.trim();
+        if (!trimmed)
+            return undefined;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (Array.isArray(parsed?.steps))
+                return parsed.steps.length;
+        }
+        catch {
+            // Best-effort parse only.
+        }
+        return undefined;
+    }
+    buildManagerTaskInput(userIntent, planText) {
+        return `User intent:\n${userIntent}\n\nPlanner output (treat as proposed execution plan):\n${planText}\n\nExecute this pragmatically. Delegate concrete subtasks to relevant specialist agents when needed. Keep user-facing updates concise.`;
+    }
+    async *runPlannerAgent(content, attachments, sessionState, runId) {
+        const plannerName = "planner-agent";
+        if (!this.agents.has(plannerName)) {
+            return "";
+        }
+        let plannerOutput = "";
+        for await (const yielded of this.runAgentInternal(plannerName, content, attachments, sessionState, runId)) {
+            if (yielded.type === `agent:${plannerName}:output`) {
+                plannerOutput = yielded.data.content || "";
+            }
+            if (!isAgentTextEvent(yielded) && yielded.type !== `agent:${plannerName}:output`) {
+                yield yielded;
+            }
+        }
+        return plannerOutput;
+    }
+    async *run(event, options) {
+        const { state, runId = `run_${Date.now()}` } = options;
+        yield event;
+        if (event.type === "action:approve" || event.type === "action:deny") {
+            const trace = setExecutionState(state, {
+                state: "EXECUTING",
+                error: undefined,
+            });
+            yield executionStateEvent(trace);
+            yield* this.routeApproval(event, state, runId);
+            return;
+        }
+        if (event.type === "user:text" || event.type === "user:multimodal") {
+            const rawContent = event.data.content;
+            const content = typeof rawContent === "string" ? rawContent.trim() : "";
+            const attachments = Array.isArray(event.data.attachments)
+                ? event.data.attachments
+                : undefined;
+            const knownAgents = new Set(this.agents.keys());
+            const direct = parseDirectAgent(content, knownAgents);
+            const intent = classifyIntent(content, knownAgents);
+            let trace = setExecutionState(state, {
+                traceId: createTraceId(runId),
+                state: "RECEIVED",
+                intentType: intent.type,
+                error: undefined,
+                currentStepId: undefined,
+                planSteps: undefined,
+            });
+            yield executionStateEvent(trace);
+            try {
+                if (direct) {
+                    this.appendSessionMessage(state, {
+                        role: "user",
+                        content,
+                        attachments,
+                    });
+                    trace = setExecutionState(state, {
+                        state: "EXECUTING",
+                        currentStepId: `delegate:${direct.agentName}`,
+                    });
+                    yield executionStateEvent(trace);
+                    yield* this.runAgentDirect(direct.agentName, direct.task, attachments, state, runId);
+                    const finalTrace = setExecutionState(state, {
+                        state: hasPendingApprovals(state) ? "WAITING_APPROVAL" : "COMPLETED",
+                        currentStepId: hasPendingApprovals(state)
+                            ? `delegate:${direct.agentName}`
+                            : undefined,
+                        error: undefined,
+                    });
+                    yield executionStateEvent(finalTrace);
+                    return;
+                }
+                trace = setExecutionState(state, {
+                    state: "EXECUTING",
+                    currentStepId: intent.type === "task" ? "planner" : "manager",
+                });
+                yield executionStateEvent(trace);
+                let managerInput = content;
+                if (intent.type === "task" && this.agents.has("planner-agent")) {
+                    const plannerResult = yield* this.runPlannerAgent(content, attachments, state, runId);
+                    if (plannerResult.trim()) {
+                        managerInput = this.buildManagerTaskInput(content, plannerResult);
+                        trace = setExecutionState(state, {
+                            currentStepId: "manager",
+                            planSteps: this.estimatePlanSteps(plannerResult),
+                        });
+                        yield executionStateEvent(trace);
+                    }
+                }
+                yield* this.runManagerLoop({
+                    type: "manager:input",
+                    data: { content: managerInput, attachments },
+                }, state, runId);
+                const waiting = hasPendingApprovals(state);
+                const finalTrace = setExecutionState(state, {
+                    state: waiting ? "WAITING_APPROVAL" : "COMPLETED",
+                    currentStepId: waiting ? (state.execution?.currentStepId ?? "manager") : undefined,
+                    error: undefined,
+                });
+                yield executionStateEvent(finalTrace);
+                return;
+            }
+            catch (error) {
+                const finalTrace = setExecutionState(state, {
+                    state: "FAILED",
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                yield executionStateEvent(finalTrace);
+                throw error;
+            }
+        }
+        yield* this.runManagerLoop(event, state, runId);
+    }
+    async *runManagerLoop(event, state, runId) {
+        const runtime = this.buildManagerRuntime();
+        const delegationSignatures = new Set();
+        let delegationCount = 0;
+        let nextManagerEvent = event;
+        while (nextManagerEvent) {
+            const managerEvent = nextManagerEvent;
+            nextManagerEvent = undefined;
+            for await (const yielded of runtime.run(managerEvent, { state, runId })) {
+                if (yielded.type !== "action:delegateTask") {
+                    yield yielded;
+                    continue;
+                }
+                const { agent: agentName, task, attachments, toolCallId } = yielded.data;
+                const normalizedTask = typeof task === "string"
+                    ? task.replace(/\s+/g, " ").trim().toLowerCase()
+                    : "";
+                const signature = `${agentName}::${normalizedTask}`;
+                if (delegationCount >= MAX_DELEGATIONS_PER_MANAGER_RUN ||
+                    (normalizedTask && delegationSignatures.has(signature))) {
+                    nextManagerEvent = {
+                        type: "manager:result",
+                        data: {
+                            action: "delegateTask",
+                            toolCallId,
+                            result: `Error: delegation loop detected for agent "${agentName}". Summarize current progress and stop delegating.`,
+                        },
+                    };
+                    break;
+                }
+                if (!this.agents.has(agentName)) {
+                    nextManagerEvent = {
+                        type: "manager:result",
+                        data: {
+                            action: "delegateTask",
+                            toolCallId,
+                            result: `Error: Agent "${agentName}" not found`,
+                        },
+                    };
+                    break;
+                }
+                delegationCount += 1;
+                if (normalizedTask)
+                    delegationSignatures.add(signature);
+                if (!state.pendingAgentTasks)
+                    state.pendingAgentTasks = {};
+                state.pendingAgentTasks[agentName] = { toolCallId };
+                let agentOutput = "";
+                let agentCompleted = false;
+                try {
+                    for await (const agentEvent of this.runAgentInternal(agentName, task, attachments, state, runId)) {
+                        if (agentEvent.type === `agent:${agentName}:output`) {
+                            agentOutput = agentEvent.data.content;
+                            agentCompleted = true;
+                        }
+                        if (!isAgentTextEvent(agentEvent)) {
+                            yield agentEvent;
+                        }
+                    }
+                }
+                catch (error) {
+                    agentOutput = `Error: ${error instanceof Error ? error.message : String(error)}`;
+                    agentCompleted = true;
+                }
+                if (agentCompleted) {
+                    delete state.pendingAgentTasks[agentName];
+                    nextManagerEvent = {
+                        type: "manager:result",
+                        data: {
+                            action: "delegateTask",
+                            toolCallId,
+                            result: agentOutput,
+                        },
+                    };
+                }
+                break;
+            }
+        }
+    }
+    async *runAgentInternal(agentName, task, attachments, sessionState, runId) {
+        const agent = this.agents.get(agentName);
+        const agentState = this.getAgentState(agentName, sessionState);
+        const runtime = this.buildAgentRuntime(agent);
+        const inputEvent = {
+            type: `agent:${agentName}:input`,
+            data: { content: task, attachments },
+        };
+        for await (const yielded of runtime.run(inputEvent, {
+            state: agentState,
+            runId,
+        })) {
+            yield yielded;
+        }
+    }
+    async *runAgentDirect(agentName, task, attachments, sessionState, runId) {
+        for await (const yielded of this.runAgentInternal(agentName, task, attachments, sessionState, runId)) {
+            if (yielded.type === `agent:${agentName}:output`) {
+                const content = yielded.data.content;
+                this.appendSessionMessage(sessionState, {
+                    role: "assistant",
+                    content,
+                });
+                yield {
+                    type: "assistant:text",
+                    data: { content },
+                    meta: { agent: agentName },
+                };
+                yield* this.triggerTopicRefresh(sessionState, runId);
+            }
+            else {
+                yield yielded;
+            }
+        }
+    }
+    async *routeApproval(event, state, runId) {
+        const approvalId = event.data.id;
+        const agentStates = state.agentStates || {};
+        let targetAgent;
+        for (const [name, agentState] of Object.entries(agentStates)) {
+            if (agentState.pendingApprovals?.[approvalId]) {
+                targetAgent = name;
+                break;
+            }
+        }
+        if (!targetAgent) {
+            console.warn("[openbot-runtime] No agent found for approval event:", approvalId);
+            return;
+        }
+        const agent = this.agents.get(targetAgent);
+        const agentState = this.getAgentState(targetAgent, state);
+        const runtime = this.buildAgentRuntime(agent);
+        let agentOutput = "";
+        let agentCompleted = false;
+        const isDelegation = !!state.pendingAgentTasks?.[targetAgent];
+        for await (const yielded of runtime.run(event, {
+            state: agentState,
+            runId,
+        })) {
+            if (yielded.type === `agent:${targetAgent}:output`) {
+                agentOutput = yielded.data.content;
+                agentCompleted = true;
+            }
+            if (isDelegation && isAgentTextEvent(yielded)) {
+                continue;
+            }
+            yield yielded;
+        }
+        if (agentCompleted && state.pendingAgentTasks?.[targetAgent]) {
+            const { toolCallId } = state.pendingAgentTasks[targetAgent];
+            delete state.pendingAgentTasks[targetAgent];
+            yield* this.runManagerLoop({
+                type: "manager:result",
+                data: {
+                    action: "delegateTask",
+                    toolCallId,
+                    result: agentOutput,
+                },
+            }, state, runId);
+        }
+        const waiting = hasPendingApprovals(state);
+        const trace = setExecutionState(state, {
+            state: waiting ? "WAITING_APPROVAL" : "COMPLETED",
+            currentStepId: waiting ? state.execution?.currentStepId : undefined,
+            error: undefined,
+        });
+        yield executionStateEvent(trace);
+    }
+}