@dv.nghiem/flowdeck 0.5.3 → 0.5.5

package/README.md

@@ -18,8 +18,8 @@ FlowDeck adds a structured, multi-agent development workflow to OpenCode. It coo
 - 🗂️ **Multi-repo support** — coordinate changes across multiple repositories in one session
 - 🔔 **System notifications** — desktop alerts when long-running tasks complete
 - 🛡️ **AI Safety layer** — patch trust scoring, edit gates, phase gating, arch constraint enforcement, failure replay, and regression prediction built into every workflow
-- 🔍 **Governance layer** — capability contracts, agent validator, inter-agent trace graph, delegation budget, deadlock/loop detector, and workflow scorecard
-- 🪝 **Deep System Hooks** — context window monitoring, session idle summaries, shell environment injection, and structured compaction to prevent context loss
+- 🔍 **Governance layer** — capability contracts, agent validator, inter-agent trace graph, deadlock/loop detector, workflow scorecard, and hook-based budget/depth enforcement
+- 🪝 **Deep System Hooks** — context window monitoring, session idle summaries, shell environment injection, structured compaction, and tool.execute.before/after governance hooks
 - 🌐 **Built-in MCPs** — Context7 (docs), Exa (web search), and Grep.app (code search) included and enabled by default
 - 💎 **Ensemble Reasoning** — `council` tool for synthesized consensus from multiple specialized agents
 - 🗺️ **Codegraph Integration** — Codegraph-backed code understanding maps the codebase at indexing time and serves as the shared intelligence layer for all commands and agents.
@@ -122,18 +122,20 @@ FlowDeck's governance layer makes multi-agent execution trustworthy and debuggab
 |---------|-------------|
 | **Agent Contract Registry** | Defines allowed tools, forbidden actions, required inputs, and success criteria for every agent |
 | **Agent Validator** | Checks each agent invocation against its contract before and after execution; mode: `off` / `advisory` / `strict` |
-| **Inter-Agent Trace Graph** | Records every agent-to-agent delegation as a causal span graph; stored in `.codebase/AGENT_SPANS.jsonl` |
-| **Delegation Budget** | Per-run limits on tool calls, sub-agent delegations, retries, and delegation depth; stored in `.codebase/BUDGETS.json` |
+| **Inter-Agent Trace Graph** | Records every agent invocation as a causal span graph; stored in `.codebase/AGENT_SPANS.jsonl` |
+| **Hook-Based Budget & Depth Enforcement** | Per-run limits on tool calls and delegation depth enforced via `tool.execute.before` and `session.created` hooks |
 | **Deadlock / Loop Detector** | Detects agent bounce loops, circular delegation, step retry loops, and stage stalls; stored in `.codebase/DEADLOCK_SIGNALS.jsonl` |
 | **Workflow Scorecard** | 10-dimension quality score for every run (TDD, design-first, approvals, budget efficiency, etc.); stored in `.codebase/SCORECARDS.jsonl` |
 
+Agents route work via native OpenCode `@agent-name` mentions. The `delegate` tool has been removed; depth and tool-call budgets are now enforced transparently for every session.
+
 Configure in `flowdeck.json`:
 
 ```json
 {
   "governance": {
     "validator": { "mode": "advisory" },
-    "delegationBudget": { "maxToolCalls": 200, "maxDepth": 8, "maxSameStepRetries": 3 },
+    "delegationBudget": { "maxToolCalls": 200, "maxDepth": 3, "maxSameStepRetries": 3 },
     "deadlockDetection": { "enabled": true, "bounceThreshold": 3, "autoStop": false },
     "scorecard": { "enabled": true }
   }

package/dist/agents/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAwV/C,wBAAgB,uBAAuB,CACrC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CA6BR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACjE,YAAY,CAAC,EAAE,MAAM,EACrB,kBAAkB,CAAC,EAAE,MAAM,EAC3B,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,eAAe,CAuBjB"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agents/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AA8W/C,wBAAgB,uBAAuB,CACrC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,MAAM,CA6BR;AAED,wBAAgB,uBAAuB,CACrC,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC,MAAM,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EACjE,YAAY,CAAC,EAAE,MAAM,EACrB,kBAAkB,CAAC,EAAE,MAAM,EAC3B,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,EAC5B,aAAa,CAAC,EAAE,MAAM,GACrB,eAAe,CAuBjB"}

package/dist/hooks/event-log-hook.d.ts

@@ -2,14 +2,14 @@ import type { SpanStatus } from "@/services/harness-types";
 type AppLog = (msg: string) => void;
 export type OnToolAfterCallback = (toolName: string, args: Record<string, unknown>, output: unknown, sessionId: string, status: string) => void;
 export interface SpanLifecycleCallbacks {
-    /** Called when a delegated session starts (span open). */
+    /** Called when a subagent session starts (span open). */
     onSpanOpen?: (props: {
         spanId: string;
         agent: string;
         sessionId: string;
         parentSessionId?: string;
     }) => void;
-    /** Called when a delegated session ends (span close). */
+    /** Called when a subagent session ends (span close). */
     onSpanClose?: (props: {
         spanId: string;
         status: Exclude<SpanStatus, "running">;

package/dist/hooks/event-log-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-log-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/event-log-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;AAEnC,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,KACX,IAAI,CAAA;AAET,MAAM,WAAW,sBAAsB;IACrC,0DAA0D;IAC1D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,KAAK,IAAI,CAAA;IACV,yDAAyD;IACzD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QACpB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACtC,SAAS,EAAE,MAAM,CAAA;KAClB,KAAK,IAAI,CAAA;CACX;AASD,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAOjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,mBAAmB,EACjC,aAAa,CAAC,EAAE,sBAAsB;gBASlB;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,aAAa,GAAG,cAAc,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;eA2BvE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,aAAa,GAAG,cAAc,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;iBA0CvE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,SAAS,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;EA4G1E;AAGD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,GAAG,GACd,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,GAAG,GACd,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,KAAK,EAAE,GAAG,GACT,OAAO,CAAC,OAAO,CAAC,CAElB"}
+{"version":3,"file":"event-log-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/event-log-hook.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,KAAK,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;AAEnC,MAAM,MAAM,mBAAmB,GAAG,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,KACX,IAAI,CAAA;AAET,MAAM,WAAW,sBAAsB;IACrC,yDAAyD;IACzD,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,KAAK,EAAE,MAAM,CAAA;QACb,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,CAAC,EAAE,MAAM,CAAA;KACzB,KAAK,IAAI,CAAA;IACV,wDAAwD;IACxD,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE;QACpB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,OAAO,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACtC,SAAS,EAAE,MAAM,CAAA;KAClB,KAAK,IAAI,CAAA;CACX;AASD,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAgB,0BAA0B,IAAI,IAAI,CAOjD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,EACd,WAAW,CAAC,EAAE,mBAAmB,EACjC,aAAa,CAAC,EAAE,sBAAsB;gBASlB;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,aAAa,GAAG,cAAc,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC;eA2BvE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,aAAa,GAAG,cAAc,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;iBA0CvE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,SAAS,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC;EA4G1E;AAGD,wBAAsB,kBAAkB,CACtC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,GAAG,GACd,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,SAAS,EAAE,GAAG,EACd,UAAU,EAAE,GAAG,GACd,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAC1B,KAAK,EAAE,GAAG,GACT,OAAO,CAAC,OAAO,CAAC,CAElB"}

package/dist/hooks/orchestrator-guard-hook.d.ts

@@ -3,8 +3,11 @@
  *
  * Enforces the "orchestrator as coordinator, not executor" rule for the primary session.
  * The guard consults the orchestrator capability contract in agent-contract-registry
- * and the harness policy. Any tool not in the orchestrator's allowedTools list is
- * blocked when run from the primary session.
+ * and the harness policy.
+ *
+ * IMPORTANT: The guard never throws. When a tool is blocked it returns a block
+ * message string that the caller should surface as tool output. This keeps the
+ * orchestrator turn alive and gives it a path forward (delegate or ask the human).
  *
  * To disable: set FLOWDECK_ORCHESTRATOR_GUARD=off in the environment.
  * Default is ON.
@@ -13,6 +16,7 @@ import type { HarnessPolicy } from "../services/harness-policy";
 export declare class OrchestratorGuard {
     private primarySessionId;
     private policy?;
+    private blockedHistory;
     setPolicy(policy: HarnessPolicy): void;
     onEvent(event: {
         type?: string;
@@ -21,12 +25,19 @@ export declare class OrchestratorGuard {
         sessionID?: string;
         sessionId?: string;
     }): void;
-    check(sessionId: string, toolName: string): void;
+    /**
+     * Check whether the tool is allowed for the primary session.
+     * Returns undefined when allowed, or a block message string when blocked.
+     * Never throws.
+     */
+    check(sessionId: string, toolName: string): string | undefined;
     /** Returns true if the tool is not in the orchestrator contract allowlist. */
     _isBlockedForTest(name: string): boolean;
     /** Returns true if the tool is in the orchestrator contract allowlist. */
     _isAllowedForTest(name: string): boolean;
     /** Exposed for testing. */
     _setPrimarySessionIdForTest(id: string | null): void;
+    /** Exposed for testing. */
+    _getRepeatCountForTest(sessionId: string, toolName: string): number;
 }
 //# sourceMappingURL=orchestrator-guard-hook.d.ts.map

package/dist/hooks/orchestrator-guard-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-guard-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/orchestrator-guard-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAkB,MAAM,4BAA4B,CAAA;AA6B/E,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAe;IAE9B,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAItC,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAkBtH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI;IAyBhD,8EAA8E;IAC9E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAOxC,0EAA0E;IAC1E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxC,2BAA2B;IAC3B,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;CAGrD"}
+{"version":3,"file":"orchestrator-guard-hook.d.ts","sourceRoot":"","sources":["../../src/hooks/orchestrator-guard-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAA;AAqF/D,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,gBAAgB,CAAsB;IAC9C,OAAO,CAAC,MAAM,CAAC,CAAe;IAC9B,OAAO,CAAC,cAAc,CAA8C;IAEpE,SAAS,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAItC,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAmBtH;;;;OAIG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAyB9D,8EAA8E;IAC9E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAOxC,0EAA0E;IAC1E,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIxC,2BAA2B;IAC3B,2BAA2B,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAIpD,2BAA2B;IAC3B,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM;CAGpE"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAkHjD,QAAA,MAAM,MAAM,EAAE,MAuSb,CAAA;AAED,eAAe,MAAM,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAiHjD,QAAA,MAAM,MAAM,EAAE,MAuTb,CAAA;AAED,eAAe,MAAM,CAAA"}