@blockrun/franklin 3.33.0 → 3.34.1
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 +23 -2
- package/dist/agent/approvals.d.ts +47 -0
- package/dist/agent/approvals.js +66 -0
- package/dist/agent/commands.js +230 -7
- package/dist/agent/input-queue.d.ts +26 -0
- package/dist/agent/input-queue.js +65 -0
- package/dist/agent/loop.js +196 -3
- package/dist/agent/streaming-executor.d.ts +4 -0
- package/dist/agent/streaming-executor.js +52 -0
- package/dist/agent/tool-guard.d.ts +7 -0
- package/dist/agent/tool-guard.js +21 -0
- package/dist/agent/types.d.ts +26 -0
- package/dist/audit/approvals.d.ts +20 -0
- package/dist/audit/approvals.js +21 -0
- package/dist/commands/start.d.ts +10 -1
- package/dist/commands/start.js +53 -1
- package/dist/events/types.d.ts +38 -1
- package/dist/goal/engine.d.ts +39 -0
- package/dist/goal/engine.js +182 -0
- package/dist/goal/prompts.d.ts +16 -0
- package/dist/goal/prompts.js +206 -0
- package/dist/goal/runtime.d.ts +20 -0
- package/dist/goal/runtime.js +110 -0
- package/dist/goal/store.d.ts +22 -0
- package/dist/goal/store.js +79 -0
- package/dist/goal/types.d.ts +63 -0
- package/dist/goal/types.js +26 -0
- package/dist/hooks/loader.d.ts +19 -0
- package/dist/hooks/loader.js +115 -0
- package/dist/hooks/runner.d.ts +31 -0
- package/dist/hooks/runner.js +147 -0
- package/dist/hooks/types.d.ts +64 -0
- package/dist/hooks/types.js +35 -0
- package/dist/index.js +5 -1
- package/dist/memory/capture.d.ts +40 -0
- package/dist/memory/capture.js +95 -0
- package/dist/memory/dream.d.ts +24 -0
- package/dist/memory/dream.js +147 -0
- package/dist/memory/indexer.d.ts +29 -0
- package/dist/memory/indexer.js +144 -0
- package/dist/memory/store.d.ts +50 -0
- package/dist/memory/store.js +163 -0
- package/dist/monitors/registry.d.ts +42 -0
- package/dist/monitors/registry.js +104 -0
- package/dist/panel/html.js +299 -0
- package/dist/panel/server.js +41 -0
- package/dist/scheduler/service.d.ts +24 -0
- package/dist/scheduler/service.js +44 -0
- package/dist/scheduler/store.d.ts +26 -0
- package/dist/scheduler/store.js +116 -0
- package/dist/scheduler/types.d.ts +36 -0
- package/dist/scheduler/types.js +31 -0
- package/dist/serve/agent-host.d.ts +63 -0
- package/dist/serve/agent-host.js +270 -0
- package/dist/serve/server.js +186 -3
- package/dist/session/live-registry.d.ts +32 -0
- package/dist/session/live-registry.js +83 -0
- package/dist/session/search.d.ts +6 -0
- package/dist/session/search.js +3 -3
- package/dist/session/storage.d.ts +6 -0
- package/dist/session/storage.js +6 -0
- package/dist/tools/goal.d.ts +7 -0
- package/dist/tools/goal.js +29 -0
- package/dist/tools/index.js +11 -0
- package/dist/tools/memory.js +14 -4
- package/dist/tools/monitor.d.ts +11 -0
- package/dist/tools/monitor.js +96 -0
- package/dist/tools/scheduler.d.ts +12 -0
- package/dist/tools/scheduler.js +79 -0
- package/dist/tools/spend-tools.d.ts +33 -0
- package/dist/tools/spend-tools.js +114 -0
- package/dist/tools/tool-categories.js +7 -0
- package/dist/tools/trade-plan.d.ts +11 -0
- package/dist/tools/trade-plan.js +137 -0
- package/dist/tools/trading-execute.js +24 -0
- package/dist/trading/trade-plan.d.ts +75 -0
- package/dist/trading/trade-plan.js +290 -0
- package/package.json +2 -2
package/dist/commands/start.js
CHANGED
|
@@ -4,7 +4,7 @@ import path from 'node:path';
|
|
|
4
4
|
import { getOrCreateWallet, getOrCreateSolanaWallet } from '@blockrun/llm';
|
|
5
5
|
import { BLOCKRUN_DIR, loadChain, API_URLS } from '../config.js';
|
|
6
6
|
import { retryFetchBalance } from './balance-retry.js';
|
|
7
|
-
import { flushStats, loadStats } from '../stats/tracker.js';
|
|
7
|
+
import { flushStats, loadStats, getLiveSpendUsd } from '../stats/tracker.js';
|
|
8
8
|
import { OPUS_PRICING } from '../pricing.js';
|
|
9
9
|
import { loadConfig } from './config.js';
|
|
10
10
|
import { printBanner } from '../banner.js';
|
|
@@ -374,6 +374,15 @@ export async function startCommand(options) {
|
|
|
374
374
|
? { maxSpendUsd: Number(options.maxSpend) }
|
|
375
375
|
: {}),
|
|
376
376
|
};
|
|
377
|
+
// Non-interactive runs get the headless approval policy: trades fail
|
|
378
|
+
// closed unless --approve-trades was granted, and even then only within
|
|
379
|
+
// the remaining --max-spend envelope. Interactive TUI overrides this
|
|
380
|
+
// below with a real prompt.
|
|
381
|
+
if (options.prompt || !process.stdin.isTTY) {
|
|
382
|
+
agentConfig.approvalPromptFn = createHeadlessApprovalFn(options.approveTrades === true, agentConfig.maxSpendUsd);
|
|
383
|
+
// A goal must never extend a bounded scripted run past its single prompt.
|
|
384
|
+
agentConfig.autoContinueGoals = false;
|
|
385
|
+
}
|
|
377
386
|
// Bootstrap learnings from existing CLAUDE.md on first run (async, non-blocking)
|
|
378
387
|
Promise.all([
|
|
379
388
|
import('../learnings/extractor.js'),
|
|
@@ -399,6 +408,34 @@ export async function startCommand(options) {
|
|
|
399
408
|
export function oneShotExitCodeForTurnReason(reason) {
|
|
400
409
|
return reason === 'completed' ? 0 : 1;
|
|
401
410
|
}
|
|
411
|
+
/**
|
|
412
|
+
* Headless approval policy. No human is present, so:
|
|
413
|
+
* - without --approve-trades: every trade plan is denied
|
|
414
|
+
* - with it: auto-approve only when the plan total fits what's left of the
|
|
415
|
+
* --max-spend envelope (no flag combination bypasses --max-spend)
|
|
416
|
+
*/
|
|
417
|
+
export function createHeadlessApprovalFn(approveTrades, maxSpendUsd) {
|
|
418
|
+
return async (req) => {
|
|
419
|
+
if (req.kind !== 'trade-plan') {
|
|
420
|
+
return { choice: 'deny', message: 'non-interactive run' };
|
|
421
|
+
}
|
|
422
|
+
if (!approveTrades) {
|
|
423
|
+
return { choice: 'deny', message: 'non-interactive run without --approve-trades' };
|
|
424
|
+
}
|
|
425
|
+
const plan = req.payload;
|
|
426
|
+
const total = typeof plan?.totalSpendUsd === 'number' ? plan.totalSpendUsd : Number.POSITIVE_INFINITY;
|
|
427
|
+
if (maxSpendUsd != null && maxSpendUsd > 0) {
|
|
428
|
+
const remaining = maxSpendUsd - getLiveSpendUsd();
|
|
429
|
+
if (total > remaining) {
|
|
430
|
+
return {
|
|
431
|
+
choice: 'deny',
|
|
432
|
+
message: `plan total $${total.toFixed(2)} exceeds remaining --max-spend envelope $${Math.max(0, remaining).toFixed(2)}`,
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
}
|
|
436
|
+
return { choice: 'approve', message: 'auto' };
|
|
437
|
+
};
|
|
438
|
+
}
|
|
402
439
|
async function runOneShot(agentConfig, prompt) {
|
|
403
440
|
let delivered = false;
|
|
404
441
|
let exitCode = 0;
|
|
@@ -482,6 +519,21 @@ async function runWithInkUI(agentConfig, model, workDir, version, walletInfo, on
|
|
|
482
519
|
// immediately and auto-denied every permission. Now y/n/a goes through useInput.
|
|
483
520
|
agentConfig.permissionPromptFn = (toolName, description) => ui.requestPermission(toolName, description);
|
|
484
521
|
agentConfig.onAskUser = (question, options) => ui.requestAskUser(question, options);
|
|
522
|
+
// Structured approvals (trade plans) render through the ask-user modal:
|
|
523
|
+
// the full plan card as the question, decision keywords as the options.
|
|
524
|
+
// A free-text reply that isn't a listed option is treated as a change
|
|
525
|
+
// request so the user can type feedback directly.
|
|
526
|
+
agentConfig.approvalPromptFn = async (req) => {
|
|
527
|
+
const answer = (await ui.requestAskUser(`${req.description}\n\nDecision?`, req.options)).trim();
|
|
528
|
+
const norm = answer.toLowerCase();
|
|
529
|
+
if (norm === 'approve' || norm === 'deny')
|
|
530
|
+
return { choice: norm };
|
|
531
|
+
if (norm === 'request changes') {
|
|
532
|
+
const msg = await ui.requestAskUser('What should change about this plan?');
|
|
533
|
+
return { choice: 'request changes', message: msg };
|
|
534
|
+
}
|
|
535
|
+
return { choice: 'request changes', message: answer };
|
|
536
|
+
};
|
|
485
537
|
agentConfig.onModelChange = (model) => ui.updateModel(model);
|
|
486
538
|
let activeSessionId = agentConfig.resumeSessionId;
|
|
487
539
|
agentConfig.onSessionStart = (sessionId) => { activeSessionId = sessionId; };
|
package/dist/events/types.d.ts
CHANGED
|
@@ -45,5 +45,42 @@ export interface BudgetExceededEvent extends BaseEvent {
|
|
|
45
45
|
blockedAction: string;
|
|
46
46
|
};
|
|
47
47
|
}
|
|
48
|
-
export type
|
|
48
|
+
export type AgentRunState = 'working' | 'idle' | 'needs-input' | 'completed' | 'failed';
|
|
49
|
+
export interface AgentStateEvent extends BaseEvent {
|
|
50
|
+
type: 'agent.state';
|
|
51
|
+
data: {
|
|
52
|
+
sessionId: string;
|
|
53
|
+
state: AgentRunState;
|
|
54
|
+
label: string;
|
|
55
|
+
model: string;
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
export interface AgentTurnEvent extends BaseEvent {
|
|
59
|
+
type: 'agent.turn';
|
|
60
|
+
data: {
|
|
61
|
+
sessionId: string;
|
|
62
|
+
phase: 'start' | 'done';
|
|
63
|
+
reason?: string;
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
export interface ApprovalRequestedEvent extends BaseEvent {
|
|
67
|
+
type: 'approval.requested';
|
|
68
|
+
data: {
|
|
69
|
+
sessionId: string;
|
|
70
|
+
requestId: string;
|
|
71
|
+
kind: string;
|
|
72
|
+
title: string;
|
|
73
|
+
options: string[];
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
export interface ApprovalResolvedEvent extends BaseEvent {
|
|
77
|
+
type: 'approval.resolved';
|
|
78
|
+
data: {
|
|
79
|
+
sessionId: string;
|
|
80
|
+
requestId: string;
|
|
81
|
+
choice: string;
|
|
82
|
+
by: string;
|
|
83
|
+
};
|
|
84
|
+
}
|
|
85
|
+
export type FranklinEvent = SignalDetectedEvent | PostPublishedEvent | MentionReceivedEvent | BudgetExceededEvent | AgentStateEvent | AgentTurnEvent | ApprovalRequestedEvent | ApprovalResolvedEvent;
|
|
49
86
|
export declare function makeEvent<T extends FranklinEvent>(props: Omit<T, 'id' | 'ts'>): T;
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Goal-engine role runners: planner, adversarial verifier panel,
|
|
3
|
+
* strategist, summarizer. Role calls are ordinary model completions (all
|
|
4
|
+
* recorded via recordUsage so /cost and --max-spend see them); verifiers
|
|
5
|
+
* additionally run a bounded read-only tool loop so they can AUDIT the
|
|
6
|
+
* implementer's evidence rather than take its word.
|
|
7
|
+
*/
|
|
8
|
+
import { ModelClient } from '../agent/llm.js';
|
|
9
|
+
import type { CapabilityHandler } from '../agent/types.js';
|
|
10
|
+
import type { GoalKind, GoalState, VerifierVerdict } from './types.js';
|
|
11
|
+
export interface GoalEngineContext {
|
|
12
|
+
client: ModelClient;
|
|
13
|
+
model: string;
|
|
14
|
+
capabilities: CapabilityHandler[];
|
|
15
|
+
workingDir: string;
|
|
16
|
+
signal: AbortSignal;
|
|
17
|
+
onProgress?: (text: string) => void;
|
|
18
|
+
}
|
|
19
|
+
/** Lightweight kind detection — the plan template diverges per kind. */
|
|
20
|
+
export declare function detectGoalKind(objective: string): GoalKind;
|
|
21
|
+
export declare function runPlanner(ctx: GoalEngineContext, objective: string): Promise<{
|
|
22
|
+
kind: GoalKind;
|
|
23
|
+
planMd: string;
|
|
24
|
+
}>;
|
|
25
|
+
export declare function parseVerdict(text: string): VerifierVerdict | null;
|
|
26
|
+
export interface PanelOutcome {
|
|
27
|
+
refuted: boolean;
|
|
28
|
+
gaps: string[];
|
|
29
|
+
blocking: 'none' | 'contradiction' | 'unverifiable';
|
|
30
|
+
verdicts: VerifierVerdict[];
|
|
31
|
+
}
|
|
32
|
+
export declare function runVerifierPanel(ctx: GoalEngineContext, goal: GoalState, planMd: string, claimMessage: string): Promise<PanelOutcome>;
|
|
33
|
+
/** Whack-a-mole detector: the last three rounds all refuted with materially
|
|
34
|
+
* different gap sets (no shared gap between consecutive rounds). */
|
|
35
|
+
export declare function needsStrategist(goal: GoalState): boolean;
|
|
36
|
+
export declare function runStrategist(ctx: GoalEngineContext, goal: GoalState, planMd: string): Promise<string>;
|
|
37
|
+
export declare function runSummarizer(ctx: GoalEngineContext, goal: GoalState, planMd: string): Promise<string>;
|
|
38
|
+
/** First unchecked checklist item — the per-turn nudge. */
|
|
39
|
+
export declare function mineNextStep(planMd: string): string | undefined;
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Goal-engine role runners: planner, adversarial verifier panel,
|
|
3
|
+
* strategist, summarizer. Role calls are ordinary model completions (all
|
|
4
|
+
* recorded via recordUsage so /cost and --max-spend see them); verifiers
|
|
5
|
+
* additionally run a bounded read-only tool loop so they can AUDIT the
|
|
6
|
+
* implementer's evidence rather than take its word.
|
|
7
|
+
*/
|
|
8
|
+
import { recordUsage } from '../stats/tracker.js';
|
|
9
|
+
import { estimateCost } from '../pricing.js';
|
|
10
|
+
import { plannerPrompt, strategistPrompt, summarizerPrompt, verifierPrompt, VERIFIER_LENSES, } from './prompts.js';
|
|
11
|
+
import { goalVerifierCount } from './types.js';
|
|
12
|
+
/** Read-only surface for verifiers — no writes, no shell, no sub-agents, so
|
|
13
|
+
* panels can run unattended without hitting a permission prompt. */
|
|
14
|
+
const VERIFIER_TOOL_ALLOWLIST = new Set([
|
|
15
|
+
'Read', 'Grep', 'Glob',
|
|
16
|
+
'WebFetch', 'WebSearch',
|
|
17
|
+
'ExaSearch', 'ExaAnswer', 'ExaReadUrls',
|
|
18
|
+
'TradingMarket', 'TradingSignal', 'TradingPortfolio', 'TradingHistory',
|
|
19
|
+
'PredictionMarket', 'SurfMarket', 'Wallet',
|
|
20
|
+
]);
|
|
21
|
+
function record(model, usage) {
|
|
22
|
+
try {
|
|
23
|
+
recordUsage(model, usage.inputTokens, usage.outputTokens, estimateCost(model, usage.inputTokens, usage.outputTokens), 0);
|
|
24
|
+
}
|
|
25
|
+
catch { /* stats are best-effort */ }
|
|
26
|
+
}
|
|
27
|
+
async function completeText(ctx, prompt, maxTokens) {
|
|
28
|
+
const { content, usage } = await ctx.client.complete({
|
|
29
|
+
model: ctx.model,
|
|
30
|
+
messages: [{ role: 'user', content: prompt }],
|
|
31
|
+
max_tokens: maxTokens,
|
|
32
|
+
stream: true,
|
|
33
|
+
}, ctx.signal);
|
|
34
|
+
record(ctx.model, usage);
|
|
35
|
+
return content
|
|
36
|
+
.filter((p) => p.type === 'text')
|
|
37
|
+
.map(p => p.text)
|
|
38
|
+
.join('\n')
|
|
39
|
+
.trim();
|
|
40
|
+
}
|
|
41
|
+
// ─── Planner ───────────────────────────────────────────────────────────────
|
|
42
|
+
/** Lightweight kind detection — the plan template diverges per kind. */
|
|
43
|
+
export function detectGoalKind(objective) {
|
|
44
|
+
const text = objective.toLowerCase();
|
|
45
|
+
if (/\b(trade|trading|position|portfolio|swap|bet|long|short|rebalance|dca|stop.?loss|take.?profit|polymarket)\b/.test(text)) {
|
|
46
|
+
return 'trading';
|
|
47
|
+
}
|
|
48
|
+
if (/\b(research|compare|investigate|analy[sz]e|find out|survey|report|summar)\b/.test(text)) {
|
|
49
|
+
return 'research';
|
|
50
|
+
}
|
|
51
|
+
return 'general';
|
|
52
|
+
}
|
|
53
|
+
export async function runPlanner(ctx, objective) {
|
|
54
|
+
const kind = detectGoalKind(objective);
|
|
55
|
+
const planMd = await completeText(ctx, plannerPrompt(objective, kind), 4096);
|
|
56
|
+
return { kind, planMd };
|
|
57
|
+
}
|
|
58
|
+
// ─── Verifier panel ────────────────────────────────────────────────────────
|
|
59
|
+
export function parseVerdict(text) {
|
|
60
|
+
const lines = text.trim().split('\n');
|
|
61
|
+
for (let i = lines.length - 1; i >= 0; i--) {
|
|
62
|
+
const line = lines[i].trim();
|
|
63
|
+
const start = line.indexOf('{');
|
|
64
|
+
if (start === -1)
|
|
65
|
+
continue;
|
|
66
|
+
try {
|
|
67
|
+
const obj = JSON.parse(line.slice(start));
|
|
68
|
+
if (typeof obj?.refuted === 'boolean') {
|
|
69
|
+
return {
|
|
70
|
+
refuted: obj.refuted,
|
|
71
|
+
findings: Array.isArray(obj.findings) ? obj.findings.map(String).slice(0, 8) : [],
|
|
72
|
+
confidence: obj.confidence === 'low' || obj.confidence === 'high' ? obj.confidence : 'medium',
|
|
73
|
+
blocking: obj.blocking === 'contradiction' || obj.blocking === 'unverifiable' ? obj.blocking : 'none',
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
catch { /* keep scanning upward */ }
|
|
78
|
+
}
|
|
79
|
+
return null;
|
|
80
|
+
}
|
|
81
|
+
async function runSingleVerifier(ctx, goal, planMd, claimMessage, lens) {
|
|
82
|
+
const tools = ctx.capabilities.filter(c => VERIFIER_TOOL_ALLOWLIST.has(c.spec.name));
|
|
83
|
+
const toolDefs = tools.map(c => c.spec);
|
|
84
|
+
const toolMap = new Map(tools.map(c => [c.spec.name, c]));
|
|
85
|
+
const history = [
|
|
86
|
+
{ role: 'user', content: verifierPrompt(goal, planMd, claimMessage, lens) },
|
|
87
|
+
];
|
|
88
|
+
const deadline = Date.now() + 4 * 60 * 1000;
|
|
89
|
+
let finalText = '';
|
|
90
|
+
for (let turn = 0; turn < 12; turn++) {
|
|
91
|
+
if (Date.now() > deadline || ctx.signal.aborted)
|
|
92
|
+
break;
|
|
93
|
+
const { content, usage } = await ctx.client.complete({ model: ctx.model, messages: history, tools: toolDefs, max_tokens: 8192, stream: true }, ctx.signal);
|
|
94
|
+
record(ctx.model, usage);
|
|
95
|
+
history.push({ role: 'assistant', content });
|
|
96
|
+
const invocations = [];
|
|
97
|
+
for (const part of content) {
|
|
98
|
+
if (part.type === 'text')
|
|
99
|
+
finalText = part.text;
|
|
100
|
+
else if (part.type === 'tool_use')
|
|
101
|
+
invocations.push(part);
|
|
102
|
+
}
|
|
103
|
+
if (invocations.length === 0)
|
|
104
|
+
break;
|
|
105
|
+
const outcomes = [];
|
|
106
|
+
for (const inv of invocations) {
|
|
107
|
+
const handler = toolMap.get(inv.name);
|
|
108
|
+
let result;
|
|
109
|
+
try {
|
|
110
|
+
result = handler
|
|
111
|
+
? await handler.execute(inv.input, { workingDir: ctx.workingDir, abortSignal: ctx.signal })
|
|
112
|
+
: { output: `Tool ${inv.name} is not available to verifiers (read-only audit surface).`, isError: true };
|
|
113
|
+
}
|
|
114
|
+
catch (err) {
|
|
115
|
+
result = { output: `Error: ${err.message}`, isError: true };
|
|
116
|
+
}
|
|
117
|
+
outcomes.push({
|
|
118
|
+
type: 'tool_result',
|
|
119
|
+
tool_use_id: inv.id,
|
|
120
|
+
content: result.output.slice(0, 20_000),
|
|
121
|
+
is_error: result.isError,
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
history.push({ role: 'user', content: outcomes });
|
|
125
|
+
}
|
|
126
|
+
// Unparseable / no verdict = refuted (default-refute doctrine).
|
|
127
|
+
return (parseVerdict(finalText) ?? {
|
|
128
|
+
refuted: true,
|
|
129
|
+
findings: ['verifier produced no parseable verdict — treat as refuted and re-verify'],
|
|
130
|
+
confidence: 'low',
|
|
131
|
+
blocking: 'none',
|
|
132
|
+
});
|
|
133
|
+
}
|
|
134
|
+
export async function runVerifierPanel(ctx, goal, planMd, claimMessage) {
|
|
135
|
+
const n = goalVerifierCount();
|
|
136
|
+
const lenses = Array.from({ length: n }, (_, i) => VERIFIER_LENSES[i % VERIFIER_LENSES.length]);
|
|
137
|
+
ctx.onProgress?.(`goal verification: ${n} adversarial reviewers auditing the completion claim…`);
|
|
138
|
+
const verdicts = await Promise.all(lenses.map(lens => runSingleVerifier(ctx, goal, planMd, claimMessage, lens).catch(() => ({
|
|
139
|
+
refuted: true,
|
|
140
|
+
findings: ['verifier crashed — treat as refuted'],
|
|
141
|
+
confidence: 'low',
|
|
142
|
+
blocking: 'none',
|
|
143
|
+
}))));
|
|
144
|
+
const refutedCount = verdicts.filter(v => v.refuted).length;
|
|
145
|
+
const refuted = refutedCount * 2 > verdicts.length; // strict majority
|
|
146
|
+
const gaps = refuted
|
|
147
|
+
? [...new Set(verdicts.filter(v => v.refuted).flatMap(v => v.findings))].slice(0, 10)
|
|
148
|
+
: [];
|
|
149
|
+
const blocking = verdicts.find(v => v.refuted && v.blocking === 'contradiction')
|
|
150
|
+
? 'contradiction'
|
|
151
|
+
: verdicts.find(v => v.refuted && v.blocking === 'unverifiable')
|
|
152
|
+
? 'unverifiable'
|
|
153
|
+
: 'none';
|
|
154
|
+
return { refuted, gaps, blocking, verdicts };
|
|
155
|
+
}
|
|
156
|
+
// ─── Strategist & summarizer ───────────────────────────────────────────────
|
|
157
|
+
/** Whack-a-mole detector: the last three rounds all refuted with materially
|
|
158
|
+
* different gap sets (no shared gap between consecutive rounds). */
|
|
159
|
+
export function needsStrategist(goal) {
|
|
160
|
+
if (goal.strategistNote)
|
|
161
|
+
return false; // one structural intervention per goal
|
|
162
|
+
const last = goal.rounds.slice(-3);
|
|
163
|
+
if (last.length < 3 || !last.every(r => r.refuted))
|
|
164
|
+
return false;
|
|
165
|
+
for (let i = 1; i < last.length; i++) {
|
|
166
|
+
const prev = new Set(last[i - 1].gaps.map(g => g.toLowerCase()));
|
|
167
|
+
if (last[i].gaps.some(g => prev.has(g.toLowerCase())))
|
|
168
|
+
return false; // overlapping = converging
|
|
169
|
+
}
|
|
170
|
+
return true;
|
|
171
|
+
}
|
|
172
|
+
export async function runStrategist(ctx, goal, planMd) {
|
|
173
|
+
return completeText(ctx, strategistPrompt(goal, planMd), 512);
|
|
174
|
+
}
|
|
175
|
+
export async function runSummarizer(ctx, goal, planMd) {
|
|
176
|
+
return completeText(ctx, summarizerPrompt(goal, planMd), 512);
|
|
177
|
+
}
|
|
178
|
+
/** First unchecked checklist item — the per-turn nudge. */
|
|
179
|
+
export function mineNextStep(planMd) {
|
|
180
|
+
const m = planMd.match(/^- \[ \] (.+)$/m);
|
|
181
|
+
return m?.[1]?.trim();
|
|
182
|
+
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Goal-engine prompt templates. All roles except the summarizer write for
|
|
3
|
+
* MACHINE readers (the implementer, the verifier panel, the parser) — keep
|
|
4
|
+
* their outputs structured and terse. The summarizer alone writes for the
|
|
5
|
+
* user.
|
|
6
|
+
*/
|
|
7
|
+
import type { GoalKind, GoalState } from './types.js';
|
|
8
|
+
export declare function plannerPrompt(objective: string, kind: GoalKind): string;
|
|
9
|
+
export declare function taskDisciplineBlock(): string;
|
|
10
|
+
/** Spend shown as coarse buckets so the directive stays prompt-cache-friendly. */
|
|
11
|
+
export declare function spendBucket(spentUsd: number, maxUsd?: number): string;
|
|
12
|
+
export declare function continuationDirective(goal: GoalState, planMd: string, nextStep?: string): string;
|
|
13
|
+
export declare function verifierPrompt(goal: GoalState, planMd: string, claimMessage: string, lens: string): string;
|
|
14
|
+
export declare const VERIFIER_LENSES: string[];
|
|
15
|
+
export declare function strategistPrompt(goal: GoalState, planMd: string): string;
|
|
16
|
+
export declare function summarizerPrompt(goal: GoalState, planMd: string): string;
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Goal-engine prompt templates. All roles except the summarizer write for
|
|
3
|
+
* MACHINE readers (the implementer, the verifier panel, the parser) — keep
|
|
4
|
+
* their outputs structured and terse. The summarizer alone writes for the
|
|
5
|
+
* user.
|
|
6
|
+
*/
|
|
7
|
+
// ─── Planner ───────────────────────────────────────────────────────────────
|
|
8
|
+
const KIND_GUIDANCE = {
|
|
9
|
+
trading: `This is a TRADING goal. The plan MUST include:
|
|
10
|
+
- Entry criteria (what conditions justify opening each position)
|
|
11
|
+
- Exit criteria (profit target and stop conditions, in plain language)
|
|
12
|
+
- Risk limits: an explicit "Budget: $X" line (the maximum total USD at risk)
|
|
13
|
+
- A monitoring cadence if the goal spans time (use the Scheduler/Monitor tools)
|
|
14
|
+
Remember: every real-money trade will separately require an approved trade plan at execution time — your acceptance criteria should reference outcomes (position opened/closed per criteria, P&L recorded), not raw tool calls.`,
|
|
15
|
+
research: `This is a RESEARCH goal. The plan MUST name the deliverable (a written answer, comparison, or report), the source standards (primary sources over aggregators; cite what was actually read), and completeness criteria (which questions must be answered for the deliverable to count as done).`,
|
|
16
|
+
general: `This is a GENERAL task goal. Anchor acceptance criteria on observable outcomes (an artifact exists, a state changed, a question is answered with evidence) — never on effort spent.`,
|
|
17
|
+
};
|
|
18
|
+
export function plannerPrompt(objective, kind) {
|
|
19
|
+
return `You are a goal planner. Convert the objective below into a frozen plan that a
|
|
20
|
+
separate implementer agent will execute and a skeptical verifier panel will audit.
|
|
21
|
+
Downstream readers are machines, some on small models — be structured and unambiguous.
|
|
22
|
+
|
|
23
|
+
<objective>
|
|
24
|
+
${objective}
|
|
25
|
+
</objective>
|
|
26
|
+
|
|
27
|
+
${KIND_GUIDANCE[kind]}
|
|
28
|
+
|
|
29
|
+
Rules:
|
|
30
|
+
- Specify OUTCOMES, not methods. Do not prescribe which tools to call, in what
|
|
31
|
+
order, or how to structure intermediate work — freezing the HOW lets a verifier
|
|
32
|
+
wrongly refute correct work that took a different path.
|
|
33
|
+
- Write 3-5 ACCEPTANCE CRITERIA by GROUPING requirements, never one criterion per
|
|
34
|
+
detail and never an exhaustive conjunction. Satisficing beats completionism.
|
|
35
|
+
- If the objective references something with an established definition (a named
|
|
36
|
+
protocol, market mechanism, or convention), state the defining facts the
|
|
37
|
+
implementer must honor rather than assuming it knows them.
|
|
38
|
+
- Include a VERIFICATION PLAN: how the implementer should demonstrate each
|
|
39
|
+
criterion with evidence a skeptic can audit (commands run, data captured,
|
|
40
|
+
sources cited).
|
|
41
|
+
- Include NON-GOALS: what is explicitly out of scope, so the verifier cannot
|
|
42
|
+
invent requirements.
|
|
43
|
+
|
|
44
|
+
Output EXACTLY this structure (markdown):
|
|
45
|
+
|
|
46
|
+
# Goal Plan
|
|
47
|
+
## Objective
|
|
48
|
+
(one sentence restatement)
|
|
49
|
+
## Kind
|
|
50
|
+
${kind}
|
|
51
|
+
## Acceptance criteria
|
|
52
|
+
1. ...
|
|
53
|
+
## Verification plan
|
|
54
|
+
- ...
|
|
55
|
+
## Task checklist
|
|
56
|
+
- [ ] ...
|
|
57
|
+
## Non-goals
|
|
58
|
+
- ...
|
|
59
|
+
|
|
60
|
+
End your response with the plan only — no commentary after it.`;
|
|
61
|
+
}
|
|
62
|
+
// ─── Continuation directive (injected each turn while a goal is active) ────
|
|
63
|
+
export function taskDisciplineBlock() {
|
|
64
|
+
return `<task_discipline>
|
|
65
|
+
Four failure modes to avoid:
|
|
66
|
+
1. Narration without action: past-tense prose describing an action counts for
|
|
67
|
+
nothing unless the actual tool call happened. Call the tool, then narrate.
|
|
68
|
+
2. Do not ask permission to continue in-flight work. Only surface questions
|
|
69
|
+
that genuinely require a user decision.
|
|
70
|
+
3. The task checklist is your scratchpad, not the deliverable. Flip items to
|
|
71
|
+
[x] as you finish them; record real deviations in a "## Deviations" note.
|
|
72
|
+
4. Do not stop with easy work undone — the goal loop re-engages you until
|
|
73
|
+
verification passes anyway, so finishing now is strictly cheaper.
|
|
74
|
+
NO EVIDENCE THEATER: verification will audit what you actually did. Captured
|
|
75
|
+
outputs, real data, and cited sources count; claims do not.
|
|
76
|
+
</task_discipline>`;
|
|
77
|
+
}
|
|
78
|
+
/** Spend shown as coarse buckets so the directive stays prompt-cache-friendly. */
|
|
79
|
+
export function spendBucket(spentUsd, maxUsd) {
|
|
80
|
+
if (!maxUsd || maxUsd <= 0) {
|
|
81
|
+
if (spentUsd < 0.5)
|
|
82
|
+
return 'under $0.50';
|
|
83
|
+
if (spentUsd < 2)
|
|
84
|
+
return 'under $2';
|
|
85
|
+
if (spentUsd < 10)
|
|
86
|
+
return 'under $10';
|
|
87
|
+
return 'over $10';
|
|
88
|
+
}
|
|
89
|
+
const pct = (spentUsd / maxUsd) * 100;
|
|
90
|
+
if (pct < 25)
|
|
91
|
+
return 'under 25% of budget';
|
|
92
|
+
if (pct < 50)
|
|
93
|
+
return '25-50% of budget';
|
|
94
|
+
if (pct < 75)
|
|
95
|
+
return '50-75% of budget';
|
|
96
|
+
if (pct < 100)
|
|
97
|
+
return '75-100% of budget — wrap up';
|
|
98
|
+
return 'BUDGET EXHAUSTED';
|
|
99
|
+
}
|
|
100
|
+
export function continuationDirective(goal, planMd, nextStep) {
|
|
101
|
+
const gaps = goal.verifierGaps.length
|
|
102
|
+
? `\nOpen verification gaps (address these FIRST):\n${goal.verifierGaps.map(g => `- ${g}`).join('\n')}`
|
|
103
|
+
: '';
|
|
104
|
+
const strategist = goal.strategistNote
|
|
105
|
+
? `\nStrategist recommendation (a structural change — apply it rather than patching symptoms):\n${goal.strategistNote}`
|
|
106
|
+
: '';
|
|
107
|
+
const next = nextStep ? `\nNext step: ${nextStep}` : '';
|
|
108
|
+
return `<goal-state>
|
|
109
|
+
Active goal (${goal.kind}): ${goal.objective}
|
|
110
|
+
Status: ${goal.status} · verification rounds: ${goal.rounds.length} · spend: ${spendBucket(goal.budget.spentUsd, goal.budget.maxUsd)}
|
|
111
|
+
${gaps}${strategist}${next}
|
|
112
|
+
</goal-state>
|
|
113
|
+
|
|
114
|
+
<goal-plan>
|
|
115
|
+
${planMd}
|
|
116
|
+
</goal-plan>
|
|
117
|
+
|
|
118
|
+
Work the plan's task checklist in order. Run the plan's Verification plan yourself
|
|
119
|
+
BEFORE claiming completion. When (and only when) every acceptance criterion is
|
|
120
|
+
demonstrably met, call UpdateGoal with completed: true. If genuinely blocked on a
|
|
121
|
+
user decision, call UpdateGoal with blocked_reason.
|
|
122
|
+
|
|
123
|
+
${taskDisciplineBlock()}`;
|
|
124
|
+
}
|
|
125
|
+
// ─── Verifier (adversarial skeptic) ────────────────────────────────────────
|
|
126
|
+
export function verifierPrompt(goal, planMd, claimMessage, lens) {
|
|
127
|
+
return `You are an adversarial verifier. An implementer agent claims the goal below is
|
|
128
|
+
complete. Your JOB is to REFUTE the claim. If you are uncertain whether a
|
|
129
|
+
criterion is met, the verdict is refuted — a false pass that ships broken work
|
|
130
|
+
costs far more than one more iteration.
|
|
131
|
+
|
|
132
|
+
Your assigned lens: ${lens}.
|
|
133
|
+
|
|
134
|
+
<goal-plan>
|
|
135
|
+
${planMd}
|
|
136
|
+
</goal-plan>
|
|
137
|
+
|
|
138
|
+
<completion-claim>
|
|
139
|
+
${claimMessage || '(no message attached to the claim)'}
|
|
140
|
+
</completion-claim>
|
|
141
|
+
|
|
142
|
+
Audit doctrine:
|
|
143
|
+
- AUDIT, DON'T AUTHOR: examine the evidence the implementer produced (files,
|
|
144
|
+
captured outputs, cited sources, recorded data) with your read-only tools.
|
|
145
|
+
Minimize tool calls; do not redo the work.
|
|
146
|
+
- EVIDENCE HONESTY: hardcoded expected values, self-referential claims, sources
|
|
147
|
+
that were never actually read, or "verified" without captured output prove
|
|
148
|
+
nothing. But controlling an environment boundary (fixed clock, pinned data
|
|
149
|
+
snapshot) to make real behavior observable is honest evidence.
|
|
150
|
+
- ANTI-RATCHET: judge ONLY against the plan's acceptance criteria and non-goals.
|
|
151
|
+
Do not raise requirements the plan does not contain — missing edge cases,
|
|
152
|
+
stylistic preferences, and scope beyond the criteria are NOT grounds to refute.
|
|
153
|
+
On re-review rounds the bar must not rise; a fresh nitpick each round is the
|
|
154
|
+
failure mode that makes goals unfinishable.
|
|
155
|
+
- Classify a refute: blocking "none" = implementer can fix it; "contradiction" =
|
|
156
|
+
the objective precludes itself; "unverifiable" = the required evidence cannot
|
|
157
|
+
exist in this environment. The latter two escalate to the user, not to retry.
|
|
158
|
+
|
|
159
|
+
Respond with EXACTLY one JSON object on the final line of your response:
|
|
160
|
+
{"refuted": true|false, "findings": ["specific actionable gap", ...], "confidence": "low|medium|high", "blocking": "none|contradiction|unverifiable"}
|
|
161
|
+
Findings must be empty when refuted is false.`;
|
|
162
|
+
}
|
|
163
|
+
export const VERIFIER_LENSES = [
|
|
164
|
+
'criteria coverage — is every acceptance criterion demonstrably met with real evidence',
|
|
165
|
+
'evidence honesty — does the claimed evidence actually support the claims, or is it theater',
|
|
166
|
+
'reproducibility — would the demonstrated outcome hold if checked again right now',
|
|
167
|
+
];
|
|
168
|
+
// ─── Strategist ────────────────────────────────────────────────────────────
|
|
169
|
+
export function strategistPrompt(goal, planMd) {
|
|
170
|
+
const gapHistory = goal.rounds
|
|
171
|
+
.map(r => `Round ${r.round}: ${r.refuted ? 'REFUTED' : 'passed'} — ${r.gaps.join('; ') || 'no gaps'}`)
|
|
172
|
+
.join('\n');
|
|
173
|
+
return `You are a strategist. An implementer keeps failing verification on the goal
|
|
174
|
+
below, with a DIFFERENT gap surfacing each round (whack-a-mole) — patching
|
|
175
|
+
symptoms is not converging. Diagnose the STRUCTURAL root cause and recommend ONE
|
|
176
|
+
concrete structural change to HOW the work is being approached.
|
|
177
|
+
|
|
178
|
+
Hard limits: you may not change the objective or the acceptance criteria (WHAT is
|
|
179
|
+
frozen; only HOW may change). Recommend exactly one change, not a list.
|
|
180
|
+
|
|
181
|
+
<goal-plan>
|
|
182
|
+
${planMd}
|
|
183
|
+
</goal-plan>
|
|
184
|
+
|
|
185
|
+
<verification-history>
|
|
186
|
+
${gapHistory}
|
|
187
|
+
</verification-history>
|
|
188
|
+
|
|
189
|
+
Respond in at most 120 words:
|
|
190
|
+
Diagnosis: (the structural cause)
|
|
191
|
+
Restructure: (the one change)
|
|
192
|
+
Why this converges: (one sentence)`;
|
|
193
|
+
}
|
|
194
|
+
// ─── Summarizer ────────────────────────────────────────────────────────────
|
|
195
|
+
export function summarizerPrompt(goal, planMd) {
|
|
196
|
+
return `A goal just passed verification. Write the single closing message the user will
|
|
197
|
+
read. At most 80 words and 4 bullet points total: WHAT was delivered, and HOW to
|
|
198
|
+
use or see it (exact command, file, or position to look at). No process
|
|
199
|
+
narration, no praise, no caveats already covered by the plan's non-goals.
|
|
200
|
+
|
|
201
|
+
<goal-plan>
|
|
202
|
+
${planMd}
|
|
203
|
+
</goal-plan>
|
|
204
|
+
|
|
205
|
+
Objective: ${goal.objective}`;
|
|
206
|
+
}
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Goal runtime — bridges the UpdateGoal capability (constructed at module
|
|
3
|
+
* load, before any session exists) to the session's model client and
|
|
4
|
+
* capability set, and processes completion claims through the verifier
|
|
5
|
+
* panel. The loop installs the dependencies at session start.
|
|
6
|
+
*/
|
|
7
|
+
import type { ModelClient } from '../agent/llm.js';
|
|
8
|
+
import type { CapabilityHandler, CapabilityResult, ExecutionScope } from '../agent/types.js';
|
|
9
|
+
export interface GoalEngineDeps {
|
|
10
|
+
client: ModelClient;
|
|
11
|
+
getModel: () => string;
|
|
12
|
+
capabilities: CapabilityHandler[];
|
|
13
|
+
}
|
|
14
|
+
export declare function setGoalEngineDeps(d: GoalEngineDeps | null): void;
|
|
15
|
+
export interface GoalClaimInput {
|
|
16
|
+
completed?: boolean;
|
|
17
|
+
blocked_reason?: string;
|
|
18
|
+
message?: string;
|
|
19
|
+
}
|
|
20
|
+
export declare function processGoalClaim(input: GoalClaimInput, scope: ExecutionScope): Promise<CapabilityResult>;
|