@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/org/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agents/org/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAK3D,YAAY,EAAE,gBAAgB,EAAE,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,MAAM,aAAa;AACvB,qDAAqD;AACnD,eAAe;AACjB,gEAAgE;GAC9D,iBAAiB;AACnB,mDAAmD;GACjD,cAAc;AAChB,8DAA8D;GAC5D,oBAAoB;AACtB,wDAAwD;GACtD,aAAa;AACf,oEAAoE;GAClE,oBAAoB;AACtB,yDAAyD;GACvD,WAAW,CAAC;AAEhB;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,aAAa,CAAC;IACtB,0EAA0E;IAC1E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CACb,MAAM,EACN;QACE,UAAU,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,GAAG,CAAC,EAAE,MAAM,CAAC;QACb;;;sCAG8B;QAC9B,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC;KAC7B,CACF,CAAC;IACF,sEAAsE;IACtE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IACtC,yDAAyD;IACzD,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,wEAAwE;IACxE,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CACvC;AAED;;;;;;;;;GASG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAGxC,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAOnC;AAED,sEAAsE;AACtE,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,iCAAiC,GACjC,yBAAyB,GACzB,wBAAwB,GACxB,6BAA6B,GAC7B,iCAAiC,GACjC,+BAA+B,GAC/B,sBAAsB,CAAC;AAE3B;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,uDAAuD;AACvD,MAAM,MAAM,WAAW,GACnB,8BAA8B,GAC9B,+BAA+B,GAC/B,6BAA6B,GAC7B,8BAA8B,GAC9B,4BAA4B,GAC5B,uBAAuB,GACvB,qBAAqB,CAAC;AAE1B;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/agents/org/types.js

@@ -0,0 +1,43 @@
+/**
+ * Brigade virtual-office layer — type surface (Stage A).
+ *
+ * STAGE-A CONTRACT: Inert data only. Nothing in the existing runtime
+ * reads any of these types yet. The derivation helper exists, the
+ * config field exists, but every consumer falls back to legacy
+ * behaviour when `cfg.org` is absent. Stages B/C/D wire the
+ * consumers.
+ *
+ * The wider design doc lives in the user's plan brief; the locked
+ * contract is:
+ *
+ *   - `cfg.org` is OPTIONAL on `BrigadeConfig`. Absent → legacy mode.
+ *   - `cfg.agents.<id>.org` is OPTIONAL on `AgentConfig`. Absent on a
+ *     member means the member is auto-derived (single-agent install)
+ *     OR rejected (multi-agent install with `cfg.org` present).
+ *   - `deriveOrgGraph(cfg)` returns `OrgGraph | undefined`. Undefined
+ *     signals "legacy mode" to every consumer.
+ *
+ * No external agent-codebase identifiers are
+ * referenced from this file.
+ */
+/**
+ * Hard-violation error thrown by `agents/org/validate.ts` and
+ * `agents/org/derive-graph.ts` when the operator's org config breaks
+ * an invariant (cycle, dangling reportsTo, topOrder.reportsTo !== null,
+ * departmentHeads referencing non-member, etc.).
+ *
+ * The class is a plain `Error` subclass so existing try/catch chains
+ * downstream don't need to learn a new shape. The `code` field carries
+ * the machine-readable diagnostic for tests + CLI rendering.
+ */
+export class BrigadeOrgConfigError extends Error {
+    code;
+    detail;
+    constructor(code, message, detail) {
+        super(message);
+        this.name = "BrigadeOrgConfigError";
+        this.code = code;
+        this.detail = detail;
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/agents/org/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/agents/org/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAmFH;;;;;;;;;GASG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,CAA4B;IAChC,MAAM,CAA2B;IAE1C,YACE,IAA+B,EAC/B,OAAe,EACf,MAAgC;QAEhC,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/dist/agents/org/validate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Brigade virtual-office layer — config validation (Stage A).
+ *
+ * Hard violations throw `BrigadeOrgConfigError` with a stable code so
+ * the CLI / TUI can render an actionable message. Soft warnings live
+ * in `lints.ts`. The split mirrors the reference codebase's
+ * config-validator pattern.
+ *
+ * Checks performed at Stage A:
+ *
+ *   1. `cfg.org.topOrder` resolves to a real member (or to the
+ *      single-agent auto-derive fallback when no `cfg.agents.<id>.org`
+ *      block is present).
+ *   2. The top-of-org agent has `reportsTo === null`.
+ *   3. Every member's `reportsTo` resolves to a real member.
+ *   4. The `reportsTo` chain is acyclic.
+ *   5. `cfg.org.departmentHeads[<dept>]` is a real member AND a member
+ *      of the named department.
+ *   6. `cfg.org.a2a.mode` is one of `derived | explicit | open`.
+ *
+ * Soft check emitted as a lint (NOT thrown):
+ *
+ *   - Manager chain deeper than 5 (Rule: depth-5 warning).
+ *
+ * Stage-A consumers (tests + audit-log only) call this synchronously.
+ */
+import type { BrigadeConfig } from "../../config/io.js";
+export interface ValidationOutcome {
+    /** Manager chain longer than `MAX_DEPTH_WARN`. Surfaced as a lint
+     *  (NOT thrown). Stage-A audit-log records the count. */
+    depthOverFive: boolean;
+    /** Resolved topOrder id (after applying defaults). */
+    topOrder: string;
+}
+export declare function validateOrgConfig(cfg: BrigadeConfig): ValidationOutcome;
+//# sourceMappingURL=validate.d.ts.map

package/dist/agents/org/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../../src/agents/org/validate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAKxD,MAAM,WAAW,iBAAiB;IAChC;6DACyD;IACzD,aAAa,EAAE,OAAO,CAAC;IACvB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,GAAG,iBAAiB,CAgGvE"}

package/dist/agents/org/validate.js

@@ -0,0 +1,135 @@
+/**
+ * Brigade virtual-office layer — config validation (Stage A).
+ *
+ * Hard violations throw `BrigadeOrgConfigError` with a stable code so
+ * the CLI / TUI can render an actionable message. Soft warnings live
+ * in `lints.ts`. The split mirrors the reference codebase's
+ * config-validator pattern.
+ *
+ * Checks performed at Stage A:
+ *
+ *   1. `cfg.org.topOrder` resolves to a real member (or to the
+ *      single-agent auto-derive fallback when no `cfg.agents.<id>.org`
+ *      block is present).
+ *   2. The top-of-org agent has `reportsTo === null`.
+ *   3. Every member's `reportsTo` resolves to a real member.
+ *   4. The `reportsTo` chain is acyclic.
+ *   5. `cfg.org.departmentHeads[<dept>]` is a real member AND a member
+ *      of the named department.
+ *   6. `cfg.org.a2a.mode` is one of `derived | explicit | open`.
+ *
+ * Soft check emitted as a lint (NOT thrown):
+ *
+ *   - Manager chain deeper than 5 (Rule: depth-5 warning).
+ *
+ * Stage-A consumers (tests + audit-log only) call this synchronously.
+ */
+import { BrigadeOrgConfigError } from "./types.js";
+const MAX_DEPTH_WARN = 5;
+export function validateOrgConfig(cfg) {
+    if (!cfg.org) {
+        // Should never be called without cfg.org — bail-out is defensive.
+        return { depthOverFive: false, topOrder: "" };
+    }
+    const mode = cfg.org.a2a?.mode;
+    if (mode !== "derived" && mode !== "explicit" && mode !== "open") {
+        throw new BrigadeOrgConfigError("ORG_INVALID_A2A_MODE", `cfg.org.a2a.mode must be one of "derived" | "explicit" | "open" (got ${JSON.stringify(mode)})`, { received: mode });
+    }
+    const topOrder = resolveTopOrder(cfg);
+    const memberIds = collectMemberIds(cfg);
+    // If no members are declared but cfg.org is present, that's a
+    // single-agent auto-derive scenario — the derivation path produces
+    // a synthesized member without consulting cfg.agents. Skip the
+    // member-level checks in that case.
+    if (memberIds.size === 0) {
+        return { depthOverFive: false, topOrder };
+    }
+    if (!memberIds.has(topOrder)) {
+        throw new BrigadeOrgConfigError("ORG_TOPORDER_NOT_MEMBER", `cfg.org.topOrder=${JSON.stringify(topOrder)} does not match any agent in cfg.agents with an .org block`, { topOrder, knownMembers: [...memberIds].sort() });
+    }
+    // Check #2: top-of-org agent must have reportsTo === null.
+    const topMemberOrg = cfg.agents?.[topOrder]?.org;
+    if (topMemberOrg && topMemberOrg.reportsTo !== null) {
+        throw new BrigadeOrgConfigError("ORG_TOPORDER_REPORTSTO_NOT_NULL", `topOrder agent ${JSON.stringify(topOrder)} must have org.reportsTo === null (got ${JSON.stringify(topMemberOrg.reportsTo)})`, { topOrder, reportsTo: topMemberOrg.reportsTo });
+    }
+    // Check #3 + #4: reportsTo references + acyclic chain.
+    for (const id of memberIds) {
+        const m = cfg.agents?.[id]?.org;
+        if (!m)
+            continue;
+        const rt = m.reportsTo;
+        if (rt === null || rt === undefined)
+            continue;
+        if (!memberIds.has(rt)) {
+            throw new BrigadeOrgConfigError("ORG_REPORTS_TO_UNKNOWN", `agent ${JSON.stringify(id)} reportsTo ${JSON.stringify(rt)} which is not a member`, { id, reportsTo: rt, knownMembers: [...memberIds].sort() });
+        }
+    }
+    // Acyclic check: depth-first walk from each member; track visited
+    // on the current path. Any revisit is a cycle.
+    let depthOverFive = false;
+    for (const id of memberIds) {
+        const { cycle, offending, depth } = walkChain(cfg, id, memberIds);
+        if (cycle) {
+            throw new BrigadeOrgConfigError("ORG_CYCLE_DETECTED", `manager chain for agent ${JSON.stringify(id)} contains a cycle at ${JSON.stringify(offending)}`, { id, offending });
+        }
+        if (depth > MAX_DEPTH_WARN)
+            depthOverFive = true;
+    }
+    // Check #5: departmentHeads.
+    const heads = cfg.org.departmentHeads ?? {};
+    for (const [dept, headId] of Object.entries(heads)) {
+        if (!memberIds.has(headId)) {
+            throw new BrigadeOrgConfigError("ORG_DEPARTMENT_HEAD_UNKNOWN", `departmentHeads[${JSON.stringify(dept)}]=${JSON.stringify(headId)} is not a member`, { dept, headId });
+        }
+        const headMember = cfg.agents?.[headId]?.org;
+        if (headMember && headMember.department !== dept) {
+            throw new BrigadeOrgConfigError("ORG_DEPARTMENT_HEAD_NOT_IN_DEPT", `departmentHeads[${JSON.stringify(dept)}]=${JSON.stringify(headId)} but that agent's org.department is ${JSON.stringify(headMember.department)}`, { dept, headId, actual: headMember.department });
+        }
+    }
+    return { depthOverFive, topOrder };
+}
+function resolveTopOrder(cfg) {
+    const fromCfg = cfg.org?.topOrder?.trim();
+    if (fromCfg && fromCfg.length > 0)
+        return fromCfg;
+    const fromDefaults = cfg.defaults?.agentId?.trim();
+    if (fromDefaults && fromDefaults.length > 0)
+        return fromDefaults;
+    return "main";
+}
+function collectMemberIds(cfg) {
+    const out = new Set();
+    const agents = cfg.agents ?? {};
+    for (const [id, value] of Object.entries(agents)) {
+        if (id === "defaults")
+            continue;
+        if (!value || typeof value !== "object")
+            continue;
+        const orgMeta = value.org;
+        if (orgMeta && typeof orgMeta.department === "string")
+            out.add(id);
+    }
+    return out;
+}
+function walkChain(cfg, start, memberIds) {
+    let cur = start;
+    const seen = new Set();
+    let depth = 0;
+    while (cur) {
+        if (seen.has(cur))
+            return { cycle: true, offending: cur, depth };
+        seen.add(cur);
+        const orgMeta = cfg.agents?.[cur]?.org;
+        if (!orgMeta)
+            break;
+        const next = orgMeta.reportsTo;
+        if (next === null || next === undefined)
+            break;
+        if (!memberIds.has(next))
+            break;
+        cur = next;
+        depth += 1;
+    }
+    return { cycle: false, offending: null, depth };
+}
+//# sourceMappingURL=validate.js.map

package/dist/agents/org/validate.js.map

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

package/dist/agents/path-write-guard.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Path-write guard — refuses `write` / `edit` / `bash` tool calls whose
+ * target path falls inside one of Brigade's protected roots.
+ *
+ * Why this exists
+ * ---------------
+ * The model has free filesystem access through Pi's built-in `write`
+ * and `edit` tools — and through `bash` it can shell out to `cat > X`,
+ * `sed -i`, `node -e fs.writeFileSync(...)`, etc. Without a guard, when
+ * a turn says "create skill X for agent Y" the model often falls back to:
+ *
+ *   1. Hand-writing to `<install-dir>/skills/<name>/SKILL.md` — ends up
+ *      in the read-only bundled scan root, lost on reinstall.
+ *   2. Hand-editing `~/.brigade/brigade.json` to register a new agent —
+ *      bypasses atomic config rotation, workspace bootstrap, and
+ *      `.brigade-trash/` soft-delete.
+ *   3. Hand-writing `~/.brigade/agents/<id>/agent/profile-state.json` —
+ *      bypasses the auth-profile lifecycle.
+ *
+ * Each of these has a dedicated tool (`manage_skill`, `manage_agent`,
+ * onboarding flows). This guard refuses the raw path AND the shell
+ * equivalents, and points the model at the right tool.
+ *
+ * Scope
+ * -----
+ * Path-mutating tools only: `write` (param: `path`), `edit` (param:
+ * `file_path`), and `bash`/`exec`/`shell`/`sh` (param: `command`). The
+ * bash branch parses the command string for write-intent indicators
+ * near a protected path; read-only ops (cat / grep / head / tail / ls /
+ * stat / wc / json.tool with no redirect) pass through. Plain reads via
+ * `read` / `grep` / `ls` / `find` are never blocked.
+ *
+ * Defense in depth — the resolved absolute path is checked against the
+ * forbidden roots using `path.relative()` semantics, so a symlinked path
+ * or `..` traversal still hits the guard.
+ */
+import type { BrigadeBeforeToolCallHook } from "./tool-guard.js";
+interface ProtectedRoot {
+    /** Absolute, normalised path of the forbidden file OR directory. */
+    target: string;
+    /** Whether `target` is treated as a directory tree (true) or a single file (false). */
+    directory: boolean;
+    /** Short identifier for the violation message ("brigade-config", "install-skills", ...). */
+    id: string;
+    /** Concrete redirect telling the model the right tool/path to use instead. */
+    redirect: string;
+}
+declare function buildProtectedRoots(): ProtectedRoot[];
+export interface PathWriteGuardOptions {
+    /**
+     * Override the protected-roots list — test seam. Production callers
+     * leave this undefined and the guard reads the live runtime paths.
+     */
+    roots?: ProtectedRoot[];
+    /**
+     * The SESSION cwd Pi's tools resolve relative paths against (the
+     * per-turn agent workspace). Audit P0 (2026-06-11): the guard used to
+     * resolve candidates with bare `path.resolve(...)` — gateway
+     * process.cwd(), no tilde expansion — while Pi's write/edit expand `~`
+     * and resolve against the session cwd. `edit({path:
+     * "~/.brigade/brigade.json"})` or `edit({path: "../brigade.json"})`
+     * from the default workspace therefore hit the real config while the
+     * guard compared a different absolute path. Defaults to process.cwd()
+     * when omitted (test back-compat with absolute-path fixtures).
+     */
+    cwd?: string;
+}
+/**
+ * Build the path-write guard hook. Refuses `write` / `edit` calls whose
+ * target lives under a protected root unless a carve-out applies. Also
+ * refuses `bash` / `exec` / `shell` / `sh` calls whose `command`
+ * contains a write-intent indicator against a protected path.
+ *
+ * Wire AFTER the unknown-tool guard (so unknown tools fail first) and
+ * BEFORE the exec-gate + user policy hook (so policy hooks never see a
+ * forbidden write and the exec-gate's approval prompt never asks the
+ * operator to allow a structurally-forbidden mutation).
+ */
+export declare function makePathWriteGuard(opts?: PathWriteGuardOptions): BrigadeBeforeToolCallHook;
+export { buildProtectedRoots };
+export type { ProtectedRoot };
+//# sourceMappingURL=path-write-guard.d.ts.map

package/dist/agents/path-write-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"path-write-guard.d.ts","sourceRoot":"","sources":["../../src/agents/path-write-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAaH,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAEjE,UAAU,aAAa;IACtB,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,uFAAuF;IACvF,SAAS,EAAE,OAAO,CAAC;IACnB,4FAA4F;IAC5F,EAAE,EAAE,MAAM,CAAC;IACX,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,iBAAS,mBAAmB,IAAI,aAAa,EAAE,CAsD9C;AAshBD,MAAM,WAAW,qBAAqB;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAC;IACxB;;;;;;;;;;OAUG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,GAAE,qBAA0B,GAAG,yBAAyB,CAuD9F;AAqBD,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAC/B,YAAY,EAAE,aAAa,EAAE,CAAC"}