agentopology 0.1.0 → 0.2.0

package/dist/bindings/openclaw.js

@@ -55,7 +55,15 @@ function gitkeep(dirPath) {
 }
 /**
  * Map topology model strings to OpenClaw model identifiers.
- * OpenClaw uses `provider/model-id` format with hyphens.
+ *
+ * OpenClaw resolves the provider from the FIRST segment of the model ID
+ * (everything before the first "/"). For proxy providers like OpenRouter,
+ * the model ID must include both the proxy provider AND the upstream
+ * model path: `openrouter/google/gemini-2.5-flash`.
+ *
+ * When the .at file specifies a model like `google/gemini-2.5-flash`
+ * under an `openrouter` provider, the binding prepends the provider
+ * name to produce the correct 3-segment ID.
  */
 function mapModel(model, defaultProvider) {
     const provider = defaultProvider ?? "anthropic";
@@ -64,10 +72,19 @@ function mapModel(model, defaultProvider) {
         sonnet: `${provider}/claude-sonnet-4-6`,
         haiku: `${provider}/claude-haiku-4-5`,
     };
-    // If model already has provider prefix, return as-is
-    if (model.includes("/"))
+    // Alias lookup (short names like "opus", "sonnet", "haiku")
+    if (MODEL_MAP[model])
+        return MODEL_MAP[model];
+    // If model already starts with the provider prefix, return as-is
+    if (model.startsWith(`${provider}/`))
         return model;
-    return MODEL_MAP[model] ?? `${provider}/${model}`;
+    // If model has a slash (e.g. "google/gemini-2.5-flash") but doesn't
+    // start with the provider, prepend the provider so OpenClaw routes
+    // through the correct provider (e.g. "openrouter/google/gemini-2.5-flash")
+    if (model.includes("/"))
+        return `${provider}/${model}`;
+    // Bare model name — prepend provider
+    return `${provider}/${model}`;
 }
 /**
  * Map topology permission strings to OpenClaw permission labels.
@@ -205,7 +222,7 @@ function generateOpenClawJson(ast) {
             name: toTitle(ast.topology.name) + " Coordinator",
             model: orchModel,
             workspace: `~/.openclaw/workspace-${ast.topology.name}`,
-            agentDir: `./config/agents/orchestrator/agent`,
+            agentDir: `~/.openclaw/config/agents/orchestrator/agent`,
             subagents: {
                 allowAgents: agentIds,
             },
@@ -225,7 +242,7 @@ function generateOpenClawJson(ast) {
             name: toTitle(agent.id),
             model: agentModel,
             workspace: `~/.openclaw/workspace-${agent.id}`,
-            agentDir: `./config/agents/${agent.id}/agent`,
+            agentDir: `~/.openclaw/config/agents/${agent.id}/agent`,
         };
         // No per-agent tools in openclaw.json — tool restrictions go in AGENTS.md
         // Sampling params
@@ -233,9 +250,32 @@ function generateOpenClawJson(ast) {
             entry.temperature = agent.temperature;
         if (agent.maxTokens != null)
             entry.maxTokens = agent.maxTokens;
-        // Timeout
-        if (agent.timeout)
-            entry.timeout = agent.timeout;
+        // Note: OpenClaw does NOT support per-agent "timeout" in openclaw.json.
+        // Timeouts are documented in AGENTS.md instead.
+        // subagents.allowAgents — OpenClaw requires explicit delegation lists
+        // for agents to use sessions_spawn. We detect supervisors using:
+        // 1. The topology's interface entry point (if defined)
+        // 2. The first agent by phase order
+        // 3. Any agent that is the target of error edges (error handlers coordinate)
+        // Supervisors get allowAgents for ALL other agents in the topology,
+        // because OpenClaw delegation is about permission, not flow direction.
+        const isSupervisor = 
+        // Interface entry point
+        (ast.interfaceEndpoints?.entry === agent.id) ||
+            // First agent by phase (lowest phase = coordinator)
+            (agents.length > 0 && agents[0].id === agent.id) ||
+            // Error handler target (receives error edges from other agents)
+            ast.edges.some((e) => e.isError && e.to === agent.id) ||
+            // Topology declares "supervisor" pattern and this is the first agent
+            (ast.topology.patterns.includes("supervisor") && agents[0]?.id === agent.id);
+        if (isSupervisor) {
+            const otherAgentIds = agents
+                .filter((a) => a.id !== agent.id)
+                .map((a) => a.id);
+            if (otherAgentIds.length > 0) {
+                entry.subagents = { allowAgents: otherAgentIds };
+            }
+        }
         // Merge agent-level openclaw extensions
         if (agent.extensions?.openclaw) {
             for (const [k, v] of Object.entries(agent.extensions.openclaw)) {
@@ -704,6 +744,56 @@ function generateAgentsMd(ast) {
             if (agent.writes && agent.writes.length > 0) {
                 sections.push(`- **Writes:** ${agent.writes.join(", ")}`);
             }
+            // Memory stores — rich details per store
+            if (agent.memory && agent.memory.length > 0) {
+                const storeMap = new Map((ast.stores ?? []).map(s => [s.id, s]));
+                sections.push("- **Memory stores:**");
+                for (const storeId of agent.memory) {
+                    const store = storeMap.get(storeId);
+                    if (!store) {
+                        sections.push(`  - ${storeId}`);
+                        continue;
+                    }
+                    const parts = [`**${storeId}**`, `type: ${store.type}`, `backend: ${store.backend}`];
+                    if (store.path)
+                        parts.push(`path: \`${store.path}\``);
+                    if (store.scope)
+                        parts.push(`scope: ${store.scope}`);
+                    if (store.embedding?.model)
+                        parts.push(`embedding: ${store.embedding.model} (${store.embedding.dimensions}d)`);
+                    if (store.search?.strategy)
+                        parts.push(`search: ${store.search.strategy}`);
+                    sections.push(`  - ${parts.join(" — ")}`);
+                }
+            }
+            // Retrieval strategy — rich details
+            if (agent.retrieval) {
+                const retrieval = (ast.retrievals ?? []).find(r => r.id === agent.retrieval);
+                if (retrieval) {
+                    const parts = [`**${retrieval.id}**`];
+                    if (retrieval.sources)
+                        parts.push(`sources: ${retrieval.sources.join(", ")}`);
+                    if (retrieval.budget)
+                        parts.push(`budget: ${retrieval.budget} tokens`);
+                    if (retrieval.rerank)
+                        parts.push(`reranked`);
+                    if (retrieval.scoring) {
+                        const weights = [];
+                        if (retrieval.scoring.semanticWeight != null)
+                            weights.push(`semantic: ${retrieval.scoring.semanticWeight}`);
+                        if (retrieval.scoring.recencyWeight != null)
+                            weights.push(`recency: ${retrieval.scoring.recencyWeight}`);
+                        if (retrieval.scoring.importanceWeight != null)
+                            weights.push(`importance: ${retrieval.scoring.importanceWeight}`);
+                        if (weights.length)
+                            parts.push(`scoring: ${weights.join(", ")}`);
+                    }
+                    sections.push(`- **Retrieval strategy:** ${parts.join(" — ")}`);
+                }
+                else {
+                    sections.push(`- **Retrieval strategy:** ${agent.retrieval}`);
+                }
+            }
             // Outputs
             if (agent.outputs) {
                 sections.push("- **Outputs:**");
@@ -1201,6 +1291,127 @@ function generateMemoryMd(ast) {
             sections.push(`Mode: ${metrics.mode}`);
         sections.push("");
     }
+    // Memory Stores — full details
+    const stores = ast.stores ?? [];
+    if (stores.length > 0) {
+        sections.push("## Memory Stores");
+        sections.push("");
+        for (const store of stores) {
+            sections.push(`### ${store.id}`);
+            if (store.description)
+                sections.push(store.description);
+            sections.push("");
+            sections.push(`- **Type**: ${store.type}`);
+            sections.push(`- **Backend**: ${store.backend}`);
+            if (store.path)
+                sections.push(`- **Path**: \`${store.path}\``);
+            if (store.connection)
+                sections.push(`- **Connection**: ${store.connection}`);
+            if (store.scope)
+                sections.push(`- **Scope**: ${store.scope}`);
+            if (store.isolation)
+                sections.push(`- **Isolation**: ${store.isolation}`);
+            if (store.extraction)
+                sections.push(`- **Extraction**: ${store.extraction}`);
+            // Embedding
+            if (store.embedding) {
+                const emb = store.embedding;
+                sections.push(`- **Embedding**: ${emb.model} (${emb.provider}, ${emb.dimensions}d)`);
+            }
+            // Index
+            if (store.index) {
+                const parts = [];
+                if (store.index.collection)
+                    parts.push(`collection: ${store.index.collection}`);
+                if (store.index.metric)
+                    parts.push(`metric: ${store.index.metric}`);
+                if (parts.length)
+                    sections.push(`- **Index**: ${parts.join(", ")}`);
+            }
+            // Search
+            if (store.search) {
+                const parts = [`strategy: ${store.search.strategy}`];
+                if (store.search.topK)
+                    parts.push(`top-k: ${store.search.topK}`);
+                if (store.search.rerank)
+                    parts.push(`rerank: yes`);
+                sections.push(`- **Search**: ${parts.join(", ")}`);
+            }
+            // Ingestion
+            if (store.ingestion) {
+                const parts = [];
+                if (store.ingestion.sources)
+                    parts.push(`sources: ${store.ingestion.sources.join(", ")}`);
+                if (store.ingestion.chunking)
+                    parts.push(`chunking: ${store.ingestion.chunking}`);
+                if (store.ingestion.chunkSize)
+                    parts.push(`size: ${store.ingestion.chunkSize}`);
+                if (store.ingestion.overlap)
+                    parts.push(`overlap: ${store.ingestion.overlap}`);
+                if (parts.length)
+                    sections.push(`- **Ingestion**: ${parts.join(", ")}`);
+            }
+            // Lifecycle
+            if (store.lifecycle) {
+                const lc = store.lifecycle;
+                if (lc.retention)
+                    sections.push(`- **Retention**: ${lc.retention}`);
+                if (lc.decayHalfLife)
+                    sections.push(`- **Decay half-life**: ${lc.decayHalfLife}`);
+                if (lc.consolidation != null)
+                    sections.push(`- **Consolidation threshold**: ${lc.consolidation}`);
+                if (lc.contradiction)
+                    sections.push(`- **Contradiction handling**: ${lc.contradiction}`);
+                if (lc.auditLog != null)
+                    sections.push(`- **Audit log**: ${lc.auditLog}`);
+            }
+            // Which agents use this store
+            const storeAgents = agents.filter(a => a.memory?.includes(store.id));
+            if (storeAgents.length > 0) {
+                sections.push(`- **Used by**: ${storeAgents.map(a => a.id).join(", ")}`);
+            }
+            sections.push("");
+        }
+    }
+    // Retrieval Strategies
+    const retrievals = ast.retrievals ?? [];
+    if (retrievals.length > 0) {
+        sections.push("## Retrieval Strategies");
+        sections.push("");
+        for (const ret of retrievals) {
+            sections.push(`### ${ret.id}`);
+            if (ret.sources)
+                sections.push(`- **Sources**: ${ret.sources.join(", ")}`);
+            if (ret.budget)
+                sections.push(`- **Token budget**: ${ret.budget}`);
+            if (ret.paths)
+                sections.push(`- **Search paths**: ${ret.paths.join(", ")}`);
+            if (ret.rerank)
+                sections.push(`- **Reranking**: enabled`);
+            if (ret.diversity)
+                sections.push(`- **Diversity**: enabled`);
+            if (ret.cacheHitThreshold != null) {
+                sections.push(`- **Cache hit**: threshold ${ret.cacheHitThreshold} → ${ret.cacheHitAction ?? "short-circuit"}`);
+            }
+            if (ret.scoring) {
+                const weights = [];
+                if (ret.scoring.recencyWeight != null)
+                    weights.push(`recency: ${ret.scoring.recencyWeight}`);
+                if (ret.scoring.semanticWeight != null)
+                    weights.push(`semantic: ${ret.scoring.semanticWeight}`);
+                if (ret.scoring.importanceWeight != null)
+                    weights.push(`importance: ${ret.scoring.importanceWeight}`);
+                if (weights.length)
+                    sections.push(`- **Scoring**: ${weights.join(", ")}`);
+            }
+            // Which agents use this retrieval
+            const retAgents = agents.filter(a => a.retrieval === ret.id);
+            if (retAgents.length > 0) {
+                sections.push(`- **Used by**: ${retAgents.map(a => a.id).join(", ")}`);
+            }
+            sections.push("");
+        }
+    }
     // Agent access rules
     const agentsWithAccess = agents.filter((a) => (a.reads && a.reads.length > 0) || (a.writes && a.writes.length > 0));
     if (agentsWithAccess.length > 0) {
@@ -1348,9 +1559,11 @@ function generateSkillFiles(ast) {
     const files = [];
     for (const skill of ast.skills) {
         const sections = [];
-        // OpenClaw requires YAML frontmatter with name and description
+        // OpenClaw requires YAML frontmatter with name, version, AND description.
+        // Missing any of the three = skill silently not registered.
         sections.push("---");
         sections.push(`name: ${skill.id}`);
+        sections.push(`version: "${ast.topology.version}"`);
         if (skill.description) {
             sections.push(`description: ${JSON.stringify(skill.description)}`);
         }
@@ -1398,10 +1611,11 @@ function generateSkillFiles(ast) {
 function generateToolSkills(ast) {
     const files = [];
     for (const tool of ast.toolDefs) {
-        // SKILL.md wrapper — OpenClaw requires YAML frontmatter
+        // SKILL.md wrapper — OpenClaw requires name, version, AND description.
         const sections = [];
         sections.push("---");
         sections.push(`name: ${tool.id}`);
+        sections.push(`version: "${ast.topology.version}"`);
         sections.push(`description: ${JSON.stringify(tool.description)}`);
         sections.push("---");
         sections.push("");
@@ -1498,6 +1712,11 @@ function generateMemoryDirs(ast) {
     }
     // Domains dir
     files.push(gitkeep("domains"));
+    // Store directory markers
+    const stores = ast.stores ?? [];
+    for (const store of stores) {
+        files.push(gitkeep(`stores/${store.id}`));
+    }
     return files;
 }
 /** Generate metering script + metrics file. */
@@ -1534,6 +1753,163 @@ function generateMetering(ast) {
     });
     return files;
 }
+/**
+ * Generate per-agent identity directories.
+ *
+ * OpenClaw reads agent identity from `config/agents/<id>/agent/`.
+ * Each agent gets its own IDENTITY.md, MEMORY.md (scoped to its stores),
+ * and SOUL.md with role-specific instructions.
+ */
+function generatePerAgentDirs(ast) {
+    const files = [];
+    const agents = getAgentsSorted(ast);
+    const orchestrator = getOrchestrator(ast);
+    const storeMap = new Map((ast.stores ?? []).map(s => [s.id, s]));
+    const defaultProvider = getDefaultProviderName(ast);
+    // Helper: build per-agent MEMORY.md with only stores this agent uses
+    function agentMemoryMd(agentId, storeIds, retrievalId) {
+        const lines = ["# Memory Stores", ""];
+        lines.push("You have access to the following memory stores. Use them to persist and retrieve knowledge.");
+        lines.push("");
+        for (const sid of storeIds) {
+            const store = storeMap.get(sid);
+            if (!store)
+                continue;
+            lines.push(`## ${store.id}`);
+            if (store.description)
+                lines.push(store.description);
+            lines.push("");
+            lines.push(`- **Type**: ${store.type}`);
+            lines.push(`- **Backend**: ${store.backend}`);
+            if (store.path)
+                lines.push(`- **Path**: \`${store.path}\``);
+            if (store.scope)
+                lines.push(`- **Scope**: ${store.scope}`);
+            if (store.embedding) {
+                lines.push(`- **Embedding**: ${store.embedding.model} (${store.embedding.provider}, ${store.embedding.dimensions}d)`);
+            }
+            if (store.search) {
+                const parts = [`strategy: ${store.search.strategy}`];
+                if (store.search.topK)
+                    parts.push(`top-k: ${store.search.topK}`);
+                if (store.search.rerank)
+                    parts.push(`rerank: yes`);
+                lines.push(`- **Search**: ${parts.join(", ")}`);
+            }
+            if (store.ingestion?.sources) {
+                lines.push(`- **Ingestion sources**: ${store.ingestion.sources.join(", ")}`);
+            }
+            if (store.lifecycle?.retention)
+                lines.push(`- **Retention**: ${store.lifecycle.retention}`);
+            lines.push("");
+        }
+        // Retrieval strategy
+        if (retrievalId) {
+            const retrieval = (ast.retrievals ?? []).find(r => r.id === retrievalId);
+            if (retrieval) {
+                lines.push("## Retrieval Strategy");
+                lines.push("");
+                lines.push(`**${retrieval.id}** — When you need to recall information:`);
+                lines.push("");
+                if (retrieval.sources)
+                    lines.push(`- **Sources**: ${retrieval.sources.join(", ")}`);
+                if (retrieval.budget)
+                    lines.push(`- **Token budget**: ${retrieval.budget}`);
+                if (retrieval.paths)
+                    lines.push(`- **Search paths**: ${retrieval.paths.join(", ")}`);
+                if (retrieval.rerank)
+                    lines.push(`- **Reranking**: enabled`);
+                if (retrieval.scoring) {
+                    const w = [];
+                    if (retrieval.scoring.semanticWeight != null)
+                        w.push(`semantic: ${retrieval.scoring.semanticWeight}`);
+                    if (retrieval.scoring.recencyWeight != null)
+                        w.push(`recency: ${retrieval.scoring.recencyWeight}`);
+                    if (retrieval.scoring.importanceWeight != null)
+                        w.push(`importance: ${retrieval.scoring.importanceWeight}`);
+                    if (w.length)
+                        lines.push(`- **Scoring**: ${w.join(", ")}`);
+                }
+                lines.push("");
+            }
+        }
+        return lines.join("\n");
+    }
+    // Generate per-agent dirs
+    const allAgents = orchestrator
+        ? [{ id: "orchestrator", description: `${toTitle(ast.topology.name)} orchestrator`, model: orchestrator.model, memory: undefined, retrieval: undefined, prompt: undefined }]
+        : [];
+    for (const a of agents) {
+        allAgents.push({ id: a.id, description: a.description ?? "", model: a.model ?? "sonnet", memory: a.memory, retrieval: a.retrieval, prompt: a.prompt });
+    }
+    for (const agent of allAgents) {
+        const base = `config/agents/${agent.id}/agent`;
+        // IDENTITY.md
+        files.push({
+            path: `${base}/IDENTITY.md`,
+            content: [
+                `# ${toTitle(agent.id)}`,
+                "",
+                agent.description || `Agent in the ${ast.topology.name} topology.`,
+                "",
+                `Model: ${mapModel(agent.model, defaultProvider)}`,
+                "",
+            ].join("\n"),
+            category: "machine",
+        });
+        // MEMORY.md — scoped to this agent's stores
+        if (agent.memory && agent.memory.length > 0) {
+            files.push({
+                path: `${base}/MEMORY.md`,
+                content: agentMemoryMd(agent.id, agent.memory, agent.retrieval) + "\n",
+                category: "machine",
+            });
+        }
+        // SOUL.md — agent-specific instructions
+        const soulLines = [
+            `# ${toTitle(agent.id)} — Soul`,
+            "",
+            `You are the **${toTitle(agent.id)}** agent in the **${toTitle(ast.topology.name)}** topology.`,
+            "",
+        ];
+        if (agent.description) {
+            soulLines.push(`## Role`, "", agent.description, "");
+        }
+        if (agent.prompt) {
+            soulLines.push("## Instructions", "", agent.prompt, "");
+        }
+        if (agent.memory && agent.memory.length > 0) {
+            soulLines.push(`## Memory`, "", `You have access to these stores: ${agent.memory.join(", ")}. See MEMORY.md for details.`, "");
+        }
+        files.push({
+            path: `${base}/SOUL.md`,
+            content: soulLines.join("\n"),
+            category: "machine",
+        });
+    }
+    // OpenClaw injects ALL files from agentDir into the agent's system prompt.
+    // The team-level AGENTS.md, TOOLS.md, USER.md, and BOOTSTRAP.md must be
+    // copied into each agent's dir so the gateway can find them.
+    // We re-generate the content here (same functions used for root-level files)
+    // to avoid cross-function dependencies.
+    const sharedContent = {
+        "AGENTS.md": generateAgentsMd(ast).content,
+        "TOOLS.md": generateToolsMd(ast).content,
+        "USER.md": generateUserMd().content,
+        "BOOTSTRAP.md": generateBootstrapMd(ast).content,
+    };
+    for (const agent of allAgents) {
+        const base = `config/agents/${agent.id}/agent`;
+        for (const [filename, content] of Object.entries(sharedContent)) {
+            files.push({
+                path: `${base}/${filename}`,
+                content,
+                category: "machine",
+            });
+        }
+    }
+    return files;
+}
 // ---------------------------------------------------------------------------
 // Binding export
 // ---------------------------------------------------------------------------
@@ -1568,7 +1944,9 @@ export const openClawBinding = {
         // 5. Memory and skills directory markers
         files.push(gitkeep("memory"));
         files.push(gitkeep("skills"));
-        // 6. Workspace protocol
+        // 6. Per-agent identity directories (config/agents/<id>/agent/)
+        files.push(...generatePerAgentDirs(ast));
+        // 7. Workspace protocol
         const protocol = generateWorkspaceProtocol(ast);
         if (protocol)
             files.push(protocol);