agentopology 0.2.5 → 0.4.0

package/dist/parser/index.js

@@ -16,6 +16,78 @@ import { stripComments, extractBlock, extractAllBlocks, parseKV, parseList, pars
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
+/**
+ * V90: detect a field value that swallowed the next field.
+ *
+ * `parseFields` is line-based, and the grammar never says so. Writing two
+ * fields on one line — `agent a { model: sonnet retry: 3 }` — makes the first
+ * key take the whole rest of the line as its value (`"sonnet retry: 3"`), and
+ * nothing catches it. The value is then silently wrong: a model name that does
+ * not exist, a version string carrying a description, an action `kind` that
+ * fails its enum for a confusing reason.
+ *
+ * Detection: an UNQUOTED value containing whitespace followed by
+ * `identifier:` is almost certainly a swallowed field. Quoted values are
+ * exempt (a description may legitimately contain a colon), and a leading
+ * scheme like `https://` is not matched because it has no preceding
+ * whitespace.
+ */
+function detectSwallowedFields(fields, nodeId, out) {
+    for (const [key, raw] of Object.entries(fields)) {
+        if (typeof raw !== "string")
+            continue;
+        const value = raw.trim();
+        // Free-prose fields whose quotes have already been stripped are exempt: a
+        // colon inside a description is ordinary English ("Demo: agent pipeline"),
+        // and once the quotes are gone there is no way to tell prose from a
+        // swallow. Where quotes SURVIVE parsing — every block except `meta` — the
+        // check below still catches `description: "k" model: sonnet`.
+        const PROSE_FIELDS = new Set(["description", "role", "generates", "termination"]);
+        if (PROSE_FIELDS.has(key) && !value.startsWith('"'))
+            continue;
+        // A balanced brace block is a NESTED OBJECT, not a swallow. The single-line
+        // form is spec-legal and parses correctly — `spec/grammar.md:117` gives
+        // `outputs: { depth: 1 | 2 | 3 }` verbatim. Flagging it rejected valid
+        // topologies, which is worse than missing one.
+        if (value.startsWith("{") && value.endsWith("}"))
+            continue;
+        // Same for a list.
+        if (value.startsWith("[") && value.endsWith("]"))
+            continue;
+        // A WELL-FORMED quoted string is exempt — a description may contain a
+        // colon. `"1.0.0" description: "x"` is NOT well-formed: it is one quoted
+        // token followed by more content, i.e. a swallowed field.
+        if (/^"(?:[^"\\]|\\.)*"$/.test(value))
+            continue;
+        const search = value.startsWith('"')
+            ? value.replace(/^"(?:[^"\\]|\\.)*"/, "")
+            : value;
+        const m = /\s([a-zA-Z][a-zA-Z0-9_-]*):/.exec(search.startsWith(" ") ? search : " " + search);
+        if (!m)
+            continue;
+        out.push({
+            rule: "V90",
+            level: "error",
+            message: `"${nodeId}" field \`${key}\` has the value \`${value}\`, which looks like it swallowed the ` +
+                `field \`${m[1]}\` — fields must be one per line`,
+            node: nodeId,
+        });
+    }
+}
+/**
+ * Placeholders the parser injects for REQUIRED fields that were not declared.
+ *
+ * The parser cannot leave them undefined without changing non-optional AST
+ * types, so it substitutes a sentinel — and that sentinel then satisfied every
+ * "is it present?" check downstream. V91 recognises them and reports the field
+ * as missing, which is what the spec says it is.
+ */
+export const MISSING = {
+    /** `orchestrator.model` — spec/grammar.md, orchestrator field table. */
+    model: "unknown",
+    /** `meta.version` — spec/grammar.md:282, Required: yes. */
+    version: "0.0.0",
+};
 /** Convert a kebab-case or snake_case identifier to a Title Case label. */
 function toLabel(id) {
     return id
@@ -203,8 +275,11 @@ export function parseMeta(body) {
 /**
  * Parse the `orchestrator { ... }` block into an {@link OrchestratorNode}.
  */
-export function parseOrchestrator(body) {
+export function parseOrchestrator(body, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, "orchestrator", _blockFieldMisuseWarnings);
+    }
     const handles = parseMultilineList(body, "handles");
     const outputs = parseOutputsBlock(body);
     const node = {
@@ -247,8 +322,11 @@ export function parseRoles(body) {
 /**
  * Parse an `action <id> { ... }` block into an {@link ActionNode}.
  */
-export function parseAction(id, body) {
+export function parseAction(id, body, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, id, _blockFieldMisuseWarnings);
+    }
     const commands = parseMultilineList(body, "commands");
     const node = {
         id,
@@ -279,7 +357,7 @@ export function parseAction(id, body) {
  * @param roles - Role descriptions from the `roles` block, used to attach a
  *                role description to matching agents.
  */
-export function parseAgent(id, body, roles) {
+export function parseAgent(id, body, roles, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
     const tools = parseMultilineList(body, "tools");
     const skills = parseMultilineList(body, "skills");
@@ -298,7 +376,24 @@ export function parseAgent(id, body, roles) {
         node.model = fields.model;
     if (fields.permissions)
         node.permissions = fields.permissions;
-    // Extract prompt from prompt {} block (not KV pair)
+    // Extract prompt from prompt {} block (not KV pair).
+    //
+    // V89: `agent.prompt` is a BLOCK per spec/grammar.md:350. The string form
+    // (`prompt: "path.md"`) belongs to `skill`, a different node type
+    // (spec/grammar.md:1377). A KV `prompt` on an agent is silently unparseable,
+    // so flag it rather than dropping the author's instructions on the floor.
+    if (fields.prompt) {
+        _blockFieldMisuseWarnings?.push({
+            rule: "V89",
+            level: "error",
+            message: `agent "${id}" uses \`prompt:\` as a key-value field, but agent prompts must be a \`prompt { }\` block — ` +
+                `this value is ignored and the agent will have no instructions`,
+            node: id,
+        });
+    }
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, id, _blockFieldMisuseWarnings);
+    }
     const promptBlock = extractBlock(body, "prompt");
     if (promptBlock) {
         node.prompt = dedentBlock(promptBlock.body);
@@ -407,6 +502,24 @@ export function parseAgent(id, body, roles) {
     }
     if (fields.retrieval)
         node.retrieval = fields.retrieval;
+    // Custody: `custodian-of: [store, ...]` with optional `{ does: [verb, ...] }`.
+    // The store-list appears before an optional brace block. Match the list first,
+    // then look inside the block (if any) for `does`.
+    const custodyMatch = /custodian-of\s*:\s*\[([^\]]*)\]/.exec(body);
+    if (custodyMatch) {
+        const stores = parseList(custodyMatch[1]);
+        if (stores.length)
+            node.custodianOf = stores;
+        const custodyBlock = extractBlock(body, "custodian-of");
+        if (custodyBlock) {
+            const does = parseMultilineList(custodyBlock.body, "does");
+            const doesInline = parseFields(custodyBlock.body).does;
+            if (does.length)
+                node.custodianDoes = does;
+            else if (doesInline)
+                node.custodianDoes = parseList(doesInline);
+        }
+    }
     if (outputs)
         node.outputs = outputs;
     // Parse scale sub-block
@@ -537,8 +650,11 @@ export function parseAgent(id, body, roles) {
 /**
  * Parse a `gate <id> { ... }` block into a {@link GateNode}.
  */
-export function parseGate(id, body) {
+export function parseGate(id, body, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, id, _blockFieldMisuseWarnings);
+    }
     const checks = parseMultilineList(body, "checks");
     const node = {
         id,
@@ -569,8 +685,11 @@ export function parseGate(id, body) {
 /**
  * Parse a `human <id> { ... }` block into a {@link HumanNode}.
  */
-export function parseHuman(id, body) {
+export function parseHuman(id, body, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, id, _blockFieldMisuseWarnings);
+    }
     const node = {
         id,
         type: "human",
@@ -587,8 +706,11 @@ export function parseHuman(id, body) {
 /**
  * Parse a `group <id> { ... }` block into a {@link GroupNode}.
  */
-export function parseGroup(id, body) {
+export function parseGroup(id, body, _blockFieldMisuseWarnings) {
     const fields = parseFields(body);
+    if (_blockFieldMisuseWarnings) {
+        detectSwallowedFields(fields, id, _blockFieldMisuseWarnings);
+    }
     const members = parseList(fields.members ?? "");
     const node = {
         id,
@@ -633,6 +755,24 @@ export function parseFlow(body, _edgeAttributeErrors) {
         // Match annotation at end of line: [when ..., max N, per agent-id, tolerance: N, race, wait 30s, reflection]
         // Must start with "when", "max", "per", "tolerance", "race", "wait", "join", "weight", or "reflection" to avoid matching fan-out lists.
         const bracketMatch = trimmed.match(/\[(when\s+.+?|max\s+\d+.*?|per\s+\S+.*?|tolerance\s*:.+?|race.*?|wait\s+\S+.*?|join\s+\S+.*?|weight\s+\S+.*?|reflection.*?)\]\s*$/);
+        // V92: two bracket groups on one edge. The grammar defines ONE annotation
+        // with comma-separated attributes (`[when ..., max N]`). Written as
+        // `[when ...] [max N]`, the matcher below spans from the first `[` to the
+        // last `]` and produces a corrupt condition — literally
+        // `a.verdict == fail] [max 3` — with no error at all.
+        // Count only ANNOTATION brackets. A fan-out list is also bracketed —
+        // `analyzer -> [reporter, alerter] [when ...]` is legal — so testing for
+        // `] [` alone flagged valid topologies.
+        const ATTR = /\[\s*(?:when|max|per|tolerance|race|wait|join|weight|reflection)\b/g;
+        const annotationBrackets = (trimmed.match(ATTR) ?? []).length;
+        if (annotationBrackets > 1 && _edgeAttributeErrors) {
+            _edgeAttributeErrors.push({
+                rule: "V92",
+                level: "error",
+                message: "Edge has two bracket groups — attributes go in ONE bracket, " +
+                    `comma-separated: [when ..., max N] (line: ${trimmed})`,
+            });
+        }
         if (bracketMatch) {
             flowPart = trimmed.slice(0, bracketMatch.index).trim();
             const annotation = bracketMatch[1];
@@ -892,10 +1032,13 @@ function parseScoringConfig(body) {
  */
 export function parseStore(id, body) {
     const fields = parseFields(body);
+    // `brain` stores are file-native (Obsidian-format markdown) — their backend
+    // is always `files`, never a database. Every other type defaults to lancedb.
+    const type = fields.type ?? "semantic";
     const store = {
         id,
-        type: fields.type ?? "semantic",
-        backend: fields.backend ?? "lancedb",
+        type,
+        backend: fields.backend ?? (type === "brain" ? "files" : "lancedb"),
     };
     if (fields.description)
         store.description = unquote(fields.description);
@@ -907,6 +1050,8 @@ export function parseStore(id, body) {
         store.path = unquote(fields.path);
     if (fields.extraction)
         store.extraction = fields.extraction;
+    if (fields.format)
+        store.format = fields.format;
     // Connection: may use `secret "uri"` modifier (same pattern as parseCheckpoint)
     if (fields.connection) {
         const rawConn = fields.connection.trim();
@@ -933,6 +1078,39 @@ export function parseStore(id, body) {
     const lifecycleBlock = extractBlock(body, "lifecycle");
     if (lifecycleBlock)
         store.lifecycle = parseLifecycleConfig(lifecycleBlock.body);
+    // Presentation-only `sources { gmail { color icon } slack { ... } }` block.
+    // Maps a note's `source:` frontmatter to a graph color/icon. Cosmetic — the
+    // visualizer reads it; bindings ignore it entirely.
+    const sourcesBlock = extractBlock(body, "sources");
+    if (sourcesBlock) {
+        const sources = {};
+        const re = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
+        let sm;
+        while ((sm = re.exec(sourcesBlock.body)) !== null) {
+            const name = sm[1];
+            const startIdx = sm.index + sm[0].length;
+            let depth = 1, i = startIdx;
+            while (i < sourcesBlock.body.length && depth > 0) {
+                if (sourcesBlock.body[i] === "{")
+                    depth++;
+                else if (sourcesBlock.body[i] === "}")
+                    depth--;
+                i++;
+            }
+            if (depth === 0) {
+                const inner = parseFields(sourcesBlock.body.slice(startIdx, i - 1));
+                const style = {};
+                if (inner.color)
+                    style.color = unquote(inner.color);
+                if (inner.icon)
+                    style.icon = unquote(inner.icon);
+                if (style.color || style.icon)
+                    sources[name] = style;
+            }
+        }
+        if (Object.keys(sources).length > 0)
+            store.sources = sources;
+    }
     // Backend-config passthrough bag
     const backendConfigBlock = extractBlock(body, "backend-config");
     if (backendConfigBlock) {
@@ -1006,10 +1184,7 @@ export function parseMemory(body, _unknownSubBlockWarnings) {
     ];
     const knownSubsSet = new Set([
         ...knownSubs,
-        "store", "retrieval",
-        // Sub-blocks within store {} and retrieval {} (not top-level memory subs,
-        // but the V24 scanner sees them because it doesn't track depth)
-        "embedding", "index", "ingestion", "search", "lifecycle", "backend-config", "scoring",
+        "store", "retrieval", // the two typed top-level blocks
     ]);
     for (const name of knownSubs) {
         const block = extractBlock(body, name);
@@ -1042,19 +1217,47 @@ export function parseMemory(body, _unknownSubBlockWarnings) {
             continue;
         retrievals.push(parseRetrieval(block.id, block.body));
     }
-    // Detect unknown sub-blocks
+    // Detect unknown sub-blocks. Only consider TOP-LEVEL blocks of the memory
+    // body — names nested inside a `store {}` or `retrieval {}` (e.g. a brain
+    // store's `sources { gmail {} }`) are that block's own concern, not memory
+    // sub-blocks. Walk the body tracking brace depth so we only flag depth-0 names.
     if (_unknownSubBlockWarnings) {
-        const subBlockRe = /(?:^|\n)\s*([a-zA-Z][a-zA-Z0-9_-]*)\s*\{/gm;
-        let m;
-        while ((m = subBlockRe.exec(body)) !== null) {
-            const name = m[1];
-            if (!knownSubsSet.has(name)) {
-                _unknownSubBlockWarnings.push({
-                    rule: "V24",
-                    level: "warning",
-                    message: `Unknown sub-block "${name}" in memory block — known sub-blocks are: ${knownSubs.join(", ")}`,
-                });
+        let depth = 0;
+        let i = 0;
+        while (i < body.length) {
+            const ch = body[i];
+            if (ch === "}") {
+                depth = Math.max(0, depth - 1);
+                i++;
+                continue;
+            }
+            if (ch === "{") {
+                depth++;
+                i++;
+                continue;
             }
+            // At top level, match a block header before `{`. Handles both the bare
+            // form (`workspace {`) and the typed-block form (`store brain {`,
+            // `retrieval smart {`) — in the latter the FIRST token is the keyword.
+            if (depth === 0) {
+                const rest = body.slice(i);
+                const m = /^([a-zA-Z][a-zA-Z0-9_-]*)(?:\s+[a-zA-Z][a-zA-Z0-9_-]*)?\s*\{/.exec(rest);
+                if (m && (i === 0 || /\s/.test(body[i - 1]))) {
+                    const name = m[1]; // the leading keyword (store / retrieval / workspace / …)
+                    if (!knownSubsSet.has(name)) {
+                        _unknownSubBlockWarnings.push({
+                            rule: "V24",
+                            level: "warning",
+                            message: `Unknown sub-block "${name}" in memory block — known sub-blocks are: ${knownSubs.join(", ")}`,
+                        });
+                    }
+                    // Advance into the block (past the `{`) so its body is depth-counted.
+                    i += m[0].length;
+                    depth++;
+                    continue;
+                }
+            }
+            i++;
         }
     }
     return { memory, stores, retrievals };
@@ -1970,7 +2173,11 @@ export function parse(source) {
     const topBody = stripComments(topoBlock.body);
     // --- Meta ---
     const metaBlock = extractBlock(topBody, "meta");
+    // V89/V90: collected while parsing blocks — a field written in a form the
+    // grammar does not define. Attached to the AST below.
+    const blockFieldMisuseWarnings = [];
     const metaFields = metaBlock ? parseMeta(metaBlock.body) : {};
+    detectSwallowedFields(metaFields, "<meta>", blockFieldMisuseWarnings);
     const topology = {
         name: header.name,
         version: metaFields.version ?? "0.0.0",
@@ -1991,20 +2198,20 @@ export function parse(source) {
     // Orchestrator
     const orchBlock = extractBlock(topBody, "orchestrator");
     if (orchBlock) {
-        nodes.push(parseOrchestrator(orchBlock.body));
+        nodes.push(parseOrchestrator(orchBlock.body, blockFieldMisuseWarnings));
     }
     // Actions
     const actionBlocks = extractAllBlocks(topBody, "action");
     for (const block of actionBlocks) {
         if (block.id) {
-            nodes.push(parseAction(block.id, block.body));
+            nodes.push(parseAction(block.id, block.body, blockFieldMisuseWarnings));
         }
     }
     // Agents
     const agentBlocks = extractAllBlocks(topBody, "agent");
     for (const block of agentBlocks) {
         if (block.id) {
-            nodes.push(parseAgent(block.id, block.body, roles));
+            nodes.push(parseAgent(block.id, block.body, roles, blockFieldMisuseWarnings));
         }
     }
     // Gates
@@ -2013,7 +2220,7 @@ export function parse(source) {
         const gateBlocks = extractAllBlocks(gatesBlock.body, "gate");
         for (const block of gateBlocks) {
             if (block.id) {
-                nodes.push(parseGate(block.id, block.body));
+                nodes.push(parseGate(block.id, block.body, blockFieldMisuseWarnings));
             }
         }
     }
@@ -2021,14 +2228,14 @@ export function parse(source) {
     const humanBlocks = extractAllBlocks(topBody, "human");
     for (const block of humanBlocks) {
         if (block.id) {
-            nodes.push(parseHuman(block.id, block.body));
+            nodes.push(parseHuman(block.id, block.body, blockFieldMisuseWarnings));
         }
     }
     // Group chat nodes
     const groupBlocks = extractAllBlocks(topBody, "group");
     for (const block of groupBlocks) {
         if (block.id) {
-            nodes.push(parseGroup(block.id, block.body));
+            nodes.push(parseGroup(block.id, block.body, blockFieldMisuseWarnings));
         }
     }
     // --- Skills ---
@@ -2209,6 +2416,10 @@ export function parse(source) {
     if (unknownMemorySubBlockWarnings.length > 0) {
         ast._unknownMemorySubBlockWarnings = unknownMemorySubBlockWarnings;
     }
+    // Attach V89 block-vs-KV field misuse errors for the validator to consume.
+    if (blockFieldMisuseWarnings.length > 0) {
+        ast._blockFieldMisuseWarnings = blockFieldMisuseWarnings;
+    }
     // Attach source map for line number tracking in validation results.
     if (Object.keys(sourceMap).length > 0) {
         ast._sourceMap = sourceMap;