@dv.nghiem/flowdeck 0.4.7 → 0.4.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -1
- package/dist/agents/default-executor.d.ts +3 -0
- package/dist/agents/default-executor.d.ts.map +1 -0
- package/dist/agents/index.d.ts +2 -1
- package/dist/agents/index.d.ts.map +1 -1
- package/dist/agents/orchestrator.d.ts +2 -5
- package/dist/agents/orchestrator.d.ts.map +1 -1
- package/dist/config/schema.d.ts +1 -15
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/dashboard/server.mjs +14 -1
- package/dist/hooks/orchestrator-guard-hook.d.ts +12 -16
- package/dist/hooks/orchestrator-guard-hook.d.ts.map +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +811 -2042
- package/dist/{tools/dispatch-routing.d.ts → lib/task-routing.d.ts} +1 -3
- package/dist/lib/task-routing.d.ts.map +1 -0
- package/dist/services/agent-contract-registry.d.ts.map +1 -1
- package/dist/services/agent-performance.d.ts +1 -1
- package/dist/services/agent-performance.d.ts.map +1 -1
- package/dist/services/cost-estimator.d.ts +0 -88
- package/dist/services/cost-estimator.d.ts.map +1 -1
- package/dist/services/event-logger.d.ts +1 -1
- package/dist/services/event-logger.d.ts.map +1 -1
- package/dist/services/quick-router.d.ts +24 -0
- package/dist/services/quick-router.d.ts.map +1 -1
- package/dist/services/supervisor-binding.d.ts +6 -0
- package/dist/services/supervisor-binding.d.ts.map +1 -1
- package/dist/services/workflow-router.d.ts +57 -0
- package/dist/services/workflow-router.d.ts.map +1 -0
- package/dist/services/workflow-scorecard.d.ts.map +1 -1
- package/dist/tools/planning-state-lib.d.ts +23 -0
- package/dist/tools/planning-state-lib.d.ts.map +1 -1
- package/docs/concepts/workflows.md +48 -0
- package/docs/index.md +15 -2
- package/docs/reference/workflow-router.md +337 -0
- package/package.json +1 -1
- package/src/commands/fd-discuss.md +8 -1
- package/src/commands/fd-execute.md +25 -3
- package/src/commands/fd-new-feature.md +97 -4
- package/src/commands/fd-plan.md +14 -4
- package/src/commands/fd-quick.md +43 -16
- package/src/rules/common/agent-orchestration.md +116 -24
- package/src/skills/agent-harness-construction/SKILL.md +5 -5
- package/dist/services/delegation-budget.d.ts +0 -54
- package/dist/services/delegation-budget.d.ts.map +0 -1
- package/dist/services/prompt-cache.d.ts +0 -61
- package/dist/services/prompt-cache.d.ts.map +0 -1
- package/dist/services/token-metrics.d.ts +0 -97
- package/dist/services/token-metrics.d.ts.map +0 -1
- package/dist/tools/delegate.d.ts +0 -4
- package/dist/tools/delegate.d.ts.map +0 -1
- package/dist/tools/dispatch-routing.d.ts.map +0 -1
- package/dist/tools/run-pipeline.d.ts +0 -4
- package/dist/tools/run-pipeline.d.ts.map +0 -1
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: FlowDeck agent registry and orchestration rules — which agent to
|
|
2
|
+
description: FlowDeck agent registry and orchestration rules — which agent to route to and when
|
|
3
3
|
always_on: true
|
|
4
4
|
stages: []
|
|
5
5
|
languages: []
|
|
@@ -7,23 +7,40 @@ languages: []
|
|
|
7
7
|
|
|
8
8
|
# Agent Orchestration
|
|
9
9
|
|
|
10
|
-
FlowDeck provides
|
|
10
|
+
FlowDeck provides specialist agents. The orchestrator routes work to them. The orchestrator does NOT execute work itself.
|
|
11
|
+
|
|
12
|
+
## Core Principle: Orchestrator = Router, Not Worker
|
|
13
|
+
|
|
14
|
+
The orchestrator's ONLY responsibilities:
|
|
15
|
+
1. **Analyze** the request
|
|
16
|
+
2. **Classify** the task type
|
|
17
|
+
3. **Choose** the appropriate workflow
|
|
18
|
+
4. **Route** work to the correct agent
|
|
19
|
+
5. **Supervise** progress
|
|
20
|
+
6. **Collect** results
|
|
21
|
+
7. **Return** the final coordinated outcome
|
|
22
|
+
|
|
23
|
+
The orchestrator NEVER:
|
|
24
|
+
- Writes or edits files directly
|
|
25
|
+
- Runs shell commands or builds
|
|
26
|
+
- Implements code itself
|
|
27
|
+
- Runs the full coding workflow itself
|
|
11
28
|
|
|
12
29
|
## Available FlowDeck Agents
|
|
13
30
|
|
|
14
31
|
| Agent | Purpose | When to Use |
|
|
15
32
|
|-------|---------|------------|
|
|
33
|
+
| `@orchestrator` | **Coordinate multi-agent execution** | Managing a full feature delivery — analyzes, classifies, routes, supervises |
|
|
34
|
+
| `@default-executor` | **Execute simple direct tasks** | Quick answers, simple edits, inspect-only analysis, direct stock-tool usage |
|
|
16
35
|
| `@architect` | System design, ADRs, API contracts | Planning new modules, API changes, schema changes |
|
|
17
36
|
| `@build-error-resolver` | Fix build failures and type errors | Immediately when build fails |
|
|
18
|
-
| `@build-resolver` | Diagnose and fix build/compile failures | When build breaks and cause is unclear |
|
|
19
37
|
| `@code-explorer` | Map unfamiliar codebase structure | Before modifying unfamiliar code |
|
|
20
|
-
| `@backend-coder` | Implement features and fixes | All code implementation |
|
|
38
|
+
| `@backend-coder` | Implement features and fixes | All backend code implementation |
|
|
21
39
|
| `@debug-specialist` | Root cause analysis for bugs | When a bug needs deep investigation |
|
|
22
40
|
| `@discusser` | Extract requirements via Q&A | Starting a new feature or phase |
|
|
23
41
|
| `@doc-updater` | Update docs after code changes | After implementation completes |
|
|
24
42
|
| `@plan-checker` | Review PLAN.md before execution | Before executing any plan |
|
|
25
43
|
| `@mapper` | Map codebase to .codebase/ docs | Running /fd-map-codebase |
|
|
26
|
-
| `@orchestrator` | Coordinate multi-agent execution | Managing a full feature delivery |
|
|
27
44
|
| `@task-splitter` | Decompose parallel workstreams | When tasks can run simultaneously |
|
|
28
45
|
| `@performance-optimizer` | Profile and fix performance issues | When app is slow or before release |
|
|
29
46
|
| `@planner` | Create detailed implementation plans | Any multi-file feature |
|
|
@@ -31,16 +48,52 @@ FlowDeck provides 23 specialist agents. Each has a specific role. Using the righ
|
|
|
31
48
|
| `@researcher` | Research APIs, docs, best practices | Using an unfamiliar library or API |
|
|
32
49
|
| `@reviewer` | Code quality and convention review | After writing code, before PRs |
|
|
33
50
|
| `@security-auditor` | Deep security audit | Before merging security-sensitive code |
|
|
34
|
-
| `@task-splitter` | Decompose tasks into parallel tracks | Complex features with parallel work |
|
|
35
51
|
| `@tester` | Write and run tests (TDD) | Implementing features or fixing bugs |
|
|
36
52
|
| `@writer` | Draft project documentation | Writing or updating docs |
|
|
37
53
|
|
|
38
|
-
##
|
|
54
|
+
## Execution Paths
|
|
55
|
+
|
|
56
|
+
After the orchestrator analyzes and classifies a request, it selects ONE execution path:
|
|
57
|
+
|
|
58
|
+
### Direct Execution Path (via @default-executor)
|
|
59
|
+
|
|
60
|
+
For simple, low-risk tasks (< 5 files, no ambiguity):
|
|
61
|
+
- **Mode:** `direct-stock-tools` — use built-in tools directly for focused changes
|
|
62
|
+
- **Mode:** `quick-answer` — answer questions, no file modifications
|
|
63
|
+
- **Mode:** `inspect-only` — read and analyze, produce reports
|
|
64
|
+
- **Mode:** `simple-edit` — surgical changes (rename, typo fix, constant update)
|
|
65
|
+
|
|
66
|
+
The orchestrator routes to `@default-executor` with the chosen mode. The orchestrator does NOT do the work itself.
|
|
67
|
+
|
|
68
|
+
### Specialist Execution Path
|
|
69
|
+
|
|
70
|
+
For normal or complex tasks:
|
|
71
|
+
- Implementation → `@backend-coder`, `@frontend-coder`, `@devops`
|
|
72
|
+
- Testing → `@tester`
|
|
73
|
+
- Research → `@researcher`
|
|
74
|
+
- Review → `@reviewer`, `@security-auditor`
|
|
75
|
+
- Debug → `@debug-specialist`
|
|
76
|
+
- Docs → `@writer`, `@doc-updater`
|
|
77
|
+
|
|
78
|
+
### Workflow Classes
|
|
79
|
+
|
|
80
|
+
| Class | Stages | Executor | When Selected |
|
|
81
|
+
|-------|--------|----------|---------------|
|
|
82
|
+
| `quick` | execute → verify | `@default-executor` | Simple, low-risk tasks (< 5 files, no ambiguity) |
|
|
83
|
+
| `standard` | plan → execute → verify | Specialists | Normal implementation tasks |
|
|
84
|
+
| `explore` | discuss → plan → execute → verify | Specialists | Ambiguous or unfamiliar tasks |
|
|
85
|
+
| `ui-heavy` | discuss → design → plan → execute → verify | Specialists | UI/UX-heavy tasks |
|
|
86
|
+
| `bugfix` | discuss → fix-bug → verify | Specialists | Bug fixes |
|
|
87
|
+
| `docs-only` | write-docs → verify | `@default-executor` or `@writer` | Documentation-only changes |
|
|
88
|
+
| `verify-heavy` | plan → execute → verify | Specialists | High blast radius or sensitive paths |
|
|
89
|
+
|
|
90
|
+
## When to Use Agents Immediately
|
|
39
91
|
|
|
40
92
|
These situations should trigger agent use automatically:
|
|
41
93
|
|
|
42
94
|
| Situation | Agent |
|
|
43
95
|
|-----------|-------|
|
|
96
|
+
| Simple task (< 5 files, no ambiguity) | `@default-executor` |
|
|
44
97
|
| Complex feature spanning 3+ files | `@planner` first, then `@backend-coder` |
|
|
45
98
|
| Code was just written | `@reviewer` |
|
|
46
99
|
| Build fails | `@build-error-resolver` |
|
|
@@ -56,13 +109,13 @@ Independent agents can run simultaneously. Examples:
|
|
|
56
109
|
**Feature implementation:**
|
|
57
110
|
```
|
|
58
111
|
Wave 1 (parallel):
|
|
59
|
-
@researcher
|
|
60
|
-
@backend-coder
|
|
61
|
-
@tester
|
|
112
|
+
@researcher — research the library API
|
|
113
|
+
@backend-coder — implement the model and types
|
|
114
|
+
@tester — write test cases
|
|
62
115
|
|
|
63
116
|
Wave 2 (after Wave 1):
|
|
64
|
-
@backend-coder
|
|
65
|
-
@reviewer
|
|
117
|
+
@backend-coder — implement service using Wave 1 research
|
|
118
|
+
@reviewer — review Wave 1 implementation
|
|
66
119
|
```
|
|
67
120
|
|
|
68
121
|
**Pre-deploy check:**
|
|
@@ -73,19 +126,58 @@ Parallel:
|
|
|
73
126
|
@tester — run full test suite
|
|
74
127
|
```
|
|
75
128
|
|
|
76
|
-
##
|
|
129
|
+
## Adaptive Workflow Routing
|
|
77
130
|
|
|
78
|
-
|
|
131
|
+
The orchestrator selects the most appropriate workflow class at runtime based on task context, complexity, risk, and codebase familiarity.
|
|
79
132
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
133
|
+
### Routing Criteria
|
|
134
|
+
|
|
135
|
+
- **Simplicity**: Is the task a simple rename, typo fix, or config update?
|
|
136
|
+
- **Confidence**: How well does the task description match known patterns?
|
|
137
|
+
- **Risk**: Is the blast radius small (< 3 files) and are no sensitive paths touched?
|
|
138
|
+
- **Codebase familiarity**: Is the codebase mapping fresh (< 24h)?
|
|
139
|
+
- **Complexity**: Is the task cheap (classify, validate, summarize) vs expensive (architect, refactor entire system)?
|
|
140
|
+
|
|
141
|
+
The orchestrator prefers the lightest workflow that is sufficient. Escalate to a richer workflow only when evidence shows the current path is insufficient.
|
|
142
|
+
|
|
143
|
+
### Escalation
|
|
144
|
+
|
|
145
|
+
If the orchestrator discovers during supervision that the initial workflow class is insufficient, it escalates and re-routes:
|
|
146
|
+
- quick → standard: when blast radius exceeds 3 files
|
|
147
|
+
- standard → verify-heavy: when sensitive paths are touched
|
|
148
|
+
- standard → ui-heavy: when design requirements emerge
|
|
149
|
+
- explore → standard: when confidence improves after discussion
|
|
150
|
+
|
|
151
|
+
Escalation is logged with reasons and triggers re-routing to appropriate agents. The orchestrator STILL does not execute the work itself.
|
|
152
|
+
|
|
153
|
+
### Phase Behavior
|
|
154
|
+
|
|
155
|
+
- **quick / docs-only**: Skip discuss and plan phases. Route to `@default-executor`.
|
|
156
|
+
- **standard / verify-heavy**: Skip discuss. Start with plan.
|
|
157
|
+
- **explore / bugfix / ui-heavy**: Include discuss phase for requirements gathering.
|
|
158
|
+
- **ui-heavy**: Always include design phase before execute.
|
|
159
|
+
|
|
160
|
+
### Phase Gating (Relaxed)
|
|
161
|
+
|
|
162
|
+
Phase gating is advisory, not absolute:
|
|
163
|
+
- For `quick` and `docs-only` workflows: phases may be skipped without override.
|
|
164
|
+
- For other workflows: follow the phase order for the selected workflow class.
|
|
165
|
+
- The orchestrator may override phase gating when the workflow class permits it.
|
|
166
|
+
|
|
167
|
+
## Tool Access Enforcement
|
|
168
|
+
|
|
169
|
+
The orchestrator is restricted from using execution tools directly:
|
|
170
|
+
|
|
171
|
+
**Blocked for orchestrator:**
|
|
172
|
+
- File writes: `write`, `create`, `edit`, `patch`, `str_replace_editor`
|
|
173
|
+
- Shell execution: `bash`, `execute`, `terminal`, `shell`
|
|
174
|
+
- Build/test runners: `npm`, `bun`, `cargo`, `make`
|
|
175
|
+
- Container/deployment: `docker`, `kubectl`, `terraform`
|
|
83
176
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
| review | `@reviewer` + `@security-auditor` | `/fd-verify` |
|
|
177
|
+
**Allowed for orchestrator:**
|
|
178
|
+
- Read/search: `read`, `search`, `grep`, `glob`
|
|
179
|
+
- Planning: `planning-state`, `codebase-state`, `repo-memory`
|
|
180
|
+
- Governance: `decision-trace`, `policy-engine`, `reflect`
|
|
181
|
+
- Analysis: `codegraph`, `load-rules`, `council`
|
|
90
182
|
|
|
91
|
-
|
|
183
|
+
All file modifications and command execution MUST be routed to `@default-executor` or specialist agents.
|
|
@@ -78,7 +78,7 @@ async function withRetry<T>(
|
|
|
78
78
|
interface AgentMessage {
|
|
79
79
|
from: string;
|
|
80
80
|
to: string;
|
|
81
|
-
type: 'request' | 'response' | '
|
|
81
|
+
type: 'request' | 'response' | 'assign' | 'result';
|
|
82
82
|
payload: unknown;
|
|
83
83
|
traceId: string;
|
|
84
84
|
}
|
|
@@ -87,20 +87,20 @@ class SupervisorAgent {
|
|
|
87
87
|
private agents: Map<string, Agent>;
|
|
88
88
|
private messageQueue: AgentMessage[] = [];
|
|
89
89
|
|
|
90
|
-
async
|
|
90
|
+
async assignTask(task: Task, targetAgent: string): Promise<Result> {
|
|
91
91
|
const message: AgentMessage = {
|
|
92
92
|
from: this.id,
|
|
93
93
|
to: targetAgent,
|
|
94
|
-
type: '
|
|
94
|
+
type: 'assign',
|
|
95
95
|
payload: task,
|
|
96
96
|
traceId: generateTraceId(),
|
|
97
97
|
};
|
|
98
98
|
return this.sendAndWait(message);
|
|
99
99
|
}
|
|
100
100
|
|
|
101
|
-
async
|
|
101
|
+
async assignParallel(tasks: Task[], agents: string[]): Promise<Result[]> {
|
|
102
102
|
return Promise.all(
|
|
103
|
-
tasks.map((task, i) => this.
|
|
103
|
+
tasks.map((task, i) => this.assignTask(task, agents[i % agents.length]))
|
|
104
104
|
);
|
|
105
105
|
}
|
|
106
106
|
}
|
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* Delegation Budget Manager
|
|
3
|
-
* Tracks and enforces per-run limits on tool calls, delegations, retries, and depth.
|
|
4
|
-
* Stored in .codebase/BUDGETS.json.
|
|
5
|
-
* When a limit is reached the run should stop, escalate, or enter fallback mode.
|
|
6
|
-
*/
|
|
7
|
-
export type BudgetStatus = "active" | "warning" | "exhausted" | "completed";
|
|
8
|
-
export interface BudgetLimits {
|
|
9
|
-
maxToolCalls: number;
|
|
10
|
-
maxDelegatedAgents: number;
|
|
11
|
-
maxRetries: number;
|
|
12
|
-
maxDepth: number;
|
|
13
|
-
maxSameStepRetries: number;
|
|
14
|
-
}
|
|
15
|
-
export interface BudgetConsumed {
|
|
16
|
-
toolCalls: number;
|
|
17
|
-
delegatedAgents: number;
|
|
18
|
-
retries: number;
|
|
19
|
-
maxDepthReached: number;
|
|
20
|
-
/** step_id → retry count */
|
|
21
|
-
sameStepRetries: Record<string, number>;
|
|
22
|
-
}
|
|
23
|
-
export interface DelegationBudget {
|
|
24
|
-
run_id: string;
|
|
25
|
-
session_id: string;
|
|
26
|
-
created_at: string;
|
|
27
|
-
updated_at: string;
|
|
28
|
-
limits: BudgetLimits;
|
|
29
|
-
consumed: BudgetConsumed;
|
|
30
|
-
status: BudgetStatus;
|
|
31
|
-
exhaustion_reason?: string;
|
|
32
|
-
}
|
|
33
|
-
export interface BudgetCheckResult {
|
|
34
|
-
allowed: boolean;
|
|
35
|
-
warning: boolean;
|
|
36
|
-
reason?: string;
|
|
37
|
-
}
|
|
38
|
-
export declare function createBudget(dir: string, run_id: string, session_id?: string): DelegationBudget;
|
|
39
|
-
export declare function getBudget(dir: string, run_id: string): DelegationBudget | null;
|
|
40
|
-
export declare function isBudgetExhausted(dir: string, run_id: string): boolean;
|
|
41
|
-
/**
|
|
42
|
-
* Increment tool call counter. Returns whether the call is allowed.
|
|
43
|
-
*/
|
|
44
|
-
export declare function recordToolCall(dir: string, run_id: string): BudgetCheckResult;
|
|
45
|
-
/**
|
|
46
|
-
* Increment delegation counter and track max depth.
|
|
47
|
-
*/
|
|
48
|
-
export declare function recordDelegation(dir: string, run_id: string, depth: number): BudgetCheckResult;
|
|
49
|
-
/**
|
|
50
|
-
* Increment retry counter for a specific step. Enforces both per-step and total limits.
|
|
51
|
-
*/
|
|
52
|
-
export declare function recordRetry(dir: string, run_id: string, step_id: string): BudgetCheckResult;
|
|
53
|
-
export declare function completeBudget(dir: string, run_id: string): void;
|
|
54
|
-
//# sourceMappingURL=delegation-budget.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"delegation-budget.d.ts","sourceRoot":"","sources":["../../src/services/delegation-budget.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,SAAS,GAAG,WAAW,GAAG,WAAW,CAAA;AAE3E,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAA;IACpB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,MAAM,CAAA;IACvB,OAAO,EAAE,MAAM,CAAA;IACf,eAAe,EAAE,MAAM,CAAA;IACvB,4BAA4B;IAC5B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,YAAY,CAAA;IACpB,QAAQ,EAAE,cAAc,CAAA;IACxB,MAAM,EAAE,YAAY,CAAA;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,OAAO,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AA0ED,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,UAAU,SAAc,GACvB,gBAAgB,CAclB;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI,CAE9E;AAED,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAsB7E;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAgC9F;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAiC3F;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAEhE"}
|
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
/** Agents that are safe to cache — pure read-only / idempotent analysis. */
|
|
2
|
-
export declare const CACHEABLE_AGENTS: Set<string>;
|
|
3
|
-
export interface CacheEntry {
|
|
4
|
-
key: string;
|
|
5
|
-
agent: string;
|
|
6
|
-
state_version: number;
|
|
7
|
-
index_version: number;
|
|
8
|
-
created_at: string;
|
|
9
|
-
ttl_ms: number;
|
|
10
|
-
response: string;
|
|
11
|
-
}
|
|
12
|
-
export interface CacheStats {
|
|
13
|
-
total_entries: number;
|
|
14
|
-
valid_entries: number;
|
|
15
|
-
expired_entries: number;
|
|
16
|
-
cache_size_bytes: number;
|
|
17
|
-
}
|
|
18
|
-
export declare function hashKey(agent: string, prompt: string, context: string, stateVersion: number, indexVersion: number): string;
|
|
19
|
-
/**
|
|
20
|
-
* Normalize a prompt for fuzzy cache lookup.
|
|
21
|
-
* Collapses multiple whitespace characters to single spaces and trims.
|
|
22
|
-
* Only whitespace is normalized — punctuation and case are preserved
|
|
23
|
-
* to avoid false cache hits across semantically different queries.
|
|
24
|
-
*/
|
|
25
|
-
export declare function normalizeForCache(text: string): string;
|
|
26
|
-
/**
|
|
27
|
-
* Like hashKey but using whitespace-normalized prompt and context.
|
|
28
|
-
* Used as a fallback after the exact key misses.
|
|
29
|
-
*/
|
|
30
|
-
export declare function hashKeyNormalized(agent: string, prompt: string, context: string, stateVersion: number, indexVersion: number): string;
|
|
31
|
-
/**
|
|
32
|
-
* Retrieve a cached response.
|
|
33
|
-
*
|
|
34
|
-
* Lookup order:
|
|
35
|
-
* 1. Exact key (prompt.trim() + context.trim())
|
|
36
|
-
* 2. Whitespace-normalized key (collapses multiple spaces/newlines)
|
|
37
|
-
*
|
|
38
|
-
* Returns null when:
|
|
39
|
-
* - Agent is not in CACHEABLE_AGENTS
|
|
40
|
-
* - No entry exists under either key
|
|
41
|
-
* - Entry is expired
|
|
42
|
-
* - stateVersion or indexVersion don't match (state changed since cached)
|
|
43
|
-
*/
|
|
44
|
-
export declare function getCached(dir: string, agent: string, prompt: string, context: string, stateVersion: number, indexVersion: number, safe_to_cache?: boolean): string | null;
|
|
45
|
-
/**
|
|
46
|
-
* Store a response in the cache.
|
|
47
|
-
*
|
|
48
|
-
* No-ops silently when:
|
|
49
|
-
* - safe_to_cache is false
|
|
50
|
-
* - Agent is not in CACHEABLE_AGENTS
|
|
51
|
-
*/
|
|
52
|
-
export declare function setCached(dir: string, agent: string, prompt: string, context: string, stateVersion: number, indexVersion: number, response: string, safe_to_cache?: boolean, ttl_ms?: number): void;
|
|
53
|
-
/**
|
|
54
|
-
* Remove expired entries and trim to MAX_CACHE_ENTRIES.
|
|
55
|
-
* Called automatically on setCached.
|
|
56
|
-
*/
|
|
57
|
-
export declare function pruneExpired(dir: string): void;
|
|
58
|
-
export declare function getCacheStats(dir: string): CacheStats;
|
|
59
|
-
/** Force-invalidate all cache entries for a given directory (call after state writes). */
|
|
60
|
-
export declare function invalidateCache(dir: string): void;
|
|
61
|
-
//# sourceMappingURL=prompt-cache.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"prompt-cache.d.ts","sourceRoot":"","sources":["../../src/services/prompt-cache.ts"],"names":[],"mappings":"AAmBA,4EAA4E;AAC5E,eAAO,MAAM,gBAAgB,aAQ3B,CAAA;AAMF,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AA+BD,wBAAgB,OAAO,CACrB,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CAGR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,GACnB,MAAM,CASR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,aAAa,UAAQ,GACpB,MAAM,GAAG,IAAI,CAaf;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,EAChB,aAAa,UAAQ,EACrB,MAAM,SAAiB,GACtB,IAAI,CAsBN;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAsC9C;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CA6BrD;AAED,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAQjD"}
|
|
@@ -1,97 +0,0 @@
|
|
|
1
|
-
export type WorkflowStage = "discuss" | "plan" | "execute" | "verify" | "design" | "fix-bug" | "write-docs" | "council" | "delegate" | "pipeline" | "exploration" | "unknown";
|
|
2
|
-
export type MetricEventType = "model_call" | "cache_hit" | "duplicate_suppressed" | "rule_bypass" | "retry";
|
|
3
|
-
export interface MetricEvent {
|
|
4
|
-
ts: string;
|
|
5
|
-
workflow_id: string;
|
|
6
|
-
stage: WorkflowStage;
|
|
7
|
-
event: MetricEventType;
|
|
8
|
-
agent?: string;
|
|
9
|
-
/**
|
|
10
|
-
* Model identifier used for this call (e.g. "claude-sonnet-4.6").
|
|
11
|
-
* Enables cost estimation via cost-estimator.ts.
|
|
12
|
-
*/
|
|
13
|
-
model?: string;
|
|
14
|
-
/** Estimated input tokens (chars / 4) */
|
|
15
|
-
est_input_tokens: number;
|
|
16
|
-
/** Estimated output tokens (chars / 4) */
|
|
17
|
-
est_output_tokens: number;
|
|
18
|
-
/** Raw input character count */
|
|
19
|
-
input_chars: number;
|
|
20
|
-
/** Raw output character count */
|
|
21
|
-
output_chars: number;
|
|
22
|
-
duration_ms?: number;
|
|
23
|
-
/** Estimated USD cost for this event (populated when model is known). */
|
|
24
|
-
est_cost_usd?: number;
|
|
25
|
-
}
|
|
26
|
-
export interface StageSummary {
|
|
27
|
-
stage: WorkflowStage;
|
|
28
|
-
model_calls: number;
|
|
29
|
-
cache_hits: number;
|
|
30
|
-
duplicates_suppressed: number;
|
|
31
|
-
rule_bypasses: number;
|
|
32
|
-
retries: number;
|
|
33
|
-
total_est_input_tokens: number;
|
|
34
|
-
total_est_output_tokens: number;
|
|
35
|
-
avg_input_chars: number;
|
|
36
|
-
avg_output_chars: number;
|
|
37
|
-
/** Estimated USD cost for this stage (requires model field on events). */
|
|
38
|
-
est_cost_usd: number;
|
|
39
|
-
}
|
|
40
|
-
export interface MetricsReport {
|
|
41
|
-
workflow_id: string;
|
|
42
|
-
by_stage: StageSummary[];
|
|
43
|
-
totals: {
|
|
44
|
-
model_calls: number;
|
|
45
|
-
cache_hits: number;
|
|
46
|
-
duplicates_suppressed: number;
|
|
47
|
-
rule_bypasses: number;
|
|
48
|
-
retries: number;
|
|
49
|
-
est_input_tokens: number;
|
|
50
|
-
est_output_tokens: number;
|
|
51
|
-
/** Estimated total USD cost across all model calls. 0 if no model info available. */
|
|
52
|
-
est_cost_usd: number;
|
|
53
|
-
/** Estimated USD wasted on retries. */
|
|
54
|
-
retry_cost_usd: number;
|
|
55
|
-
cache_hit_rate: number;
|
|
56
|
-
duplicate_suppression_rate: number;
|
|
57
|
-
rule_bypass_rate: number;
|
|
58
|
-
retry_rate: number;
|
|
59
|
-
};
|
|
60
|
-
efficiency: {
|
|
61
|
-
most_expensive_stage: string;
|
|
62
|
-
cache_effectiveness: "good" | "moderate" | "low";
|
|
63
|
-
avg_context_chars_by_stage: Record<string, number>;
|
|
64
|
-
};
|
|
65
|
-
/** Workflow-level timing if startWorkflowTimer was called. */
|
|
66
|
-
elapsed_ms?: number;
|
|
67
|
-
}
|
|
68
|
-
/** Rough token estimate: ~4 chars per token. */
|
|
69
|
-
export declare function estimateTokens(text: string): number;
|
|
70
|
-
export declare function recordModelCall(dir: string, workflow_id: string, stage: WorkflowStage, inputText: string, outputText: string, agent?: string, duration_ms?: number, model?: string, est_cost_usd?: number): void;
|
|
71
|
-
export declare function recordCacheHit(dir: string, workflow_id: string, stage: WorkflowStage, inputText: string, agent?: string, model?: string): void;
|
|
72
|
-
export declare function recordDuplicateSuppressed(dir: string, workflow_id: string, stage: WorkflowStage, agent?: string): void;
|
|
73
|
-
/**
|
|
74
|
-
* Record a retry model call.
|
|
75
|
-
* This is a model call that happened because the previous attempt failed transiently.
|
|
76
|
-
* Contributes to retry_cost_usd in the cost report.
|
|
77
|
-
*/
|
|
78
|
-
export declare function recordRetryCall(dir: string, workflow_id: string, stage: WorkflowStage, inputText: string, outputText: string, agent?: string, duration_ms?: number, model?: string, est_cost_usd?: number): void;
|
|
79
|
-
/**
|
|
80
|
-
* Record a rule-based bypass — a check answered deterministically without a model call.
|
|
81
|
-
* `check_type` identifies which rule-based check was used.
|
|
82
|
-
*/
|
|
83
|
-
export declare function recordRuleBypass(dir: string, workflow_id: string, stage: WorkflowStage, check_type: string, agent?: string): void;
|
|
84
|
-
/**
|
|
85
|
-
* Mark the start of a workflow run for latency tracking.
|
|
86
|
-
* Call this before the first model call for a workflow.
|
|
87
|
-
*/
|
|
88
|
-
export declare function startWorkflowTimer(workflow_id: string): void;
|
|
89
|
-
/**
|
|
90
|
-
* Get elapsed milliseconds since startWorkflowTimer was called.
|
|
91
|
-
* Returns undefined if the timer was not started.
|
|
92
|
-
*/
|
|
93
|
-
export declare function getWorkflowElapsed(workflow_id: string): number | undefined;
|
|
94
|
-
export declare function getMetricsReport(dir: string, workflow_id: string): MetricsReport;
|
|
95
|
-
/** List all workflow IDs that have metric events. */
|
|
96
|
-
export declare function listTrackedWorkflows(dir: string): string[];
|
|
97
|
-
//# sourceMappingURL=token-metrics.d.ts.map
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"token-metrics.d.ts","sourceRoot":"","sources":["../../src/services/token-metrics.ts"],"names":[],"mappings":"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"}
|
package/dist/tools/delegate.d.ts
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/tools/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAgOtD,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CA6NzE"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"dispatch-routing.d.ts","sourceRoot":"","sources":["../../src/tools/dispatch-routing.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAChB,UAAU,GACV,QAAQ,GACR,gBAAgB,GAChB,WAAW,GACX,QAAQ,GACR,SAAS,GACT,eAAe,GACf,UAAU,GACV,UAAU,GACV,eAAe,CAAA;AAEnB,wBAAgB,WAAW,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAOnD;AAED,wBAAgB,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAUvD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,QAAQ,CAevF;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAa3D;AAmCD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,WAAW,GACX,aAAa,GACb,gBAAgB,GAChB,YAAY,GACZ,UAAU,GACV,eAAe,GACf,YAAY,GACZ,YAAY,CAAA;AAEhB,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAYnE"}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"run-pipeline.d.ts","sourceRoot":"","sources":["../../src/tools/run-pipeline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AA8BtD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAuI5E"}
|