agentopology 0.5.1 → 0.6.0

package/dist/parser/run.d.ts

@@ -0,0 +1,24 @@
+/**
+ * What a `run:` value is allowed to be: a command, not a sentence.
+ *
+ * A gate or hook `run` names something to execute. Bindings derive a script
+ * file name from it, so prose there became files named `E;`, `fail:` and
+ * `outputs.py)` — and a " / " in a sentence produced an empty name that
+ * crashed scaffold with EISDIR. Both the validator (V96) and every binding go
+ * through these two functions so they cannot disagree.
+ *
+ * @module
+ */
+/**
+ * The script file name a binding writes for `run`, or null when `run` does not
+ * name one. Keeps the historical derivation (basename of the last path, first
+ * word) so every valid topology compiles exactly as before.
+ */
+export declare function scriptNameFromRun(run: string | undefined): string | null;
+/**
+ * Why `run` reads as prose rather than a command, or null when it looks like a
+ * command. Deliberately conservative: it flags only what a shell would reject
+ * or what no command contains, so real commands are never refused.
+ */
+export declare function proseInRun(run: string): string | null;
+//# sourceMappingURL=run.d.ts.map

package/dist/parser/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/parser/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAIxE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAgBrD"}

package/dist/parser/run.js

@@ -0,0 +1,55 @@
+/**
+ * What a `run:` value is allowed to be: a command, not a sentence.
+ *
+ * A gate or hook `run` names something to execute. Bindings derive a script
+ * file name from it, so prose there became files named `E;`, `fail:` and
+ * `outputs.py)` — and a " / " in a sentence produced an empty name that
+ * crashed scaffold with EISDIR. Both the validator (V96) and every binding go
+ * through these two functions so they cannot disagree.
+ *
+ * @module
+ */
+/** One path-ish token: optional ./ ../ ~/ or / prefix, then safe characters (dotfolders such as .claude/ included). */
+const EXECUTABLE = /^(?:\.{1,2}\/|~\/|\/)?[A-Za-z0-9_.][A-Za-z0-9_.\/@+-]*$/;
+/** A file name a binding may write under its scripts/ directory. */
+const SCRIPT_FILE = /^[A-Za-z0-9_][A-Za-z0-9_.-]*$/;
+/**
+ * The script file name a binding writes for `run`, or null when `run` does not
+ * name one. Keeps the historical derivation (basename of the last path, first
+ * word) so every valid topology compiles exactly as before.
+ */
+export function scriptNameFromRun(run) {
+    if (!run)
+        return null;
+    const name = run.trim().replace(/^.*\//, "").replace(/\s.*$/, "");
+    return SCRIPT_FILE.test(name) ? name : null;
+}
+/**
+ * Why `run` reads as prose rather than a command, or null when it looks like a
+ * command. Deliberately conservative: it flags only what a shell would reject
+ * or what no command contains, so real commands are never refused.
+ */
+export function proseInRun(run) {
+    const text = run.trim();
+    if (text === "")
+        return "it is empty";
+    if (/\r|\n/.test(text))
+        return "it spans several lines";
+    const first = text.split(/\s+/)[0];
+    if (/[:;,]$/.test(first))
+        return `its first word "${first}" ends in punctuation`;
+    if (!EXECUTABLE.test(first))
+        return `its first word "${first}" is not a command or path`;
+    // Judge only what the shell would see unquoted.
+    const bare = text.replace(/'[^']*'|"[^"]*"/g, "''");
+    if (/[^\x00-\x7F]/.test(bare))
+        return "it contains non-ASCII text outside quotes";
+    if (/\s->\s|\s=>\s|\s<=\s|\s>=\s/.test(bare))
+        return "it contains an arrow or comparison (->, >=, <=)";
+    if (/(^|[^$])\(/.test(bare))
+        return "it contains an unquoted parenthesis";
+    if (scriptNameFromRun(text) === null)
+        return "no script file name can be derived from it";
+    return null;
+}
+//# sourceMappingURL=run.js.map

package/dist/parser/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/parser/run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,uHAAuH;AACvH,MAAM,UAAU,GAAG,yDAAyD,CAAC;AAE7E,oEAAoE;AACpE,MAAM,WAAW,GAAG,+BAA+B,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAuB;IACvD,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IACtB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAClE,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IACxB,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,aAAa,CAAC;IACtC,IAAI,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,wBAAwB,CAAC;IAExD,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,mBAAmB,KAAK,uBAAuB,CAAC;IACjF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,mBAAmB,KAAK,4BAA4B,CAAC;IAEzF,gDAAgD;IAChD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;IACpD,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,2CAA2C,CAAC;IAClF,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,iDAAiD,CAAC;IACvG,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,qCAAqC,CAAC;IAC1E,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,4CAA4C,CAAC;IAC1F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/parser/validator.d.ts

@@ -44,5 +44,17 @@ export declare function findBackEdges(edges: EdgeDef[], nodeIds: Set<string>): E
  * @param ast - The parsed topology AST.
  * @returns An array of validation results. An empty array means no issues found.
  */
+/**
+ * Engine events a `type: mod` hook may subscribe to (Claude Code function
+ * hooks, early access, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1).
+ *
+ * PROVEN: a Mod was loaded and fired on these (Claude Code 2.1.283).
+ * SEEN: the name is in the 2.1.283 binary but no Mod has been observed on it,
+ * so V95 accepts it with a warning rather than an error.
+ */
+export declare const MOD_EVENTS_PROVEN: readonly ["tool.call", "prompt.submit"];
+export declare const MOD_EVENTS_SEEN: readonly ["prompt.context", "session.start", "session.end", "model.complete", "message.received"];
+/** Hook types the grammar defines (`spec/grammar.md` §4.16). */
+export declare const HOOK_TYPES: readonly ["command", "prompt", "mod"];
 export declare function validate(ast: TopologyAST): ValidationResult[];
 //# sourceMappingURL=validator.d.ts.map

package/dist/parser/validator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/parser/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,OAAO,KAAK,EACV,WAAW,EAKX,OAAO,EAkBR,MAAM,UAAU,CAAC;AAMlB,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAyD/E;AAo0FD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAgG7D"}
+{"version":3,"file":"validator.d.ts","sourceRoot":"","sources":["../../src/parser/validator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,OAAO,KAAK,EAEV,WAAW,EAKX,OAAO,EAkBR,MAAM,UAAU,CAAC;AAMlB,mCAAmC;AACnC,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,KAAK,EAAE,OAAO,GAAG,SAAS,CAAC;IAC3B,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyMD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,EAAE,CAyD/E;AA44FD;;;;;GAKG;AACH;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,yCAA0C,CAAC;AACzE,eAAO,MAAM,eAAe,mGAElB,CAAC;AAEX,gEAAgE;AAChE,eAAO,MAAM,UAAU,uCAAwC,CAAC;AAyHhE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,gBAAgB,EAAE,CAoG7D"}

package/dist/parser/validator.js

@@ -20,6 +20,8 @@
  */
 import { MISSING } from "./index.js";
 import { gateAnchors } from "./ast.js";
+import { proseInRun } from "./run.js";
+import { unsafePathReason } from "./paths.js";
 // ---------------------------------------------------------------------------
 // Reserved keywords (from spec section 7)
 // ---------------------------------------------------------------------------
@@ -489,7 +491,7 @@ function v10PromptsExist(ast) {
     }
     return results;
 }
-/** V11: If agent A writes X and agent B reads X, a path A -> B must exist in flow. */
+/** V11: If agent A writes X and agent B reads X, a path A -> B must exist in flow (unless either runs on demand). */
 function v11ReadWriteConsistency(ast) {
     const results = [];
     // Build a reachability map using BFS from each node
@@ -554,7 +556,16 @@ function v11ReadWriteConsistency(ast) {
             const keyWriters = writers.get(key);
             if (!keyWriters)
                 continue; // no writer = could be external, skip
-            const hasPath = keyWriters.some((writerId) => isReachable(writerId, node.id) ||
+            // An on-demand agent (invocation: manual) sits outside the flow by
+            // definition (V4), so no flow path can exist to or from it — the order
+            // is the user's. Demanding one made every hand-built project, whose
+            // subagents are all on demand, fail on import.
+            const manual = (id) => {
+                const n = ast.nodes.find((x) => x.id === id);
+                return !!n && isAgent(n) && n.invocation === "manual";
+            };
+            const hasPath = manual(node.id) || keyWriters.some((writerId) => manual(writerId) ||
+                isReachable(writerId, node.id) ||
                 (coGroupMembers.get(node.id)?.has(writerId) ?? false));
             if (!hasPath) {
                 results.push({
@@ -984,6 +995,73 @@ function v91RequiredFieldPlaceholder(ast) {
  * `handoff-overlap-empty` pre-flagged ambiguity; having it here makes it work
  * under `scaffold` too, and for anyone who never runs `plan`.
  */
+/**
+ * V96: a `run:` value is a command, not a sentence.
+ *
+ * Gates and hooks compile to scripts named after their `run`. Prose there
+ * passed validation, then scaffold wrote junk files named `E;` and `fail:`
+ * and crashed with EISDIR on a " / " — after it had already written other
+ * files. The explanation belongs in `description`; `run` keeps the command.
+ */
+function v96RunIsCommand(ast) {
+    const results = [];
+    const check = (owner, run, nodeId) => {
+        if (run === undefined)
+            return;
+        const why = proseInRun(run);
+        if (!why)
+            return;
+        results.push({
+            rule: "V96",
+            level: "error",
+            message: `${owner} "run" is not a command — ${why}. Keep only the command in ` +
+                `"run" (e.g. run: "scripts/check.sh") and move the explanation into "description"`,
+            ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}),
+        });
+    };
+    for (const node of ast.nodes) {
+        if (isGate(node))
+            check(`Gate "${node.id}"`, node.run, node.id);
+        if (node.type === "agent") {
+            for (const hook of node.hooks ?? []) {
+                check(`Hook "${hook.name}" on agent "${node.id}"`, hook.run, node.id);
+            }
+        }
+    }
+    for (const hook of ast.hooks ?? [])
+        check(`Hook "${hook.name}"`, hook.run);
+    return results;
+}
+/**
+ * V97: a `file:` is a safe project-relative path.
+ *
+ * `file:` marks a node's internals as hand-written at that path; scaffold
+ * never writes it. A path outside the project ('..', absolute) or with an
+ * unsafe name could not be honoured, so it is refused here, not at scaffold.
+ */
+function v97FileIsProjectPath(ast) {
+    const results = [];
+    const check = (owner, file, nodeId) => {
+        if (file === undefined)
+            return;
+        const why = unsafePathReason(file.replace(/^\.\//, ""));
+        if (!why)
+            return;
+        results.push({
+            rule: "V97",
+            level: "error",
+            message: `${owner} "file" is not a project-relative path — ${why}. Name the file from the project root, e.g. file: ".claude/agents/reviewer.md"`,
+            ...(nodeId ? { node: nodeId, line: lookupLine(ast, nodeId) } : {}),
+        });
+    };
+    for (const node of ast.nodes)
+        check(`Node "${node.id}"`, node.file, node.id);
+    for (const skill of ast.skills ?? [])
+        check(`Skill "${skill.id}"`, skill.file);
+    for (const trigger of ast.triggers ?? [])
+        check(`Command "${trigger.name}"`, trigger.file);
+    return results;
+}
 function v93EdgeHandoffDeclared(ast) {
     const results = [];
     const byId = new Map(ast.nodes.map((n) => [n.id, n]));
@@ -2939,6 +3017,140 @@ function v88CustodyRefsValid(ast) {
  * @param ast - The parsed topology AST.
  * @returns An array of validation results. An empty array means no issues found.
  */
+/**
+ * Engine events a `type: mod` hook may subscribe to (Claude Code function
+ * hooks, early access, CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1).
+ *
+ * PROVEN: a Mod was loaded and fired on these (Claude Code 2.1.283).
+ * SEEN: the name is in the 2.1.283 binary but no Mod has been observed on it,
+ * so V95 accepts it with a warning rather than an error.
+ */
+export const MOD_EVENTS_PROVEN = ["tool.call", "prompt.submit"];
+export const MOD_EVENTS_SEEN = [
+    "prompt.context", "session.start", "session.end", "model.complete", "message.received",
+];
+/** Hook types the grammar defines (`spec/grammar.md` §4.16). */
+export const HOOK_TYPES = ["command", "prompt", "mod"];
+/** Every hook in the topology — global first, then per-agent — with its owner. */
+function allHooks(ast) {
+    const out = ast.hooks.map((hook) => ({ hook, where: hook.name }));
+    for (const n of ast.nodes) {
+        if (n.type !== "agent" || !n.hooks)
+            continue;
+        for (const hook of n.hooks)
+            out.push({ hook, where: `${n.id}.${hook.name}`, agent: n.id });
+    }
+    return out;
+}
+/**
+ * V94: a hook's `type` must be one the grammar defines.
+ *
+ * `type: mod` passed silently before the grammar knew it, and the claude-code
+ * binding wrote it into settings.json as a bash command. A misspelt type
+ * (`type: comand`) did the same.
+ */
+function v94HookTypeKnown(ast) {
+    const results = [];
+    for (const { hook, where, agent } of allHooks(ast)) {
+        const type = hook.type ?? "command";
+        if (!HOOK_TYPES.includes(type)) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" has type "${type}" — a hook is one of: ${HOOK_TYPES.join(", ")}. ` +
+                    `Use "mod" for a TypeScript module that runs inside the engine.`,
+                node: where,
+            });
+            continue;
+        }
+        if (type === "mod" && agent) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" is a mod inside an agent — a Mod runs in the engine for the whole session; declare it in the topology's hooks block.`,
+                node: where,
+            });
+        }
+        if (hook.flag !== undefined && type !== "mod") {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" sets flag: but is type "${type}" — flag: is the env switch of a type: mod hook.`,
+                node: where,
+            });
+        }
+        else if (hook.flag !== undefined && !/^[A-Z_][A-Z0-9_]*$/.test(hook.flag)) {
+            results.push({
+                rule: "V94",
+                level: "error",
+                message: `Hook "${where}" has flag "${hook.flag}" — a flag is an env variable name (e.g. MY_MOD_ON).`,
+                node: where,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * V95: a hook's `on:` must be an event its type can subscribe to.
+ *
+ * A mod subscribes to a dotted engine event (`tool.call`); a command or prompt
+ * hook to a PascalCase lifecycle event (`PreToolUse`, spec §4.16: "any
+ * identifier in PascalCase"). Mixing them is a hook that never fires. A value
+ * with whitespace is left to V90 (a swallowed field), not reported twice.
+ */
+function v95HookEventKnown(ast) {
+    const results = [];
+    const proven = MOD_EVENTS_PROVEN;
+    const seen = MOD_EVENTS_SEEN;
+    for (const { hook, where } of allHooks(ast)) {
+        const type = hook.type ?? "command";
+        const on = hook.on.trim();
+        if (/\s/.test(on))
+            continue; // V90
+        if (!on) {
+            results.push({ rule: "V95", level: "error", message: `Hook "${where}" has no on: — name the event it fires on.`, node: where });
+            continue;
+        }
+        if (type === "mod") {
+            if (!hook.run) {
+                results.push({ rule: "V95", level: "error", message: `Mod "${where}" has no run: — name its module (e.g. run: "hooks/redact.ts").`, node: where });
+            }
+            if (proven.includes(on))
+                continue;
+            if (seen.includes(on)) {
+                results.push({
+                    rule: "V95",
+                    level: "warning",
+                    message: `Mod "${where}" subscribes to "${on}" — the engine names this event, but no Mod has been observed firing on it. Proven: ${proven.join(", ")}.`,
+                    node: where,
+                });
+                continue;
+            }
+            const hint = /^[A-Z]/.test(on)
+                ? ` "${on}" is a command-hook event; a mod subscribes to an engine event.`
+                : "";
+            results.push({
+                rule: "V95",
+                level: "error",
+                message: `Mod "${where}" subscribes to unknown engine event "${on}".${hint} Engine events: ${[...proven, ...seen].join(", ")}.`,
+                node: where,
+            });
+            continue;
+        }
+        if (!/^[A-Z][A-Za-z0-9]*$/.test(on)) {
+            const hint = proven.includes(on) || seen.includes(on)
+                ? ` "${on}" is an engine event — set type: mod to subscribe a module to it.`
+                : "";
+            results.push({
+                rule: "V95",
+                level: "error",
+                message: `Hook "${where}" (type ${type}) fires on "${on}" — a ${type} hook takes a PascalCase event (e.g. PreToolUse, AgentStop).${hint}`,
+                node: where,
+            });
+        }
+    }
+    return results;
+}
 export function validate(ast) {
     return [
         ...v1UniqueNames(ast),
@@ -2970,6 +3182,10 @@ export function validate(ast) {
         ...v91RequiredFieldPlaceholder(ast),
         ...v92EdgeTwoBrackets(ast),
         ...v93EdgeHandoffDeclared(ast),
+        ...v94HookTypeKnown(ast),
+        ...v95HookEventKnown(ast),
+        ...v96RunIsCommand(ast),
+        ...v97FileIsProjectPath(ast),
         ...v25BounceBackAdvisory(ast),
         ...v26ActionKindEnum(ast),
         ...v27AgentPermissionsEnum(ast),