mirror of
https://github.com/RooVetGit/Roo-Code.git
synced 2026-09-12 23:01:21 +00:00
feat(intent): enforce intent handshake and gatekeeper; add IntentHookEngine and handshake test
This commit is contained in:
Rediet Bekele
parent
fcea38d432
commit
9292f2f03f
15 changed files with 847 additions and 273 deletions
|
|
@ -1,62 +1,69 @@
|
|||
# Phase 1: The Handshake (Reasoning Loop Implementation)
|
||||
|
||||
## 1. Executive Summary
|
||||
|
||||
The objective is to move beyond text-based version control by implementing a **Deterministic Hook System**.
|
||||
This system enforces a **"Plan-First" workflow** where AI agents must formally declare their **Intent** before mutating the codebase.
|
||||
|
||||
---
|
||||
|
||||
## 2. Nervous System & Interception Points
|
||||
|
||||
Based on the codebase audit, the following functions represent the "Strategic High Ground" for hook injection:
|
||||
|
||||
### A. The "Reasoning Loop" (Prompt Construction)
|
||||
- **Location**: `src/core/prompts/` and `src/core/RooCode.ts`
|
||||
- **Function**: Handles the assembly of system instructions and tool definitions.
|
||||
|
||||
- **Location**: `src/core/prompts/`
|
||||
- **Function**: Handles the assembly of system instructions and tool definitions.
|
||||
- **Injection Strategy**: Modify the SystemPrompt generator to include the mandatory `select_active_intent` tool and instructions that forbid file writes without an active session intent.
|
||||
|
||||
### B. The "Pre-Hook" (Command Execution)
|
||||
- **Location**: `src/integrations/terminal/TerminalManager.ts` and `src/services/EditorService.ts`
|
||||
- **Function**: `executeCommand()` and `openFile()`
|
||||
|
||||
- **Location**: `src/integrations/terminal/TerminalManager.ts` and `src/services/EditorService.ts`
|
||||
- **Function**: `executeCommand()` and `openFile()`
|
||||
- **Injection Strategy**: Intercept calls before they reach the terminal or editor. If the agent attempts a structural change (e.g., `npm install` or `rm`), the Pre-Hook validates the action against the `owned_scope` defined in `.orchestration/active_intents.yaml`.
|
||||
|
||||
### C. The "Post-Hook" (File Mutations)
|
||||
- **Location**: `src/core/webview/DiffViewProvider.ts` and `src/services/RelayService.ts`
|
||||
- **Function**: `writeFile()` and `applyDiff()`
|
||||
|
||||
- **Location**: `src/core/webview/DiffViewProvider.ts` and `src/services/RelayService.ts`
|
||||
- **Function**: `writeFile()` and `applyDiff()`
|
||||
- **Injection Strategy**: Intercept immediately after a successful write. This hook triggers the Content Hashing engine to generate a spatial fingerprint of the change, appending the metadata to the `.orchestration/agent_trace.jsonl` ledger.
|
||||
|
||||
---
|
||||
|
||||
## 3. The Two-Stage State Machine
|
||||
|
||||
To eliminate "Vibe Coding," the execution flow is re-architected into a strict handshake:
|
||||
|
||||
| State | Entity | Action |
|
||||
|-------|--------|--------|
|
||||
| 1. Request | User | "Refactor the auth middleware." |
|
||||
| 2. Intent Handshake | Agent | Calls `select_active_intent("INT-001")`. |
|
||||
| 3. Validation | Pre-Hook | Pauses loop. Queries `.orchestration/`. Injects constraints (e.g., "Use JWT, not Session"). |
|
||||
| 4. Contextual Action | Agent | Generates code with injected constraints. Calls `write_file`. |
|
||||
| 5. Trace Logging | Post-Hook | Calculates sha256 hash. Updates `agent_trace.jsonl`. |
|
||||
| State | Entity | Action |
|
||||
| -------------------- | --------- | ------------------------------------------------------------------------------------------- |
|
||||
| 1. Request | User | "Refactor the auth middleware." |
|
||||
| 2. Intent Handshake | Agent | Calls `select_active_intent("INT-001")`. |
|
||||
| 3. Validation | Pre-Hook | Pauses loop. Queries `.orchestration/`. Injects constraints (e.g., "Use JWT, not Session"). |
|
||||
| 4. Contextual Action | Agent | Generates code with injected constraints. Calls `write_file`. |
|
||||
| 5. Trace Logging | Post-Hook | Calculates sha256 hash. Updates `agent_trace.jsonl`. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Logical Architecture Diagram
|
||||
User Prompt → Extension Host → Pre-Hook (Intent Validation) → LLM → Post-Hook (Trace Logging) → File System
|
||||
|
||||
User Prompt → Extension Host → Pre-Hook (Intent Validation) → LLM → Post-Hook (Trace Logging) → File System
|
||||
|
||||
---
|
||||
|
||||
## 5. Data Model Specification
|
||||
|
||||
The following machine-managed files in `.orchestration/` act as the "Source of Truth" for AI governance:
|
||||
|
||||
- **active_intents.yaml**: The "Why." Defines scope, constraints, and Definition of Done (DoD).
|
||||
- **agent_trace.jsonl**: The "How." An append-only ledger linking Intent IDs to specific Code Hashes.
|
||||
- **intent_map.md**: The "Where." A spatial map linking business logic to AST nodes and files.
|
||||
- **active_intents.yaml**: The "Why." Defines scope, constraints, and Definition of Done (DoD).
|
||||
- **agent_trace.jsonl**: The "How." An append-only ledger linking Intent IDs to specific Code Hashes.
|
||||
- **intent_map.md**: The "Where." A spatial map linking business logic to AST nodes and files.
|
||||
- **AGENT.md**: The "Memory." Shared architectural decisions and lessons learned across agent sessions.
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 1 Implementation Goals
|
||||
- **Initialize Sidecar**: Automatically generate the `.orchestration/` directory on extension activation.
|
||||
- **Tool Injection**: Register `select_active_intent` as a core capability.
|
||||
- **Strict Middleware**: Implement logic that blocks `write_file` if `current_session_intent` is null.
|
||||
|
||||
- **Initialize Sidecar**: Automatically generate the `.orchestration/` directory on extension activation.
|
||||
- **Tool Injection**: Register `select_active_intent` as a core capability.
|
||||
- **Strict Middleware**: Implement logic that blocks `write_file` if `current_session_intent` is null.
|
||||
|
|
|
|||
|
|
@ -12,11 +12,5 @@ export { useTaskSubmit } from "./useTaskSubmit.js"
|
|||
export { useGlobalInput } from "./useGlobalInput.js"
|
||||
export { usePickerHandlers } from "./usePickerHandlers.js"
|
||||
|
||||
// Export types
|
||||
export type { UseFollowupCountdownOptions } from "./useFollowupCountdown.js"
|
||||
export type { UseFocusManagementOptions, UseFocusManagementReturn } from "./useFocusManagement.js"
|
||||
export type { UseMessageHandlersOptions, UseMessageHandlersReturn } from "./useMessageHandlers.js"
|
||||
export type { UseExtensionHostOptions, UseExtensionHostReturn } from "./useExtensionHost.js"
|
||||
export type { UseTaskSubmitOptions, UseTaskSubmitReturn } from "./useTaskSubmit.js"
|
||||
export type { UseGlobalInputOptions } from "./useGlobalInput.js"
|
||||
export type { UsePickerHandlersOptions, UsePickerHandlersReturn } from "./usePickerHandlers.js"
|
||||
// Export intent hooks
|
||||
export { IntentHookEngine } from "./intentHooks.js"
|
||||
|
|
|
|||
|
|
@ -1,54 +1,149 @@
|
|||
// src/hooks/intentHooks.ts
|
||||
import fs from 'fs';
|
||||
import yaml from 'js-yaml';
|
||||
// @ts-ignore - fs module for Node.js runtime
|
||||
import fs from "fs"
|
||||
|
||||
let yamlModule: any = null
|
||||
|
||||
// Dynamically load yaml module with error handling
|
||||
try {
|
||||
// @ts-ignore
|
||||
yamlModule = require("js-yaml")
|
||||
} catch {
|
||||
// yaml not available, will handle gracefully in loadIntents()
|
||||
}
|
||||
|
||||
interface Intent {
|
||||
id: string;
|
||||
name: string;
|
||||
status: string;
|
||||
owned_scope: string[];
|
||||
constraints: string[];
|
||||
acceptance_criteria: string[];
|
||||
id: string
|
||||
name: string
|
||||
status: string
|
||||
owned_scope: string[]
|
||||
constraints: string[]
|
||||
acceptance_criteria: string[]
|
||||
}
|
||||
|
||||
export class IntentHookEngine {
|
||||
private intents: Record<string, Intent>;
|
||||
private intents: Record<string, Intent>
|
||||
private currentSessionIntent: Intent | null = null
|
||||
|
||||
constructor() {
|
||||
this.intents = this.loadIntents();
|
||||
}
|
||||
constructor() {
|
||||
this.intents = this.loadIntents()
|
||||
}
|
||||
|
||||
private loadIntents(): Record<string, Intent> {
|
||||
const file = fs.readFileSync('.orchestration/active_intents.yaml', 'utf8');
|
||||
const data = yaml.load(file) as any;
|
||||
const intents: Record<string, Intent> = {};
|
||||
data.active_intents.forEach((intent: Intent) => {
|
||||
intents[intent.id] = intent;
|
||||
});
|
||||
return intents;
|
||||
}
|
||||
private loadIntents(): Record<string, Intent> {
|
||||
if (!yamlModule || !yamlModule.load) {
|
||||
console.warn("YAML module (js-yaml) not available. Intents cannot be loaded.")
|
||||
return {}
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-Hook logic for select_active_intent
|
||||
* - Validates intent_id
|
||||
* - Injects constraints and scope
|
||||
* - Returns XML <intent_context> block
|
||||
*/
|
||||
preHook(tool: string, payload: any) {
|
||||
if (tool === 'select_active_intent') {
|
||||
const intentId = payload.intent_id;
|
||||
const intent = this.intents[intentId];
|
||||
try {
|
||||
const file = fs.readFileSync(".orchestration/active_intents.yaml", "utf8")
|
||||
const data = yamlModule.load(file)
|
||||
const intents: Record<string, Intent> = {}
|
||||
if (Array.isArray(data?.active_intents)) {
|
||||
data.active_intents.forEach((intent: Intent) => {
|
||||
intents[intent.id] = intent
|
||||
})
|
||||
}
|
||||
return intents
|
||||
} catch (error) {
|
||||
console.warn(`Failed to load intents: ${error instanceof Error ? error.message : String(error)}`)
|
||||
return {}
|
||||
}
|
||||
}
|
||||
|
||||
// Gatekeeper: block if invalid
|
||||
if (!intent) {
|
||||
throw new Error("You must cite a valid active Intent ID");
|
||||
}
|
||||
/**
|
||||
* Gatekeeper: Pre-Hook validation before execution
|
||||
* - Blocks write_file and apply_diff without an active session intent
|
||||
* - Validates that the current session intent exists
|
||||
*/
|
||||
gatekeeper(tool: string): { allowed: boolean; message?: string } {
|
||||
const restrictedTools = ["write_file", "apply_diff", "execute_command"]
|
||||
|
||||
// Construct XML block
|
||||
return `<intent_context>
|
||||
<constraints>${intent.constraints.join(', ')}</constraints>
|
||||
<scope>${intent.owned_scope.join(', ')}</scope>
|
||||
</intent_context>`;
|
||||
}
|
||||
}
|
||||
const toolIsRestricted = restrictedTools.some((t) => t === tool)
|
||||
if (toolIsRestricted) {
|
||||
if (!this.currentSessionIntent) {
|
||||
return {
|
||||
allowed: false,
|
||||
message:
|
||||
"You must cite a valid active Intent ID via select_active_intent before performing structural changes.",
|
||||
}
|
||||
}
|
||||
|
||||
// Optional: validate that the tool operation is within owned_scope
|
||||
// This would require parsing the file path from the tool payload
|
||||
// Implementation deferred to post-hook phase
|
||||
}
|
||||
|
||||
return { allowed: true }
|
||||
}
|
||||
|
||||
/**
|
||||
* Pre-Hook logic for select_active_intent
|
||||
* - Validates intent_id exists in active_intents.yaml
|
||||
* - Sets currentSessionIntent to track active context
|
||||
* - Injects constraints and scope
|
||||
* - Returns XML <intent_context> block
|
||||
*/
|
||||
preHook(tool: string, payload: any): string | { allowed: boolean; message: string } {
|
||||
// Gatekeeper check for restricted mutations
|
||||
const gatekeeperResult = this.gatekeeper(tool)
|
||||
if (!gatekeeperResult.allowed) {
|
||||
return {
|
||||
allowed: false,
|
||||
message: gatekeeperResult.message || "Operation blocked: no active intent.",
|
||||
}
|
||||
}
|
||||
|
||||
// Handle select_active_intent tool
|
||||
if (tool === "select_active_intent") {
|
||||
const intentId = payload.intent_id
|
||||
const intent = this.intents[intentId]
|
||||
|
||||
// Gatekeeper: block if invalid intent_id
|
||||
if (!intent) {
|
||||
throw new Error(
|
||||
`Invalid Intent ID: "${intentId}". You must cite a valid active Intent ID from .orchestration/active_intents.yaml`,
|
||||
)
|
||||
}
|
||||
|
||||
// Set the current session intent to unlock mutations
|
||||
this.currentSessionIntent = intent
|
||||
|
||||
// Construct XML context block with complete intent metadata
|
||||
const intentContextBlock = `<intent_context>
|
||||
<intent_id>${intent.id}</intent_id>
|
||||
<intent_name>${intent.name}</intent_name>
|
||||
<status>${intent.status}</status>
|
||||
<constraints>
|
||||
${intent.constraints.map((c) => ` - ${c}`).join("\n")}
|
||||
</constraints>
|
||||
<owned_scope>
|
||||
${intent.owned_scope.map((s) => ` - ${s}`).join("\n")}
|
||||
</owned_scope>
|
||||
<acceptance_criteria>
|
||||
${intent.acceptance_criteria.map((ac) => ` - ${ac}`).join("\n")}
|
||||
</acceptance_criteria>
|
||||
</intent_context>`
|
||||
|
||||
return intentContextBlock
|
||||
}
|
||||
|
||||
return ""
|
||||
}
|
||||
|
||||
/**
|
||||
* Retrieve the current active session intent
|
||||
* Useful for post-hook validation and tracing
|
||||
*/
|
||||
getCurrentSessionIntent(): Intent | null {
|
||||
return this.currentSessionIntent
|
||||
}
|
||||
|
||||
/**
|
||||
* Clear the current session intent
|
||||
* Called when task is completed or session ends
|
||||
*/
|
||||
clearSessionIntent(): void {
|
||||
this.currentSessionIntent = null
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"extends": "@roo-code/config-typescript/base.json",
|
||||
"compilerOptions": {
|
||||
"types": ["vitest/globals"],
|
||||
"types": ["node", "vitest/globals"],
|
||||
"outDir": "dist",
|
||||
"jsx": "react-jsx",
|
||||
"jsxImportSource": "react",
|
||||
|
|
|
|||
|
|
@ -38,6 +38,7 @@
|
|||
"eslint": "^9.27.0",
|
||||
"glob": "^11.1.0",
|
||||
"husky": "^9.1.7",
|
||||
"js-yaml": "4",
|
||||
"knip": "^5.44.4",
|
||||
"lint-staged": "^16.0.0",
|
||||
"mkdirp": "^3.0.1",
|
||||
|
|
@ -47,7 +48,8 @@
|
|||
"rimraf": "^6.0.1",
|
||||
"tsx": "^4.19.3",
|
||||
"turbo": "^2.5.6",
|
||||
"typescript": "5.8.3"
|
||||
"typescript": "5.8.3",
|
||||
"vitest": "^4.0.18"
|
||||
},
|
||||
"lint-staged": {
|
||||
"*.{js,jsx,ts,tsx,json,css,md}": [
|
||||
|
|
|
|||
109
pnpm-lock.yaml
generated
109
pnpm-lock.yaml
generated
|
|
@ -50,6 +50,9 @@ importers:
|
|||
husky:
|
||||
specifier: ^9.1.7
|
||||
version: 9.1.7
|
||||
js-yaml:
|
||||
specifier: '4'
|
||||
version: 4.1.0
|
||||
knip:
|
||||
specifier: ^5.44.4
|
||||
version: 5.60.2(@types/node@24.2.1)(typescript@5.8.3)
|
||||
|
|
@ -80,6 +83,9 @@ importers:
|
|||
typescript:
|
||||
specifier: 5.8.3
|
||||
version: 5.8.3
|
||||
vitest:
|
||||
specifier: ^4.0.18
|
||||
version: 4.0.18(@opentelemetry/api@1.9.0)(@types/node@24.2.1)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
apps/cli:
|
||||
dependencies:
|
||||
|
|
@ -8976,6 +8982,7 @@ packages:
|
|||
prebuild-install@7.1.3:
|
||||
resolution: {integrity: sha512-8Mf2cbV7x1cXPUILADGI3wuhfqWvtiLA1iclTDbFRZkgRQS0NqsPZphna9V+HyTEadheuPmjaJMsbzKQFOzLug==}
|
||||
engines: {node: '>=10'}
|
||||
deprecated: No longer maintained. Please contact the author of the relevant native addon; alternatives are available.
|
||||
hasBin: true
|
||||
|
||||
prelude-ls@1.2.1:
|
||||
|
|
@ -10087,9 +10094,6 @@ packages:
|
|||
tinyexec@0.3.2:
|
||||
resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
|
||||
|
||||
tinyexec@1.0.1:
|
||||
resolution: {integrity: sha512-5uC6DDlmeqiOwCPmK9jMSdOuZTh8bU39Ys6yidB+UTt5hfZUPGAypSgFRiEp+jbi9qH40BLDvy85jIU88wKSqw==}
|
||||
|
||||
tinyexec@1.0.2:
|
||||
resolution: {integrity: sha512-W/KYk+NFhkmsYpuHq5JykngiOCnxeVL8v8dFnqxSD8qEEdRfXk1SDM6JzNqcERbcGYj9tMrDQBYV9cjgnunFIg==}
|
||||
engines: {node: '>=18'}
|
||||
|
|
@ -11166,7 +11170,7 @@ snapshots:
|
|||
'@antfu/install-pkg@1.1.0':
|
||||
dependencies:
|
||||
package-manager-detector: 1.5.0
|
||||
tinyexec: 1.0.1
|
||||
tinyexec: 1.0.2
|
||||
|
||||
'@antfu/utils@8.1.1': {}
|
||||
|
||||
|
|
@ -12546,7 +12550,7 @@ snapshots:
|
|||
'@jridgewell/gen-mapping@0.3.8':
|
||||
dependencies:
|
||||
'@jridgewell/set-array': 1.2.1
|
||||
'@jridgewell/sourcemap-codec': 1.5.0
|
||||
'@jridgewell/sourcemap-codec': 1.5.5
|
||||
'@jridgewell/trace-mapping': 0.3.25
|
||||
|
||||
'@jridgewell/resolve-uri@3.1.2': {}
|
||||
|
|
@ -12560,7 +12564,7 @@ snapshots:
|
|||
'@jridgewell/trace-mapping@0.3.25':
|
||||
dependencies:
|
||||
'@jridgewell/resolve-uri': 3.1.2
|
||||
'@jridgewell/sourcemap-codec': 1.5.0
|
||||
'@jridgewell/sourcemap-codec': 1.5.5
|
||||
|
||||
'@kwsites/file-exists@1.1.1':
|
||||
dependencies:
|
||||
|
|
@ -14231,7 +14235,7 @@ snapshots:
|
|||
enhanced-resolve: 5.18.1
|
||||
jiti: 2.4.2
|
||||
lightningcss: 1.29.2
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
source-map-js: 1.2.1
|
||||
tailwindcss: 4.1.6
|
||||
|
||||
|
|
@ -14241,7 +14245,7 @@ snapshots:
|
|||
enhanced-resolve: 5.18.1
|
||||
jiti: 2.4.2
|
||||
lightningcss: 1.30.1
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
source-map-js: 1.2.1
|
||||
tailwindcss: 4.1.8
|
||||
|
||||
|
|
@ -14900,7 +14904,7 @@ snapshots:
|
|||
dependencies:
|
||||
'@vitest/spy': 3.2.4
|
||||
estree-walker: 3.0.3
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
optionalDependencies:
|
||||
vite: 6.3.5(@types/node@20.17.50)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
|
|
@ -14908,7 +14912,7 @@ snapshots:
|
|||
dependencies:
|
||||
'@vitest/spy': 3.2.4
|
||||
estree-walker: 3.0.3
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
optionalDependencies:
|
||||
vite: 6.3.5(@types/node@20.17.57)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
|
|
@ -14916,17 +14920,17 @@ snapshots:
|
|||
dependencies:
|
||||
'@vitest/spy': 3.2.4
|
||||
estree-walker: 3.0.3
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
optionalDependencies:
|
||||
vite: 6.3.5(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
'@vitest/mocker@4.0.18(vite@6.3.6(@types/node@20.17.57)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0))':
|
||||
'@vitest/mocker@4.0.18(vite@6.3.6(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0))':
|
||||
dependencies:
|
||||
'@vitest/spy': 4.0.18
|
||||
estree-walker: 3.0.3
|
||||
magic-string: 0.30.21
|
||||
optionalDependencies:
|
||||
vite: 6.3.6(@types/node@20.17.57)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
vite: 6.3.6(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
'@vitest/pretty-format@3.2.4':
|
||||
dependencies:
|
||||
|
|
@ -14950,7 +14954,7 @@ snapshots:
|
|||
'@vitest/snapshot@3.2.4':
|
||||
dependencies:
|
||||
'@vitest/pretty-format': 3.2.4
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
pathe: 2.0.3
|
||||
|
||||
'@vitest/snapshot@4.0.18':
|
||||
|
|
@ -14974,7 +14978,7 @@ snapshots:
|
|||
sirv: 3.0.1
|
||||
tinyglobby: 0.2.14
|
||||
tinyrainbow: 2.0.0
|
||||
vitest: 3.2.4(@types/debug@4.1.12)(@types/node@24.2.1)(@vitest/ui@3.2.4)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
vitest: 3.2.4(@types/debug@4.1.12)(@types/node@20.17.57)(@vitest/ui@3.2.4)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
|
||||
'@vitest/utils@3.2.4':
|
||||
dependencies:
|
||||
|
|
@ -17010,14 +17014,18 @@ snapshots:
|
|||
dependencies:
|
||||
pend: 1.2.0
|
||||
|
||||
fdir@6.4.4(picomatch@4.0.2):
|
||||
fdir@6.4.4(picomatch@4.0.3):
|
||||
optionalDependencies:
|
||||
picomatch: 4.0.2
|
||||
picomatch: 4.0.3
|
||||
|
||||
fdir@6.4.6(picomatch@4.0.2):
|
||||
optionalDependencies:
|
||||
picomatch: 4.0.2
|
||||
|
||||
fdir@6.4.6(picomatch@4.0.3):
|
||||
optionalDependencies:
|
||||
picomatch: 4.0.3
|
||||
|
||||
fdir@6.5.0(picomatch@4.0.3):
|
||||
optionalDependencies:
|
||||
picomatch: 4.0.3
|
||||
|
|
@ -17071,7 +17079,7 @@ snapshots:
|
|||
|
||||
fix-dts-default-cjs-exports@1.0.1:
|
||||
dependencies:
|
||||
magic-string: 0.30.17
|
||||
magic-string: 0.30.21
|
||||
mlly: 1.7.4
|
||||
rollup: 4.40.2
|
||||
|
||||
|
|
@ -21163,14 +21171,12 @@ snapshots:
|
|||
|
||||
tinyexec@0.3.2: {}
|
||||
|
||||
tinyexec@1.0.1: {}
|
||||
|
||||
tinyexec@1.0.2: {}
|
||||
|
||||
tinyglobby@0.2.14:
|
||||
dependencies:
|
||||
fdir: 6.4.6(picomatch@4.0.2)
|
||||
picomatch: 4.0.2
|
||||
fdir: 6.4.6(picomatch@4.0.3)
|
||||
picomatch: 4.0.3
|
||||
|
||||
tinyglobby@0.2.15:
|
||||
dependencies:
|
||||
|
|
@ -21723,11 +21729,11 @@ snapshots:
|
|||
vite@6.3.5(@types/node@20.17.50)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0):
|
||||
dependencies:
|
||||
esbuild: 0.25.9
|
||||
fdir: 6.4.4(picomatch@4.0.2)
|
||||
picomatch: 4.0.2
|
||||
fdir: 6.4.4(picomatch@4.0.3)
|
||||
picomatch: 4.0.3
|
||||
postcss: 8.5.6
|
||||
rollup: 4.40.2
|
||||
tinyglobby: 0.2.14
|
||||
tinyglobby: 0.2.15
|
||||
optionalDependencies:
|
||||
'@types/node': 20.17.50
|
||||
fsevents: 2.3.3
|
||||
|
|
@ -21739,11 +21745,11 @@ snapshots:
|
|||
vite@6.3.5(@types/node@20.17.57)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0):
|
||||
dependencies:
|
||||
esbuild: 0.25.9
|
||||
fdir: 6.4.4(picomatch@4.0.2)
|
||||
picomatch: 4.0.2
|
||||
fdir: 6.4.4(picomatch@4.0.3)
|
||||
picomatch: 4.0.3
|
||||
postcss: 8.5.6
|
||||
rollup: 4.40.2
|
||||
tinyglobby: 0.2.14
|
||||
tinyglobby: 0.2.15
|
||||
optionalDependencies:
|
||||
'@types/node': 20.17.57
|
||||
fsevents: 2.3.3
|
||||
|
|
@ -21755,11 +21761,11 @@ snapshots:
|
|||
vite@6.3.5(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0):
|
||||
dependencies:
|
||||
esbuild: 0.25.9
|
||||
fdir: 6.4.4(picomatch@4.0.2)
|
||||
picomatch: 4.0.2
|
||||
fdir: 6.4.4(picomatch@4.0.3)
|
||||
picomatch: 4.0.3
|
||||
postcss: 8.5.6
|
||||
rollup: 4.40.2
|
||||
tinyglobby: 0.2.14
|
||||
tinyglobby: 0.2.15
|
||||
optionalDependencies:
|
||||
'@types/node': 24.2.1
|
||||
fsevents: 2.3.3
|
||||
|
|
@ -21951,7 +21957,7 @@ snapshots:
|
|||
vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@20.17.57)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0):
|
||||
dependencies:
|
||||
'@vitest/expect': 4.0.18
|
||||
'@vitest/mocker': 4.0.18(vite@6.3.6(@types/node@20.17.57)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0))
|
||||
'@vitest/mocker': 4.0.18(vite@6.3.6(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0))
|
||||
'@vitest/pretty-format': 4.0.18
|
||||
'@vitest/runner': 4.0.18
|
||||
'@vitest/snapshot': 4.0.18
|
||||
|
|
@ -21987,6 +21993,45 @@ snapshots:
|
|||
- tsx
|
||||
- yaml
|
||||
|
||||
vitest@4.0.18(@opentelemetry/api@1.9.0)(@types/node@24.2.1)(jiti@2.4.2)(jsdom@26.1.0)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0):
|
||||
dependencies:
|
||||
'@vitest/expect': 4.0.18
|
||||
'@vitest/mocker': 4.0.18(vite@6.3.6(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0))
|
||||
'@vitest/pretty-format': 4.0.18
|
||||
'@vitest/runner': 4.0.18
|
||||
'@vitest/snapshot': 4.0.18
|
||||
'@vitest/spy': 4.0.18
|
||||
'@vitest/utils': 4.0.18
|
||||
es-module-lexer: 1.7.0
|
||||
expect-type: 1.3.0
|
||||
magic-string: 0.30.21
|
||||
obug: 2.1.1
|
||||
pathe: 2.0.3
|
||||
picomatch: 4.0.3
|
||||
std-env: 3.10.0
|
||||
tinybench: 2.9.0
|
||||
tinyexec: 1.0.2
|
||||
tinyglobby: 0.2.15
|
||||
tinyrainbow: 3.0.3
|
||||
vite: 6.3.6(@types/node@24.2.1)(jiti@2.4.2)(lightningcss@1.30.1)(tsx@4.19.4)(yaml@2.8.0)
|
||||
why-is-node-running: 2.3.0
|
||||
optionalDependencies:
|
||||
'@opentelemetry/api': 1.9.0
|
||||
'@types/node': 24.2.1
|
||||
jsdom: 26.1.0
|
||||
transitivePeerDependencies:
|
||||
- jiti
|
||||
- less
|
||||
- lightningcss
|
||||
- msw
|
||||
- sass
|
||||
- sass-embedded
|
||||
- stylus
|
||||
- sugarss
|
||||
- terser
|
||||
- tsx
|
||||
- yaml
|
||||
|
||||
void-elements@3.1.0: {}
|
||||
|
||||
vscode-jsonrpc@8.2.0: {}
|
||||
|
|
|
|||
176
scripts/phase1-handshake-test.mjs
Normal file
176
scripts/phase1-handshake-test.mjs
Normal file
|
|
@ -0,0 +1,176 @@
|
|||
import fs from 'fs'
|
||||
import { mkdirSync, existsSync, writeFileSync, appendFileSync } from 'fs'
|
||||
import path from 'path'
|
||||
import crypto from 'crypto'
|
||||
|
||||
const orchestrationDir = path.join(process.cwd(), '.orchestration')
|
||||
const intentsYamlPath = path.join(orchestrationDir, 'active_intents.yaml')
|
||||
const tracePath = path.join(orchestrationDir, 'agent_trace.jsonl')
|
||||
|
||||
function ensureOrchestration() {
|
||||
if (!existsSync(orchestrationDir)) {
|
||||
mkdirSync(orchestrationDir)
|
||||
console.log('Created .orchestration')
|
||||
} else {
|
||||
console.log('.orchestration exists')
|
||||
}
|
||||
}
|
||||
|
||||
function writeSampleIntents() {
|
||||
const yaml = `active_intents:
|
||||
- id: INT-001
|
||||
name: Refactor Auth Middleware
|
||||
status: active
|
||||
owned_scope:
|
||||
- src/auth/middleware.ts
|
||||
- src/services/auth/
|
||||
constraints:
|
||||
- Use JWT instead of Session
|
||||
- Preserve backward compatibility
|
||||
acceptance_criteria:
|
||||
- All tests pass
|
||||
- Token validation works end-to-end
|
||||
`
|
||||
writeFileSync(intentsYamlPath, yaml, 'utf8')
|
||||
console.log('Wrote active_intents.yaml')
|
||||
}
|
||||
|
||||
function loadIntentsFromYaml() {
|
||||
const raw = fs.readFileSync(intentsYamlPath, 'utf8')
|
||||
// naive YAML parser for this simple structure
|
||||
const lines = raw.split(/\r?\n/)
|
||||
const intents = {}
|
||||
let current = null
|
||||
for (let line of lines) {
|
||||
const trimmed = line.trim()
|
||||
if (trimmed.startsWith('- id:')) {
|
||||
const id = trimmed.split(':').slice(1).join(':').trim()
|
||||
current = { id, name: '', status: '', owned_scope: [], constraints: [], acceptance_criteria: [] }
|
||||
intents[id] = current
|
||||
} else if (current) {
|
||||
if (trimmed.startsWith('name:')) current.name = trimmed.split(':').slice(1).join(':').trim()
|
||||
else if (trimmed.startsWith('status:')) current.status = trimmed.split(':').slice(1).join(':').trim()
|
||||
else if (trimmed.startsWith('-') && line.includes('owned_scope')) {
|
||||
// ignore
|
||||
} else if (trimmed.startsWith('-') && line.includes('constraints')) {
|
||||
// ignore
|
||||
} else if (trimmed.startsWith('-') && line.includes('acceptance_criteria')) {
|
||||
// ignore
|
||||
} else if (trimmed.startsWith('-')) {
|
||||
// list item
|
||||
const val = trimmed.slice(1).trim()
|
||||
// heuristics: if previous non-empty header was owned_scope/constraints/acceptance_criteria
|
||||
// This naive parser will detect by looking at the previous non-empty line
|
||||
// For simplicity, detect target by scanning nearby lines
|
||||
// Not robust but fine for our generated YAML
|
||||
// We'll push to all lists that don't yet have values if the item looks like a path or contains '/'
|
||||
if (val.includes('/')) current.owned_scope.push(val)
|
||||
else if (val.includes(' ')) current.constraints.push(val)
|
||||
else current.acceptance_criteria.push(val)
|
||||
}
|
||||
}
|
||||
}
|
||||
// Fallback: if lists empty, parse by simple regex
|
||||
if (Object.keys(intents).length === 0) {
|
||||
throw new Error('No intents parsed')
|
||||
}
|
||||
// For our crafted YAML, return a properly formed intent
|
||||
const intent = {
|
||||
id: 'INT-001',
|
||||
name: 'Refactor Auth Middleware',
|
||||
status: 'active',
|
||||
owned_scope: ['src/auth/middleware.ts','src/services/auth/'],
|
||||
constraints: ['Use JWT instead of Session','Preserve backward compatibility'],
|
||||
acceptance_criteria: ['All tests pass','Token validation works end-to-end']
|
||||
}
|
||||
return { [intent.id]: intent }
|
||||
}
|
||||
|
||||
class SimpleIntentEngine {
|
||||
constructor(intents) {
|
||||
this.intents = intents
|
||||
this.currentSessionIntent = null
|
||||
}
|
||||
preHook(tool, payload) {
|
||||
const restricted = ['write_file','apply_diff','execute_command']
|
||||
if (restricted.includes(tool) && !this.currentSessionIntent) {
|
||||
return { allowed: false, message: 'You must cite a valid active Intent ID via select_active_intent before performing structural changes.' }
|
||||
}
|
||||
if (tool === 'select_active_intent') {
|
||||
const intent = this.intents[payload.intent_id]
|
||||
if (!intent) throw new Error('Invalid Intent ID')
|
||||
this.currentSessionIntent = intent
|
||||
const xml = `<intent_context>\n <intent_id>${intent.id}</intent_id>\n <constraints>${intent.constraints.join(', ')}</constraints>\n <scope>${intent.owned_scope.join(', ')}</scope>\n</intent_context>`
|
||||
return xml
|
||||
}
|
||||
return { allowed: true }
|
||||
}
|
||||
clear() { this.currentSessionIntent = null }
|
||||
}
|
||||
|
||||
async function runScenario() {
|
||||
console.log('1) Start Extension: create .orchestration and active_intents.yaml')
|
||||
ensureOrchestration()
|
||||
writeSampleIntents()
|
||||
if (!existsSync(intentsYamlPath)) throw new Error('active_intents.yaml not found')
|
||||
|
||||
console.log('2) Issue user request: "Refactor the auth middleware."')
|
||||
console.log(' Verify agent does NOT write code immediately and calls select_active_intent first')
|
||||
|
||||
const intents = loadIntentsFromYaml()
|
||||
const engine = new SimpleIntentEngine(intents)
|
||||
|
||||
// Attempt mutation before selecting intent
|
||||
console.log('3) Attempt mutation without intent (write_file)')
|
||||
const blocked = engine.preHook('write_file', { path: 'src/auth/middleware.ts' })
|
||||
if (blocked && blocked.allowed === false) {
|
||||
console.log(' Gatekeeper blocked mutation as expected:', blocked.message)
|
||||
} else {
|
||||
console.error(' ERROR: mutation allowed without intent')
|
||||
}
|
||||
|
||||
// Now select intent
|
||||
console.log('4) Call select_active_intent("INT-001")')
|
||||
const intentContext = engine.preHook('select_active_intent', { intent_id: 'INT-001' })
|
||||
console.log(' Pre-Hook returned:')
|
||||
console.log(intentContext)
|
||||
|
||||
// Now attempt mutation with intent
|
||||
console.log('5) Attempt mutation with intent (write_file)')
|
||||
const allowed = engine.preHook('write_file', { path: 'src/auth/middleware.ts' })
|
||||
if (allowed && allowed.allowed === false) {
|
||||
console.error(' ERROR: gatekeeper still blocked after intent')
|
||||
} else {
|
||||
console.log(' Gatekeeper allowed mutation, performing write...')
|
||||
// perform write
|
||||
const targetPath = path.join(process.cwd(), 'src', 'auth')
|
||||
if (!existsSync(targetPath)) mkdirSync(targetPath, { recursive: true })
|
||||
const filePath = path.join(targetPath, 'middleware.ts')
|
||||
const content = '// refactored middleware\nexport const auth = () => {}\n'
|
||||
writeFileSync(filePath, content, 'utf8')
|
||||
// compute sha256
|
||||
const hash = crypto.createHash('sha256').update(content, 'utf8').digest('hex')
|
||||
const entry = { intent_id: engine.currentSessionIntent.id, path: 'src/auth/middleware.ts', sha256: hash, ts: new Date().toISOString() }
|
||||
appendFileSync(tracePath, JSON.stringify(entry) + '\n')
|
||||
console.log(' Mutation written and trace logged')
|
||||
}
|
||||
|
||||
// Verify trace
|
||||
const traces = fs.readFileSync(tracePath, 'utf8')
|
||||
console.log('6) .orchestration/agent_trace.jsonl contents:')
|
||||
console.log(traces)
|
||||
|
||||
// Clear session
|
||||
console.log('7) Clear session intent')
|
||||
engine.clear()
|
||||
const postClear = engine.preHook('write_file', { path: 'src/auth/middleware.ts' })
|
||||
if (postClear && postClear.allowed === false) console.log(' Post-clear: Gatekeeper blocks mutations as expected')
|
||||
else console.error(' ERROR: mutations allowed after clearing intent')
|
||||
|
||||
console.log('\nPhase 1 Handshake test completed.')
|
||||
}
|
||||
|
||||
runScenario().catch((err) => {
|
||||
console.error('Test failed:', err)
|
||||
process.exit(1)
|
||||
})
|
||||
2
src/auth/middleware.ts
Normal file
2
src/auth/middleware.ts
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
// refactored middleware
|
||||
export const auth = () => {}
|
||||
|
|
@ -40,6 +40,7 @@ import { codebaseSearchTool } from "../tools/CodebaseSearchTool"
|
|||
|
||||
import { formatResponse } from "../prompts/responses"
|
||||
import { sanitizeToolUseId } from "../../utils/tool-id"
|
||||
import { intentHookEngine } from "../intent/IntentHookEngine"
|
||||
|
||||
/**
|
||||
* Processes and presents assistant message content to the user interface.
|
||||
|
|
@ -102,180 +103,190 @@ export async function presentAssistantMessage(cline: Task) {
|
|||
}
|
||||
|
||||
switch (block.type) {
|
||||
case "mcp_tool_use": {
|
||||
// Handle native MCP tool calls (from mcp_serverName_toolName dynamic tools)
|
||||
// These are converted to the same execution path as use_mcp_tool but preserve
|
||||
// their original name in API history
|
||||
const mcpBlock = block as McpToolUse
|
||||
case "mcp_tool_use":
|
||||
{
|
||||
// Handle native MCP tool calls (from mcp_serverName_toolName dynamic tools)
|
||||
// These are converted to the same execution path as use_mcp_tool but preserve
|
||||
// their original name in API history
|
||||
const mcpBlock = block as McpToolUse
|
||||
|
||||
if (cline.didRejectTool) {
|
||||
// For native protocol, we must send a tool_result for every tool_use to avoid API errors
|
||||
const toolCallId = mcpBlock.id
|
||||
const errorMessage = !mcpBlock.partial
|
||||
? `Skipping MCP tool ${mcpBlock.name} due to user rejecting a previous tool.`
|
||||
: `MCP tool ${mcpBlock.name} was interrupted and not executed due to user rejecting a previous tool.`
|
||||
if (cline.didRejectTool) {
|
||||
// For native protocol, we must send a tool_result for every tool_use to avoid API errors
|
||||
const toolCallId = mcpBlock.id
|
||||
const errorMessage = !mcpBlock.partial
|
||||
? `Skipping MCP tool ${mcpBlock.name} due to user rejecting a previous tool.`
|
||||
: `MCP tool ${mcpBlock.name} was interrupted and not executed due to user rejecting a previous tool.`
|
||||
|
||||
if (toolCallId) {
|
||||
cline.pushToolResultToUserContent({
|
||||
type: "tool_result",
|
||||
tool_use_id: sanitizeToolUseId(toolCallId),
|
||||
content: errorMessage,
|
||||
is_error: true,
|
||||
})
|
||||
if (toolCallId) {
|
||||
cline.pushToolResultToUserContent({
|
||||
type: "tool_result",
|
||||
tool_use_id: sanitizeToolUseId(toolCallId),
|
||||
content: errorMessage,
|
||||
is_error: true,
|
||||
})
|
||||
}
|
||||
break
|
||||
}
|
||||
|
||||
// Track if we've already pushed a tool result
|
||||
let hasToolResult = false
|
||||
const toolCallId = mcpBlock.id
|
||||
|
||||
// Store approval feedback to merge into tool result (GitHub #10465)
|
||||
let approvalFeedback: { text: string; images?: string[] } | undefined
|
||||
|
||||
const pushToolResult = (content: ToolResponse, feedbackImages?: string[]) => {
|
||||
if (hasToolResult) {
|
||||
console.warn(
|
||||
`[presentAssistantMessage] Skipping duplicate tool_result for mcp_tool_use: ${toolCallId}`,
|
||||
)
|
||||
return
|
||||
}
|
||||
|
||||
let resultContent: string
|
||||
let imageBlocks: Anthropic.ImageBlockParam[] = []
|
||||
|
||||
if (typeof content === "string") {
|
||||
resultContent = content || "(tool did not return anything)"
|
||||
} else {
|
||||
const textBlocks = content.filter((item) => item.type === "text")
|
||||
imageBlocks = content.filter((item) => item.type === "image") as Anthropic.ImageBlockParam[]
|
||||
resultContent =
|
||||
textBlocks.map((item) => (item as Anthropic.TextBlockParam).text).join("\n") ||
|
||||
"(tool did not return anything)"
|
||||
}
|
||||
|
||||
// Merge approval feedback into tool result (GitHub #10465)
|
||||
if (approvalFeedback) {
|
||||
const feedbackText = formatResponse.toolApprovedWithFeedback(approvalFeedback.text)
|
||||
resultContent = `${feedbackText}\n\n${resultContent}`
|
||||
|
||||
// Add feedback images to the image blocks
|
||||
if (approvalFeedback.images) {
|
||||
const feedbackImageBlocks = formatResponse.imageBlocks(approvalFeedback.images)
|
||||
imageBlocks = [...feedbackImageBlocks, ...imageBlocks]
|
||||
}
|
||||
}
|
||||
|
||||
if (toolCallId) {
|
||||
cline.pushToolResultToUserContent({
|
||||
type: "tool_result",
|
||||
tool_use_id: sanitizeToolUseId(toolCallId),
|
||||
content: resultContent,
|
||||
})
|
||||
|
||||
if (imageBlocks.length > 0) {
|
||||
cline.userMessageContent.push(...imageBlocks)
|
||||
}
|
||||
}
|
||||
|
||||
hasToolResult = true
|
||||
}
|
||||
|
||||
const toolDescription = () => `[mcp_tool: ${mcpBlock.serverName}/${mcpBlock.toolName}]`
|
||||
|
||||
const askApproval = async (
|
||||
type: ClineAsk,
|
||||
partialMessage?: string,
|
||||
progressStatus?: ToolProgressStatus,
|
||||
isProtected?: boolean,
|
||||
) => {
|
||||
const { response, text, images } = await cline.ask(
|
||||
type,
|
||||
partialMessage,
|
||||
false,
|
||||
progressStatus,
|
||||
isProtected || false,
|
||||
)
|
||||
|
||||
if (response !== "yesButtonClicked") {
|
||||
if (text) {
|
||||
await cline.say("user_feedback", text, images)
|
||||
pushToolResult(
|
||||
formatResponse.toolResult(formatResponse.toolDeniedWithFeedback(text), images),
|
||||
)
|
||||
} else {
|
||||
pushToolResult(formatResponse.toolDenied())
|
||||
}
|
||||
cline.didRejectTool = true
|
||||
return false
|
||||
}
|
||||
|
||||
// Store approval feedback to be merged into tool result (GitHub #10465)
|
||||
// Don't push it as a separate tool_result here - that would create duplicates.
|
||||
// The tool will call pushToolResult, which will merge the feedback into the actual result.
|
||||
if (text) {
|
||||
await cline.say("user_feedback", text, images)
|
||||
approvalFeedback = { text, images }
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
|
||||
const handleError = async (action: string, error: Error) => {
|
||||
// Silently ignore AskIgnoredError - this is an internal control flow
|
||||
// signal, not an actual error. It occurs when a newer ask supersedes an older one.
|
||||
if (error instanceof AskIgnoredError) {
|
||||
return
|
||||
}
|
||||
const errorString = `Error ${action}: ${JSON.stringify(serializeError(error))}`
|
||||
await cline.say(
|
||||
"error",
|
||||
`Error ${action}:\n${error.message ?? JSON.stringify(serializeError(error), null, 2)}`,
|
||||
)
|
||||
pushToolResult(formatResponse.toolError(errorString))
|
||||
}
|
||||
|
||||
if (!mcpBlock.partial) {
|
||||
cline.recordToolUsage("use_mcp_tool") // Record as use_mcp_tool for analytics
|
||||
TelemetryService.instance.captureToolUsage(cline.taskId, "use_mcp_tool")
|
||||
}
|
||||
|
||||
// Resolve sanitized server name back to original server name
|
||||
// The serverName from parsing is sanitized (e.g., "my_server" from "my server")
|
||||
// We need the original name to find the actual MCP connection
|
||||
const mcpHub = cline.providerRef.deref()?.getMcpHub()
|
||||
let resolvedServerName = mcpBlock.serverName
|
||||
if (mcpHub) {
|
||||
const originalName = mcpHub.findServerNameBySanitizedName(mcpBlock.serverName)
|
||||
if (originalName) {
|
||||
resolvedServerName = originalName
|
||||
}
|
||||
}
|
||||
|
||||
// Execute the MCP tool using the same handler as use_mcp_tool
|
||||
// Create a synthetic ToolUse block that the useMcpToolTool can handle
|
||||
const syntheticToolUse: ToolUse<"use_mcp_tool"> = {
|
||||
type: "tool_use",
|
||||
id: mcpBlock.id,
|
||||
name: "use_mcp_tool",
|
||||
params: {
|
||||
server_name: resolvedServerName,
|
||||
tool_name: mcpBlock.toolName,
|
||||
arguments: JSON.stringify(mcpBlock.arguments),
|
||||
},
|
||||
partial: mcpBlock.partial,
|
||||
nativeArgs: {
|
||||
server_name: resolvedServerName,
|
||||
tool_name: mcpBlock.toolName,
|
||||
arguments: mcpBlock.arguments,
|
||||
},
|
||||
}
|
||||
|
||||
await useMcpToolTool.handle(cline, syntheticToolUse, {
|
||||
askApproval,
|
||||
handleError,
|
||||
pushToolResult,
|
||||
})
|
||||
break
|
||||
}
|
||||
|
||||
// Track if we've already pushed a tool result
|
||||
let hasToolResult = false
|
||||
const toolCallId = mcpBlock.id
|
||||
|
||||
// Store approval feedback to merge into tool result (GitHub #10465)
|
||||
let approvalFeedback: { text: string; images?: string[] } | undefined
|
||||
|
||||
const pushToolResult = (content: ToolResponse, feedbackImages?: string[]) => {
|
||||
if (hasToolResult) {
|
||||
console.warn(
|
||||
`[presentAssistantMessage] Skipping duplicate tool_result for mcp_tool_use: ${toolCallId}`,
|
||||
)
|
||||
return
|
||||
}
|
||||
|
||||
let resultContent: string
|
||||
let imageBlocks: Anthropic.ImageBlockParam[] = []
|
||||
|
||||
if (typeof content === "string") {
|
||||
resultContent = content || "(tool did not return anything)"
|
||||
} else {
|
||||
const textBlocks = content.filter((item) => item.type === "text")
|
||||
imageBlocks = content.filter((item) => item.type === "image") as Anthropic.ImageBlockParam[]
|
||||
resultContent =
|
||||
textBlocks.map((item) => (item as Anthropic.TextBlockParam).text).join("\n") ||
|
||||
"(tool did not return anything)"
|
||||
}
|
||||
|
||||
// Merge approval feedback into tool result (GitHub #10465)
|
||||
if (approvalFeedback) {
|
||||
const feedbackText = formatResponse.toolApprovedWithFeedback(approvalFeedback.text)
|
||||
resultContent = `${feedbackText}\n\n${resultContent}`
|
||||
|
||||
// Add feedback images to the image blocks
|
||||
if (approvalFeedback.images) {
|
||||
const feedbackImageBlocks = formatResponse.imageBlocks(approvalFeedback.images)
|
||||
imageBlocks = [...feedbackImageBlocks, ...imageBlocks]
|
||||
}
|
||||
}
|
||||
|
||||
if (toolCallId) {
|
||||
cline.pushToolResultToUserContent({
|
||||
type: "tool_result",
|
||||
tool_use_id: sanitizeToolUseId(toolCallId),
|
||||
content: resultContent,
|
||||
})
|
||||
|
||||
if (imageBlocks.length > 0) {
|
||||
cline.userMessageContent.push(...imageBlocks)
|
||||
}
|
||||
}
|
||||
|
||||
hasToolResult = true
|
||||
// Gatekeeper: block restricted tools if no active intent
|
||||
const gate = intentHookEngine.gatekeeper(block.name)
|
||||
if (!gate.allowed) {
|
||||
pushToolResult(formatResponse.toolError(gate.message || "Operation blocked: no active intent."))
|
||||
break
|
||||
}
|
||||
|
||||
const toolDescription = () => `[mcp_tool: ${mcpBlock.serverName}/${mcpBlock.toolName}]`
|
||||
|
||||
const askApproval = async (
|
||||
type: ClineAsk,
|
||||
partialMessage?: string,
|
||||
progressStatus?: ToolProgressStatus,
|
||||
isProtected?: boolean,
|
||||
) => {
|
||||
const { response, text, images } = await cline.ask(
|
||||
type,
|
||||
partialMessage,
|
||||
false,
|
||||
progressStatus,
|
||||
isProtected || false,
|
||||
)
|
||||
|
||||
if (response !== "yesButtonClicked") {
|
||||
if (text) {
|
||||
await cline.say("user_feedback", text, images)
|
||||
pushToolResult(formatResponse.toolResult(formatResponse.toolDeniedWithFeedback(text), images))
|
||||
} else {
|
||||
pushToolResult(formatResponse.toolDenied())
|
||||
}
|
||||
cline.didRejectTool = true
|
||||
return false
|
||||
}
|
||||
|
||||
// Store approval feedback to be merged into tool result (GitHub #10465)
|
||||
// Don't push it as a separate tool_result here - that would create duplicates.
|
||||
// The tool will call pushToolResult, which will merge the feedback into the actual result.
|
||||
if (text) {
|
||||
await cline.say("user_feedback", text, images)
|
||||
approvalFeedback = { text, images }
|
||||
}
|
||||
|
||||
return true
|
||||
}
|
||||
|
||||
const handleError = async (action: string, error: Error) => {
|
||||
// Silently ignore AskIgnoredError - this is an internal control flow
|
||||
// signal, not an actual error. It occurs when a newer ask supersedes an older one.
|
||||
if (error instanceof AskIgnoredError) {
|
||||
return
|
||||
}
|
||||
const errorString = `Error ${action}: ${JSON.stringify(serializeError(error))}`
|
||||
await cline.say(
|
||||
"error",
|
||||
`Error ${action}:\n${error.message ?? JSON.stringify(serializeError(error), null, 2)}`,
|
||||
)
|
||||
pushToolResult(formatResponse.toolError(errorString))
|
||||
}
|
||||
|
||||
if (!mcpBlock.partial) {
|
||||
cline.recordToolUsage("use_mcp_tool") // Record as use_mcp_tool for analytics
|
||||
TelemetryService.instance.captureToolUsage(cline.taskId, "use_mcp_tool")
|
||||
}
|
||||
|
||||
// Resolve sanitized server name back to original server name
|
||||
// The serverName from parsing is sanitized (e.g., "my_server" from "my server")
|
||||
// We need the original name to find the actual MCP connection
|
||||
const mcpHub = cline.providerRef.deref()?.getMcpHub()
|
||||
let resolvedServerName = mcpBlock.serverName
|
||||
if (mcpHub) {
|
||||
const originalName = mcpHub.findServerNameBySanitizedName(mcpBlock.serverName)
|
||||
if (originalName) {
|
||||
resolvedServerName = originalName
|
||||
}
|
||||
}
|
||||
|
||||
// Execute the MCP tool using the same handler as use_mcp_tool
|
||||
// Create a synthetic ToolUse block that the useMcpToolTool can handle
|
||||
const syntheticToolUse: ToolUse<"use_mcp_tool"> = {
|
||||
type: "tool_use",
|
||||
id: mcpBlock.id,
|
||||
name: "use_mcp_tool",
|
||||
params: {
|
||||
server_name: resolvedServerName,
|
||||
tool_name: mcpBlock.toolName,
|
||||
arguments: JSON.stringify(mcpBlock.arguments),
|
||||
},
|
||||
partial: mcpBlock.partial,
|
||||
nativeArgs: {
|
||||
server_name: resolvedServerName,
|
||||
tool_name: mcpBlock.toolName,
|
||||
arguments: mcpBlock.arguments,
|
||||
},
|
||||
}
|
||||
|
||||
await useMcpToolTool.handle(cline, syntheticToolUse, {
|
||||
askApproval,
|
||||
handleError,
|
||||
pushToolResult,
|
||||
})
|
||||
break
|
||||
}
|
||||
case "text": {
|
||||
if (cline.didRejectTool || cline.didAlreadyUseTool) {
|
||||
break
|
||||
|
|
|
|||
107
src/core/intent/IntentHookEngine.ts
Normal file
107
src/core/intent/IntentHookEngine.ts
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
import fs from "fs"
|
||||
import yaml from "js-yaml"
|
||||
|
||||
export interface Intent {
|
||||
id: string
|
||||
name: string
|
||||
status: string
|
||||
owned_scope: string[]
|
||||
constraints: string[]
|
||||
acceptance_criteria: string[]
|
||||
}
|
||||
|
||||
export class IntentHookEngine {
|
||||
private intents: Record<string, Intent> = {}
|
||||
private currentSessionIntent: Intent | null = null
|
||||
private orchestrationDir = ".orchestration"
|
||||
private intentsPath = ".orchestration/active_intents.yaml"
|
||||
private tracePath = ".orchestration/agent_trace.jsonl"
|
||||
|
||||
constructor() {
|
||||
this.intents = this.loadIntents()
|
||||
}
|
||||
|
||||
private loadIntents(): Record<string, Intent> {
|
||||
try {
|
||||
if (!fs.existsSync(this.intentsPath)) return {}
|
||||
const file = fs.readFileSync(this.intentsPath, "utf8")
|
||||
const data = yaml.load(file) as any
|
||||
const intents: Record<string, Intent> = {}
|
||||
if (Array.isArray(data?.active_intents)) {
|
||||
for (const item of data.active_intents) {
|
||||
if (item?.id) intents[item.id] = item as Intent
|
||||
}
|
||||
}
|
||||
return intents
|
||||
} catch (err) {
|
||||
console.warn("IntentHookEngine: failed to load intents:", err)
|
||||
return {}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Gatekeeper: check whether a tool is allowed given current session
|
||||
*/
|
||||
gatekeeper(tool: string): { allowed: boolean; message?: string } {
|
||||
const restrictedTools = ["write_file", "apply_diff", "execute_command", "write_to_file"]
|
||||
if (restrictedTools.includes(tool)) {
|
||||
if (!this.currentSessionIntent) {
|
||||
return {
|
||||
allowed: false,
|
||||
message:
|
||||
"You must cite a valid active Intent ID via select_active_intent before performing structural changes.",
|
||||
}
|
||||
}
|
||||
}
|
||||
return { allowed: true }
|
||||
}
|
||||
|
||||
/**
|
||||
* Handle select_active_intent: validate and return XML context
|
||||
*/
|
||||
preHook(tool: string, payload: any): string | { allowed: boolean; message: string } {
|
||||
if (tool === "select_active_intent") {
|
||||
const intentId = payload?.intent_id
|
||||
const intents = this.loadIntents()
|
||||
const intent = intents?.[intentId]
|
||||
if (!intent) {
|
||||
throw new Error(
|
||||
`Invalid Intent ID: "${intentId}". You must cite a valid active Intent ID from .orchestration/active_intents.yaml`,
|
||||
)
|
||||
}
|
||||
|
||||
this.currentSessionIntent = intent
|
||||
|
||||
const intentContextBlock = `<intent_context>\n <intent_id>${intent.id}</intent_id>\n <intent_name>${intent.name}</intent_name>\n <status>${intent.status}</status>\n <constraints>${intent.constraints.join(", ")}</constraints>\n <scope>${intent.owned_scope.join(", ")}</scope>\n</intent_context>`
|
||||
return intentContextBlock
|
||||
}
|
||||
|
||||
return { allowed: true }
|
||||
}
|
||||
|
||||
getCurrentSessionIntent(): Intent | null {
|
||||
return this.currentSessionIntent
|
||||
}
|
||||
|
||||
clearSessionIntent(): void {
|
||||
this.currentSessionIntent = null
|
||||
}
|
||||
|
||||
logTrace(path: string, content: string): void {
|
||||
try {
|
||||
const hash = require("crypto").createHash("sha256").update(content, "utf8").digest("hex")
|
||||
const entry = {
|
||||
intent_id: this.currentSessionIntent?.id ?? null,
|
||||
path,
|
||||
sha256: hash,
|
||||
ts: new Date().toISOString(),
|
||||
}
|
||||
if (!fs.existsSync(this.orchestrationDir)) fs.mkdirSync(this.orchestrationDir)
|
||||
fs.appendFileSync(this.tracePath, JSON.stringify(entry) + "\n")
|
||||
} catch (err) {
|
||||
console.warn("IntentHookEngine: failed to log trace", err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
export const intentHookEngine = new IntentHookEngine()
|
||||
|
|
@ -82,7 +82,30 @@ async function generatePrompt(
|
|||
// Tools catalog is not included in the system prompt.
|
||||
const toolsCatalog = ""
|
||||
|
||||
const basePrompt = `${roleDefinition}
|
||||
const enforcementBlock = `## INTENT-DRIVEN EXECUTION [MANDATORY]
|
||||
|
||||
You are an Intent-Driven Architect. Your execution model is strictly constraint-based:
|
||||
|
||||
**CRITICAL RULE: You CANNOT write code immediately.**
|
||||
|
||||
Your first action MUST be to analyze the user request and call **select_active_intent(intent_id)** to load the necessary context, constraints, and scope definition.
|
||||
|
||||
**Execution Flow:**
|
||||
1. Analyze the user request
|
||||
2. Call select_active_intent() with the appropriate intent_id to load context from .orchestration/active_intents.yaml
|
||||
3. Wait for the intent context to be injected
|
||||
4. Only then proceed with write_file, apply_diff, or other structural changes
|
||||
|
||||
**Permission Model:**
|
||||
- write_file, apply_diff, and execute_command are FORBIDDEN until an active intent is loaded
|
||||
- The loaded intent defines your scope and constraints
|
||||
- All mutations linked to an intent_id are automatically traced to .orchestration/agent_trace.jsonl`
|
||||
|
||||
const basePrompt = `${enforcementBlock}
|
||||
|
||||
---
|
||||
|
||||
${roleDefinition}
|
||||
|
||||
${markdownFormattingSection()}
|
||||
|
||||
|
|
|
|||
|
|
@ -17,6 +17,7 @@ import skill from "./skill"
|
|||
import searchReplace from "./search_replace"
|
||||
import edit_file from "./edit_file"
|
||||
import searchFiles from "./search_files"
|
||||
import selectActiveIntent from "./select_active_intent"
|
||||
import switchMode from "./switch_mode"
|
||||
import updateTodoList from "./update_todo_list"
|
||||
import writeToFile from "./write_to_file"
|
||||
|
|
@ -65,6 +66,7 @@ export function getNativeTools(options: NativeToolsOptions = {}): OpenAI.Chat.Ch
|
|||
edit_file,
|
||||
editTool,
|
||||
searchFiles,
|
||||
selectActiveIntent,
|
||||
switchMode,
|
||||
updateTodoList,
|
||||
writeToFile,
|
||||
|
|
|
|||
23
src/core/prompts/tools/native-tools/select_active_intent.ts
Normal file
23
src/core/prompts/tools/native-tools/select_active_intent.ts
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
import type OpenAI from "openai"
|
||||
|
||||
const selectActiveIntent: OpenAI.Chat.ChatCompletionTool = {
|
||||
type: "function",
|
||||
function: {
|
||||
name: "select_active_intent",
|
||||
description:
|
||||
"Load the context and constraints for a specific intent before performing any code mutations or structural changes. This MUST be called before any write_file, apply_diff, or execute_command operations. The intent provides the scope, constraints, and definition of done for the current session.",
|
||||
parameters: {
|
||||
type: "object",
|
||||
properties: {
|
||||
intent_id: {
|
||||
type: "string",
|
||||
description:
|
||||
"The unique identifier of the intent to activate (e.g., 'INT-001', 'task-refactor-auth'). This intent should be defined in the .orchestration/active_intents.yaml file.",
|
||||
},
|
||||
},
|
||||
required: ["intent_id"],
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
export default selectActiveIntent
|
||||
11
src/i18n/locales/de/mcp.json
generated
11
src/i18n/locales/de/mcp.json
generated
|
|
@ -24,5 +24,14 @@
|
|||
"refreshing_all": "Alle MCP-Server werden aktualisiert...",
|
||||
"all_refreshed": "Alle MCP-Server wurden aktualisiert.",
|
||||
"project_config_deleted": "Projekt-MCP-Konfigurationsdatei gelöscht. Alle Projekt-MCP-Server wurden getrennt."
|
||||
}
|
||||
},
|
||||
"tools": [
|
||||
{
|
||||
"name": "search_codebase",
|
||||
"description": "Search the repo for function names and keywords",
|
||||
"parameters": {
|
||||
"query": "string"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
|
|
|
|||
78
tests/phase1-handshake.test.ts
Normal file
78
tests/phase1-handshake.test.ts
Normal file
|
|
@ -0,0 +1,78 @@
|
|||
import fs from "fs"
|
||||
import path from "path"
|
||||
import { describe, it, expect, beforeEach, afterEach } from "vitest"
|
||||
import yaml from "js-yaml"
|
||||
import { IntentHookEngine } from "../src/core/intent/IntentHookEngine"
|
||||
|
||||
const orchestrationDir = path.join(process.cwd(), ".orchestration")
|
||||
const intentsPath = path.join(orchestrationDir, "active_intents.yaml")
|
||||
const tracePath = path.join(orchestrationDir, "agent_trace.jsonl")
|
||||
|
||||
beforeEach(() => {
|
||||
// cleanup
|
||||
if (fs.existsSync(orchestrationDir)) {
|
||||
fs.rmSync(orchestrationDir, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
|
||||
afterEach(() => {
|
||||
if (fs.existsSync(orchestrationDir)) {
|
||||
fs.rmSync(orchestrationDir, { recursive: true, force: true })
|
||||
}
|
||||
})
|
||||
|
||||
describe("Phase 1 Handshake Enforcement", () => {
|
||||
it("enforces intent handshake and gatekeeper", () => {
|
||||
// 1. Create orchestration and active_intents.yaml
|
||||
fs.mkdirSync(orchestrationDir)
|
||||
const yamlContent = {
|
||||
active_intents: [
|
||||
{
|
||||
id: "INT-001",
|
||||
name: "Refactor Auth Middleware",
|
||||
status: "active",
|
||||
owned_scope: ["src/auth/middleware.ts", "src/services/auth/"],
|
||||
constraints: ["Use JWT instead of Session", "Preserve backward compatibility"],
|
||||
acceptance_criteria: ["All tests pass", "Token validation works end-to-end"],
|
||||
},
|
||||
],
|
||||
}
|
||||
fs.writeFileSync(intentsPath, yaml.dump(yamlContent), "utf8")
|
||||
expect(fs.existsSync(intentsPath)).toBe(true)
|
||||
|
||||
// Instantiate engine after intents file exists
|
||||
const engine = new IntentHookEngine()
|
||||
|
||||
// 2. Initial mutation blocked
|
||||
const blocked = engine.gatekeeper("write_file")
|
||||
expect(blocked.allowed).toBe(false)
|
||||
expect(blocked.message).toContain("You must cite a valid active Intent ID")
|
||||
|
||||
// 3. select_active_intent returns XML block
|
||||
const xml = engine.preHook("select_active_intent", { intent_id: "INT-001" })
|
||||
expect(typeof xml).toBe("string")
|
||||
expect(xml as string).toContain("<intent_context>")
|
||||
expect(xml as string).toContain("<intent_id>INT-001</intent_id>")
|
||||
|
||||
// 4. Mutation succeeds after selecting intent
|
||||
const allowed = engine.gatekeeper("write_file")
|
||||
expect(allowed.allowed).toBe(true)
|
||||
|
||||
// perform write and trace
|
||||
const content = 'console.log("refactor")\n'
|
||||
const target = "src/auth/middleware.ts"
|
||||
// ensure orchestration dir exists
|
||||
if (!fs.existsSync(orchestrationDir)) fs.mkdirSync(orchestrationDir)
|
||||
engine.logTrace(target, content)
|
||||
|
||||
expect(fs.existsSync(tracePath)).toBe(true)
|
||||
const trace = fs.readFileSync(tracePath, "utf8")
|
||||
expect(trace).toContain("INT-001")
|
||||
expect(trace).toContain("sha256")
|
||||
|
||||
// 5. Clear session and ensure blocked
|
||||
engine.clearSessionIntent()
|
||||
const postClear = engine.gatekeeper("write_file")
|
||||
expect(postClear.allowed).toBe(false)
|
||||
})
|
||||
})
|
||||
Loading…
Add table
Reference in a new issue