@blockrun/franklin 3.32.1 → 3.34.0

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.
Files changed (97) hide show
  1. package/README.md +23 -2
  2. package/dist/agent/approvals.d.ts +47 -0
  3. package/dist/agent/approvals.js +66 -0
  4. package/dist/agent/commands.js +230 -7
  5. package/dist/agent/compact.js +1 -1
  6. package/dist/agent/context.js +1 -1
  7. package/dist/agent/input-queue.d.ts +26 -0
  8. package/dist/agent/input-queue.js +65 -0
  9. package/dist/agent/loop.js +198 -5
  10. package/dist/agent/optimize.js +1 -1
  11. package/dist/agent/streaming-executor.d.ts +4 -0
  12. package/dist/agent/streaming-executor.js +52 -0
  13. package/dist/agent/tokens.js +2 -0
  14. package/dist/agent/tool-guard.d.ts +7 -0
  15. package/dist/agent/tool-guard.js +21 -0
  16. package/dist/agent/types.d.ts +26 -0
  17. package/dist/audit/approvals.d.ts +20 -0
  18. package/dist/audit/approvals.js +21 -0
  19. package/dist/commands/init.js +1 -1
  20. package/dist/commands/models.d.ts +11 -0
  21. package/dist/commands/models.js +157 -37
  22. package/dist/commands/start.d.ts +10 -1
  23. package/dist/commands/start.js +53 -1
  24. package/dist/events/types.d.ts +38 -1
  25. package/dist/gateway-models.d.ts +14 -2
  26. package/dist/gateway-models.js +8 -0
  27. package/dist/goal/engine.d.ts +39 -0
  28. package/dist/goal/engine.js +182 -0
  29. package/dist/goal/prompts.d.ts +16 -0
  30. package/dist/goal/prompts.js +206 -0
  31. package/dist/goal/runtime.d.ts +20 -0
  32. package/dist/goal/runtime.js +110 -0
  33. package/dist/goal/store.d.ts +22 -0
  34. package/dist/goal/store.js +79 -0
  35. package/dist/goal/types.d.ts +63 -0
  36. package/dist/goal/types.js +26 -0
  37. package/dist/hooks/loader.d.ts +19 -0
  38. package/dist/hooks/loader.js +115 -0
  39. package/dist/hooks/runner.d.ts +31 -0
  40. package/dist/hooks/runner.js +147 -0
  41. package/dist/hooks/types.d.ts +64 -0
  42. package/dist/hooks/types.js +35 -0
  43. package/dist/index.js +5 -1
  44. package/dist/learnings/extractor.js +1 -1
  45. package/dist/memory/capture.d.ts +40 -0
  46. package/dist/memory/capture.js +95 -0
  47. package/dist/memory/dream.d.ts +24 -0
  48. package/dist/memory/dream.js +147 -0
  49. package/dist/memory/indexer.d.ts +29 -0
  50. package/dist/memory/indexer.js +144 -0
  51. package/dist/memory/store.d.ts +50 -0
  52. package/dist/memory/store.js +163 -0
  53. package/dist/monitors/registry.d.ts +42 -0
  54. package/dist/monitors/registry.js +104 -0
  55. package/dist/panel/html.js +299 -0
  56. package/dist/panel/server.js +41 -0
  57. package/dist/pricing.js +4 -1
  58. package/dist/router/index.js +15 -9
  59. package/dist/router/vision.js +5 -4
  60. package/dist/scheduler/service.d.ts +24 -0
  61. package/dist/scheduler/service.js +44 -0
  62. package/dist/scheduler/store.d.ts +26 -0
  63. package/dist/scheduler/store.js +116 -0
  64. package/dist/scheduler/types.d.ts +36 -0
  65. package/dist/scheduler/types.js +31 -0
  66. package/dist/serve/agent-host.d.ts +63 -0
  67. package/dist/serve/agent-host.js +270 -0
  68. package/dist/serve/server.js +131 -2
  69. package/dist/session/live-registry.d.ts +32 -0
  70. package/dist/session/live-registry.js +83 -0
  71. package/dist/session/search.d.ts +6 -0
  72. package/dist/session/search.js +3 -3
  73. package/dist/session/storage.d.ts +6 -0
  74. package/dist/session/storage.js +6 -0
  75. package/dist/tools/goal.d.ts +7 -0
  76. package/dist/tools/goal.js +29 -0
  77. package/dist/tools/index.js +11 -0
  78. package/dist/tools/memory.js +14 -4
  79. package/dist/tools/moa.js +1 -1
  80. package/dist/tools/monitor.d.ts +11 -0
  81. package/dist/tools/monitor.js +96 -0
  82. package/dist/tools/scheduler.d.ts +12 -0
  83. package/dist/tools/scheduler.js +79 -0
  84. package/dist/tools/spend-tools.d.ts +33 -0
  85. package/dist/tools/spend-tools.js +114 -0
  86. package/dist/tools/tool-categories.js +7 -0
  87. package/dist/tools/trade-plan.d.ts +11 -0
  88. package/dist/tools/trade-plan.js +137 -0
  89. package/dist/tools/trading-execute.js +24 -0
  90. package/dist/trading/trade-plan.d.ts +75 -0
  91. package/dist/trading/trade-plan.js +290 -0
  92. package/dist/ui/app.js +54 -9
  93. package/dist/ui/model-picker.d.ts +40 -0
  94. package/dist/ui/model-picker.js +135 -25
  95. package/package.json +2 -2
  96. package/dist/agent/media-router.d.ts +0 -98
  97. package/dist/agent/media-router.js +0 -328
@@ -0,0 +1,31 @@
1
+ /**
2
+ * HookEngine — dispatches lifecycle events to loaded hooks.
3
+ *
4
+ * Decision semantics (blocking events only):
5
+ * exit 0 → allow
6
+ * exit 2 → deny
7
+ * stdout {"decision":"deny",...} → deny, regardless of exit code
8
+ * timeout / crash / spawn failure → allow (fail-open) + logged
9
+ *
10
+ * Handlers run sequentially per event; the first deny short-circuits.
11
+ * Non-blocking events run every matching handler and always resolve allow.
12
+ */
13
+ import { type HookDecision, type HookEvent, type HookInput, type LoadedHook } from './types.js';
14
+ export declare class HookEngine {
15
+ private hooks;
16
+ private byEvent;
17
+ /** Hooks are read once at engine construction (session start). */
18
+ constructor(opts: {
19
+ workDir: string;
20
+ hooks?: LoadedHook[];
21
+ });
22
+ /** Fast path so call sites skip envelope construction when nothing listens. */
23
+ hasHooks(event: HookEvent): boolean;
24
+ listHooks(): ReadonlyArray<LoadedHook>;
25
+ /**
26
+ * Run every hook registered for `event` whose matcher accepts the tool name.
27
+ * Returns the aggregate decision; always 'allow' for non-blocking events.
28
+ */
29
+ dispatch(event: HookEvent, input: HookInput): Promise<HookDecision>;
30
+ private runHandler;
31
+ }
@@ -0,0 +1,147 @@
1
+ /**
2
+ * HookEngine — dispatches lifecycle events to loaded hooks.
3
+ *
4
+ * Decision semantics (blocking events only):
5
+ * exit 0 → allow
6
+ * exit 2 → deny
7
+ * stdout {"decision":"deny",...} → deny, regardless of exit code
8
+ * timeout / crash / spawn failure → allow (fail-open) + logged
9
+ *
10
+ * Handlers run sequentially per event; the first deny short-circuits.
11
+ * Non-blocking events run every matching handler and always resolve allow.
12
+ */
13
+ import { execFile } from 'node:child_process';
14
+ import path from 'node:path';
15
+ import fs from 'node:fs';
16
+ import { logger } from '../logger.js';
17
+ import { appendApprovalRecord } from '../audit/approvals.js';
18
+ import { loadHooks } from './loader.js';
19
+ import { BLOCKING_EVENTS, } from './types.js';
20
+ const DEFAULT_TIMEOUT_SECS = 5;
21
+ const MAX_STDOUT_BYTES = 64 * 1024;
22
+ export class HookEngine {
23
+ hooks;
24
+ byEvent = new Map();
25
+ /** Hooks are read once at engine construction (session start). */
26
+ constructor(opts) {
27
+ this.hooks = opts.hooks ?? loadHooks(opts.workDir);
28
+ for (const hook of this.hooks) {
29
+ const list = this.byEvent.get(hook.event) ?? [];
30
+ list.push(hook);
31
+ this.byEvent.set(hook.event, list);
32
+ }
33
+ }
34
+ /** Fast path so call sites skip envelope construction when nothing listens. */
35
+ hasHooks(event) {
36
+ return (this.byEvent.get(event)?.length ?? 0) > 0;
37
+ }
38
+ listHooks() {
39
+ return this.hooks;
40
+ }
41
+ /**
42
+ * Run every hook registered for `event` whose matcher accepts the tool name.
43
+ * Returns the aggregate decision; always 'allow' for non-blocking events.
44
+ */
45
+ async dispatch(event, input) {
46
+ const candidates = this.byEvent.get(event);
47
+ if (!candidates || candidates.length === 0)
48
+ return { decision: 'allow' };
49
+ const toolName = input.toolName ?? input.spend?.tool ?? '';
50
+ const blocking = BLOCKING_EVENTS.has(event);
51
+ for (const hook of candidates) {
52
+ if (hook.matcher && !hook.matcher.test(toolName))
53
+ continue;
54
+ const result = await this.runHandler(hook, input);
55
+ if (blocking && result.decision === 'deny') {
56
+ appendApprovalRecord({
57
+ ts: Date.now(),
58
+ sessionId: input.sessionId,
59
+ kind: 'hook',
60
+ subject: toolName || event,
61
+ decision: 'deny',
62
+ by: `hook:${path.basename(hook.sourceFile)}`,
63
+ reason: result.reason,
64
+ });
65
+ return result;
66
+ }
67
+ }
68
+ return { decision: 'allow' };
69
+ }
70
+ runHandler(hook, input) {
71
+ const timeoutMs = Math.max(1, hook.handler.timeout ?? DEFAULT_TIMEOUT_SECS) * 1000;
72
+ // A bare relative path resolves against the hook file's directory so hook
73
+ // bundles are relocatable; anything with shell syntax runs as written.
74
+ let command = hook.handler.command;
75
+ const looksLikeBarePath = !/[\s;&|<>$`]/.test(command);
76
+ if (looksLikeBarePath && !path.isAbsolute(command)) {
77
+ const resolved = path.resolve(path.dirname(hook.sourceFile), command);
78
+ if (fs.existsSync(resolved))
79
+ command = resolved;
80
+ }
81
+ return new Promise(resolve => {
82
+ const child = execFile('/bin/sh', ['-c', command], {
83
+ timeout: timeoutMs,
84
+ maxBuffer: MAX_STDOUT_BYTES,
85
+ env: {
86
+ ...process.env,
87
+ ...hook.handler.env,
88
+ // Reserved vars always win over handler env.
89
+ FRANKLIN_HOOK_EVENT: input.hookEventName,
90
+ FRANKLIN_SESSION_ID: input.sessionId,
91
+ FRANKLIN_CWD: input.cwd,
92
+ },
93
+ }, (err, stdout) => {
94
+ // Explicit stdout deny wins regardless of exit code.
95
+ const parsed = parseDecision(stdout);
96
+ if (parsed?.decision === 'deny') {
97
+ resolve({ decision: 'deny', reason: parsed.reason || `denied by ${path.basename(hook.sourceFile)}` });
98
+ return;
99
+ }
100
+ if (!err) {
101
+ resolve({ decision: 'allow' });
102
+ return;
103
+ }
104
+ // child_process sets `code` to the numeric exit status on non-zero
105
+ // exit (typed as string|number across Node versions — normalize).
106
+ const code = err.code;
107
+ if (code !== undefined && Number(code) === 2) {
108
+ resolve({ decision: 'deny', reason: `denied by ${path.basename(hook.sourceFile)} (exit 2)` });
109
+ return;
110
+ }
111
+ // Timeout, crash, missing binary, other exit codes: fail open.
112
+ logger.warn(`[hooks] ${path.basename(hook.sourceFile)} ${input.hookEventName} handler failed open: ${err.message.slice(0, 160)}`);
113
+ resolve({ decision: 'allow' });
114
+ });
115
+ try {
116
+ child.stdin?.write(JSON.stringify(input));
117
+ child.stdin?.end();
118
+ }
119
+ catch {
120
+ // EPIPE from a handler that never reads stdin — fine, decision comes
121
+ // from its exit code / stdout.
122
+ }
123
+ });
124
+ }
125
+ }
126
+ function parseDecision(stdout) {
127
+ const text = String(stdout ?? '').trim();
128
+ if (!text)
129
+ return null;
130
+ // Handlers may print human noise before the JSON — scan lines from the end.
131
+ const lines = text.split('\n');
132
+ for (let i = lines.length - 1; i >= 0; i--) {
133
+ const line = lines[i].trim();
134
+ if (!line.startsWith('{'))
135
+ continue;
136
+ try {
137
+ const obj = JSON.parse(line);
138
+ if (obj && (obj.decision === 'deny' || obj.decision === 'allow')) {
139
+ return { decision: obj.decision, reason: typeof obj.reason === 'string' ? obj.reason : undefined };
140
+ }
141
+ }
142
+ catch {
143
+ /* not JSON — keep scanning */
144
+ }
145
+ }
146
+ return null;
147
+ }
@@ -0,0 +1,64 @@
1
+ /**
2
+ * Lifecycle hooks — user-authored guardrails and automations.
3
+ *
4
+ * Hooks are external commands the harness runs at fixed lifecycle points.
5
+ * They receive a JSON envelope on stdin and can veto the action (blocking
6
+ * events only) by exiting 2 or printing {"decision":"deny"} on stdout.
7
+ *
8
+ * Safety model: hooks are a convenience layer, not a security boundary.
9
+ * A hook that crashes, times out, or is missing FAILS OPEN — work proceeds
10
+ * and the failure is logged. Only an explicit deny blocks. This keeps a
11
+ * buggy hook from bricking the agent while still letting deliberate policy
12
+ * (spend caps, token blacklists) intercept actions.
13
+ */
14
+ export type HookEvent = 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse' | 'Stop' | 'SessionEnd' | 'PreSpend' | 'PostSpend';
15
+ /** Events whose handlers can veto the action. All others are notify-only. */
16
+ export declare const BLOCKING_EVENTS: ReadonlySet<HookEvent>;
17
+ /** Events that carry no tool context — a matcher on these is a config error. */
18
+ export declare const LIFECYCLE_EVENTS: ReadonlySet<HookEvent>;
19
+ export declare const HOOK_EVENTS: ReadonlySet<string>;
20
+ export interface HookHandlerDef {
21
+ type: 'command';
22
+ /** Shell command. A bare relative path resolves against the hook file's dir. */
23
+ command: string;
24
+ /** Seconds before the handler is killed and treated as allow. Default 5. */
25
+ timeout?: number;
26
+ env?: Record<string, string>;
27
+ }
28
+ export interface HookMatcherDef {
29
+ /** Regex tested against the tool name. Absent/empty = match all. */
30
+ matcher?: string;
31
+ hooks: HookHandlerDef[];
32
+ }
33
+ /** On-disk file shape: { "hooks": { "<Event>": [ {matcher, hooks:[...]} ] } } */
34
+ export interface HookConfigFile {
35
+ hooks: Partial<Record<string, HookMatcherDef[]>>;
36
+ }
37
+ /** Loaded + validated handler with provenance for logs and the /hooks UI. */
38
+ export interface LoadedHook {
39
+ event: HookEvent;
40
+ matcher?: RegExp;
41
+ handler: HookHandlerDef;
42
+ /** Absolute path of the JSON file this hook came from. */
43
+ sourceFile: string;
44
+ scope: 'user' | 'project';
45
+ }
46
+ /** stdin envelope delivered to every handler. */
47
+ export interface HookInput {
48
+ hookEventName: HookEvent;
49
+ sessionId: string;
50
+ cwd: string;
51
+ timestamp: string;
52
+ toolName?: string;
53
+ toolInput?: Record<string, unknown>;
54
+ /** Present on PreSpend/PostSpend. estimatedUsd is null when unknown. */
55
+ spend?: {
56
+ estimatedUsd: number | null;
57
+ tool: string;
58
+ params: Record<string, unknown>;
59
+ };
60
+ }
61
+ export interface HookDecision {
62
+ decision: 'allow' | 'deny';
63
+ reason?: string;
64
+ }
@@ -0,0 +1,35 @@
1
+ /**
2
+ * Lifecycle hooks — user-authored guardrails and automations.
3
+ *
4
+ * Hooks are external commands the harness runs at fixed lifecycle points.
5
+ * They receive a JSON envelope on stdin and can veto the action (blocking
6
+ * events only) by exiting 2 or printing {"decision":"deny"} on stdout.
7
+ *
8
+ * Safety model: hooks are a convenience layer, not a security boundary.
9
+ * A hook that crashes, times out, or is missing FAILS OPEN — work proceeds
10
+ * and the failure is logged. Only an explicit deny blocks. This keeps a
11
+ * buggy hook from bricking the agent while still letting deliberate policy
12
+ * (spend caps, token blacklists) intercept actions.
13
+ */
14
+ /** Events whose handlers can veto the action. All others are notify-only. */
15
+ export const BLOCKING_EVENTS = new Set([
16
+ 'PreToolUse',
17
+ 'PreSpend',
18
+ ]);
19
+ /** Events that carry no tool context — a matcher on these is a config error. */
20
+ export const LIFECYCLE_EVENTS = new Set([
21
+ 'SessionStart',
22
+ 'UserPromptSubmit',
23
+ 'Stop',
24
+ 'SessionEnd',
25
+ ]);
26
+ export const HOOK_EVENTS = new Set([
27
+ 'SessionStart',
28
+ 'UserPromptSubmit',
29
+ 'PreToolUse',
30
+ 'PostToolUse',
31
+ 'Stop',
32
+ 'SessionEnd',
33
+ 'PreSpend',
34
+ 'PostSpend',
35
+ ]);
package/dist/index.js CHANGED
@@ -53,6 +53,7 @@ program
53
53
  .option('-c, --continue', 'Continue the most recent session in this directory')
54
54
  .option('--max-spend <usd>', 'Hard USD cap on total session API spend — session stops when exceeded')
55
55
  .option('-p, --prompt <text>', 'Run a single prompt non-interactively (for batch/scripted use)')
56
+ .option('--approve-trades', 'Non-interactive runs: auto-approve trade plans that fit within --max-spend (default: reject all trades)')
56
57
  .action((fromSessionId, options) => startCommand({ ...options, fromSessionId, version }));
57
58
  program
58
59
  .command('resume [sessionId]')
@@ -276,7 +277,7 @@ const args = process.argv.slice(2);
276
277
  const firstArg = args[0];
277
278
  const HELP_FLAGS = new Set(['-h', '--help']);
278
279
  const VERSION_FLAGS = new Set(['-V', '--version']);
279
- const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '--from', '-r', '--resume', '-c', '--continue', '-p', '--prompt', '--max-spend']);
280
+ const START_ONLY_FLAGS = new Set(['--trust', '--debug', '-m', '--model', '--from', '-r', '--resume', '-c', '--continue', '-p', '--prompt', '--max-spend', '--approve-trades']);
280
281
  function hasAnyFlag(argv, flags) {
281
282
  return argv.some(arg => flags.has(arg));
282
283
  }
@@ -300,6 +301,9 @@ function parseStartFlags(argv, startIdx = 0) {
300
301
  else if (arg === '--max-spend' && argv[i + 1]) {
301
302
  opts.maxSpend = argv[++i];
302
303
  }
304
+ else if (arg === '--approve-trades') {
305
+ opts.approveTrades = true;
306
+ }
303
307
  else if (arg === '--from') {
304
308
  opts.from = argv[i + 1] && !argv[i + 1].startsWith('-') ? argv[++i] : '';
305
309
  const next = argv[i + 1];
@@ -10,7 +10,7 @@ import { loadLearnings, mergeLearning, saveLearnings, loadSkills, saveSkill } fr
10
10
  // Ordered by reliability: try the best free model first, fall back to others.
11
11
  const EXTRACTION_MODELS = [
12
12
  'nvidia/qwen3-next-80b-a3b-instruct', // Clean JSON output, no thinking leak (verified live)
13
- 'nvidia/llama-4-maverick', // Diverse-family free fallback
13
+ 'nvidia/mistral-nemotron', // Diverse-family free fallback (serves itself; maverick is pooled)
14
14
  ];
15
15
  const VALID_CATEGORIES = new Set([
16
16
  'language', 'model_preference', 'tool_pattern', 'coding_style',
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Memory capture pipeline:
3
+ * - zero-LLM session summaries at session end (metadata only, free)
4
+ * - /flush — LLM capture of the session's durable learnings
5
+ * - trading capture — journal + thesis entries on trade execution
6
+ */
7
+ import type { Dialogue } from '../agent/types.js';
8
+ import type { ModelClient } from '../agent/llm.js';
9
+ /**
10
+ * Metadata-only session summary — no LLM call, no latency, no cost.
11
+ * Trivial sessions (fewer than 3 substantive prompts) are skipped.
12
+ */
13
+ export declare function writeSessionMetadataSummary(opts: {
14
+ workDir: string;
15
+ sessionId: string;
16
+ history: Dialogue[];
17
+ costUsd?: number;
18
+ }): boolean;
19
+ /** /flush — LLM capture of the session's durable content into a session log. */
20
+ export declare function flushSessionMemory(opts: {
21
+ client: ModelClient;
22
+ model: string;
23
+ workDir: string;
24
+ sessionId: string;
25
+ history: Dialogue[];
26
+ signal?: AbortSignal;
27
+ }): Promise<string | null>;
28
+ export interface TradeMemoryEvent {
29
+ kind: 'open' | 'close' | 'bet';
30
+ chain: string;
31
+ address: string;
32
+ asset: string;
33
+ amountUsd?: number;
34
+ thesis?: string;
35
+ pnlUsd?: number;
36
+ /** Reference into trades.jsonl / tx hash for the audit trail. */
37
+ ref?: string;
38
+ }
39
+ /** Append a curated journal entry (and thesis file on opens with a thesis). */
40
+ export declare function captureTradeEvent(event: TradeMemoryEvent): void;
@@ -0,0 +1,95 @@
1
+ /**
2
+ * Memory capture pipeline:
3
+ * - zero-LLM session summaries at session end (metadata only, free)
4
+ * - /flush — LLM capture of the session's durable learnings
5
+ * - trading capture — journal + thesis entries on trade execution
6
+ */
7
+ import { recordUsage } from '../stats/tracker.js';
8
+ import { estimateCost } from '../pricing.js';
9
+ import { appendUnderHeading, memoryEnabled, sessionLogPath, thesisPath, tradingJournalPath, writeSessionLog, } from './store.js';
10
+ function userPrompts(history) {
11
+ const prompts = [];
12
+ for (const msg of history) {
13
+ if (msg.role !== 'user' || typeof msg.content !== 'string')
14
+ continue;
15
+ const text = msg.content.trim();
16
+ // Skip harness-injected continuations and command noise.
17
+ if (!text || text.startsWith('/') || text.startsWith('Continue working the active goal'))
18
+ continue;
19
+ prompts.push(text);
20
+ }
21
+ return prompts;
22
+ }
23
+ /**
24
+ * Metadata-only session summary — no LLM call, no latency, no cost.
25
+ * Trivial sessions (fewer than 3 substantive prompts) are skipped.
26
+ */
27
+ export function writeSessionMetadataSummary(opts) {
28
+ if (!memoryEnabled())
29
+ return false;
30
+ const prompts = userPrompts(opts.history);
31
+ const totalUserBytes = prompts.reduce((n, p) => n + p.length, 0);
32
+ if (prompts.length < 3 || totalUserBytes < 50)
33
+ return false;
34
+ const topics = prompts.slice(0, 5).map(p => `- ${p.replace(/\s+/g, ' ').slice(0, 120)}`);
35
+ writeSessionLog(opts.workDir, opts.sessionId, [
36
+ `# Session ${opts.sessionId.slice(0, 8)} — ${new Date().toISOString()}`,
37
+ '',
38
+ `Messages: ${opts.history.length} · user prompts: ${prompts.length}` +
39
+ (opts.costUsd != null ? ` · cost: $${opts.costUsd.toFixed(4)}` : ''),
40
+ '',
41
+ '## Topics',
42
+ ...topics,
43
+ ].join('\n'));
44
+ return true;
45
+ }
46
+ const FLUSH_PROMPT = `Review the conversation above and extract ONLY the durable learnings worth
47
+ remembering across sessions: decisions made and why, facts discovered about the
48
+ user's holdings/preferences/projects, working theses, and outcomes of actions
49
+ taken. Skip process narration and anything trivially re-derivable. Output tight
50
+ markdown bullets grouped under ## headings (Preferences / Decisions / Findings /
51
+ Theses as applicable), max 2000 characters. If nothing is worth keeping, output
52
+ exactly: NOTHING_DURABLE`;
53
+ /** /flush — LLM capture of the session's durable content into a session log. */
54
+ export async function flushSessionMemory(opts) {
55
+ if (!memoryEnabled())
56
+ return null;
57
+ const { content, usage } = await opts.client.complete({
58
+ model: opts.model,
59
+ messages: [...opts.history, { role: 'user', content: FLUSH_PROMPT }],
60
+ max_tokens: 1024,
61
+ stream: true,
62
+ }, opts.signal ?? new AbortController().signal);
63
+ try {
64
+ recordUsage(opts.model, usage.inputTokens, usage.outputTokens, estimateCost(opts.model, usage.inputTokens, usage.outputTokens), 0);
65
+ }
66
+ catch { /* best-effort */ }
67
+ const text = content
68
+ .filter((p) => p.type === 'text')
69
+ .map(p => p.text)
70
+ .join('\n')
71
+ .trim();
72
+ if (!text || text.includes('NOTHING_DURABLE'))
73
+ return null;
74
+ writeSessionLog(opts.workDir, opts.sessionId, `# Session ${opts.sessionId.slice(0, 8)} — flushed ${new Date().toISOString()}\n\n${text.slice(0, 4000)}`);
75
+ return sessionLogPath(opts.workDir, opts.sessionId);
76
+ }
77
+ /** Append a curated journal entry (and thesis file on opens with a thesis). */
78
+ export function captureTradeEvent(event) {
79
+ if (!memoryEnabled())
80
+ return;
81
+ if (!event.address)
82
+ return;
83
+ const journal = tradingJournalPath(event.chain, event.address);
84
+ const amount = event.amountUsd != null ? ` $${event.amountUsd.toFixed(2)}` : '';
85
+ const pnl = event.pnlUsd != null ? ` · P&L ${event.pnlUsd >= 0 ? '+' : ''}$${event.pnlUsd.toFixed(2)}` : '';
86
+ const ref = event.ref ? ` · ref ${event.ref}` : '';
87
+ const heading = event.kind === 'close' ? 'Closed positions' : event.kind === 'bet' ? 'Bets' : 'Open positions';
88
+ appendUnderHeading(journal, heading, `${event.kind.toUpperCase()} ${event.asset}${amount}${pnl}${ref}`);
89
+ if (event.thesis && event.kind !== 'close') {
90
+ appendUnderHeading(thesisPath(event.chain, event.address, event.asset), 'Thesis', `${event.thesis.trim().slice(0, 600)}${ref}`);
91
+ }
92
+ if (event.kind === 'close' && event.pnlUsd != null) {
93
+ appendUnderHeading(thesisPath(event.chain, event.address, event.asset), 'Outcomes', `closed${amount}${pnl}${ref}`);
94
+ }
95
+ }
@@ -0,0 +1,24 @@
1
+ /**
2
+ * /dream — consolidation. Distills accumulated session logs into the
3
+ * curated workspace MEMORY.md (deduplicated, organized), then archives
4
+ * the consumed logs. Auto-gated: runs only when enough time and sessions
5
+ * have accumulated, with a cross-process lock so concurrent sessions
6
+ * can't double-dream.
7
+ */
8
+ import type { ModelClient } from '../agent/llm.js';
9
+ export declare const DREAM_MIN_HOURS = 4;
10
+ export declare const DREAM_MIN_SESSIONS = 3;
11
+ export declare function dreamGatesPass(workDir: string, now?: number): boolean;
12
+ export interface DreamResult {
13
+ consolidated: boolean;
14
+ logsConsumed: number;
15
+ reason?: string;
16
+ }
17
+ export declare function runDream(opts: {
18
+ client: ModelClient;
19
+ model: string;
20
+ workDir: string;
21
+ signal?: AbortSignal;
22
+ /** Skip the time/count gates (explicit /dream command). */
23
+ force?: boolean;
24
+ }): Promise<DreamResult>;
@@ -0,0 +1,147 @@
1
+ /**
2
+ * /dream — consolidation. Distills accumulated session logs into the
3
+ * curated workspace MEMORY.md (deduplicated, organized), then archives
4
+ * the consumed logs. Auto-gated: runs only when enough time and sessions
5
+ * have accumulated, with a cross-process lock so concurrent sessions
6
+ * can't double-dream.
7
+ */
8
+ import fs from 'node:fs';
9
+ import path from 'node:path';
10
+ import { recordUsage } from '../stats/tracker.js';
11
+ import { estimateCost } from '../pricing.js';
12
+ import { memoryEnabled, sessionLogsDir, workspaceDir, workspaceMemoryPath } from './store.js';
13
+ export const DREAM_MIN_HOURS = 4;
14
+ export const DREAM_MIN_SESSIONS = 3;
15
+ const LOCK_STALE_MS = 3600_000;
16
+ function lockPath(workDir) {
17
+ return path.join(workspaceDir(workDir), 'dream.lock');
18
+ }
19
+ function lastDreamPath(workDir) {
20
+ return path.join(workspaceDir(workDir), '.last-dream');
21
+ }
22
+ export function dreamGatesPass(workDir, now = Date.now()) {
23
+ if (!memoryEnabled())
24
+ return false;
25
+ let logs = [];
26
+ try {
27
+ logs = fs.readdirSync(sessionLogsDir(workDir)).filter(f => f.endsWith('.md'));
28
+ }
29
+ catch {
30
+ return false;
31
+ }
32
+ if (logs.length < DREAM_MIN_SESSIONS)
33
+ return false;
34
+ try {
35
+ const last = Number(fs.readFileSync(lastDreamPath(workDir), 'utf-8'));
36
+ if (Number.isFinite(last) && now - last < DREAM_MIN_HOURS * 3600_000)
37
+ return false;
38
+ }
39
+ catch { /* never dreamed */ }
40
+ return true;
41
+ }
42
+ function acquireLock(workDir) {
43
+ const p = lockPath(workDir);
44
+ try {
45
+ const stat = fs.statSync(p);
46
+ if (Date.now() - stat.mtimeMs < LOCK_STALE_MS)
47
+ return false; // held
48
+ fs.unlinkSync(p); // stale — reclaim
49
+ }
50
+ catch { /* no lock */ }
51
+ try {
52
+ fs.mkdirSync(path.dirname(p), { recursive: true });
53
+ fs.writeFileSync(p, String(process.pid), { flag: 'wx' });
54
+ return true;
55
+ }
56
+ catch {
57
+ return false;
58
+ }
59
+ }
60
+ function releaseLock(workDir) {
61
+ try {
62
+ fs.unlinkSync(lockPath(workDir));
63
+ }
64
+ catch { /* already gone */ }
65
+ }
66
+ const DREAM_PROMPT = (curated, logs) => `You are consolidating an agent's memory. Below is the CURATED long-term memory
67
+ file followed by accumulated raw session logs. Produce the NEW COMPLETE curated
68
+ memory file: merge durable knowledge from the logs into the curated content,
69
+ deduplicate aggressively, drop stale/superseded observations, keep it organized
70
+ under ## headings, and stay under 6000 characters. Output ONLY the new file
71
+ content (markdown, starting with a # title).
72
+
73
+ === CURATED MEMORY ===
74
+ ${curated || '(empty)'}
75
+
76
+ === SESSION LOGS ===
77
+ ${logs}`;
78
+ export async function runDream(opts) {
79
+ if (!memoryEnabled())
80
+ return { consolidated: false, logsConsumed: 0, reason: 'memory disabled' };
81
+ if (!opts.force && !dreamGatesPass(opts.workDir)) {
82
+ return { consolidated: false, logsConsumed: 0, reason: 'gates not met (needs ≥3 session logs and ≥4h since last dream)' };
83
+ }
84
+ if (!acquireLock(opts.workDir)) {
85
+ return { consolidated: false, logsConsumed: 0, reason: 'another session is consolidating' };
86
+ }
87
+ try {
88
+ const dir = sessionLogsDir(opts.workDir);
89
+ let files = [];
90
+ try {
91
+ files = fs.readdirSync(dir).filter(f => f.endsWith('.md')).sort();
92
+ }
93
+ catch { /* none */ }
94
+ if (files.length === 0)
95
+ return { consolidated: false, logsConsumed: 0, reason: 'no session logs' };
96
+ let curated = '';
97
+ try {
98
+ curated = fs.readFileSync(workspaceMemoryPath(opts.workDir), 'utf-8');
99
+ }
100
+ catch { /* fresh */ }
101
+ const logs = files
102
+ .map(f => {
103
+ try {
104
+ return `--- ${f} ---\n${fs.readFileSync(path.join(dir, f), 'utf-8').slice(0, 4000)}`;
105
+ }
106
+ catch {
107
+ return '';
108
+ }
109
+ })
110
+ .filter(Boolean)
111
+ .join('\n\n')
112
+ .slice(0, 40_000);
113
+ const { content, usage } = await opts.client.complete({
114
+ model: opts.model,
115
+ messages: [{ role: 'user', content: DREAM_PROMPT(curated, logs) }],
116
+ max_tokens: 2048,
117
+ stream: true,
118
+ }, opts.signal ?? new AbortController().signal);
119
+ try {
120
+ recordUsage(opts.model, usage.inputTokens, usage.outputTokens, estimateCost(opts.model, usage.inputTokens, usage.outputTokens), 0);
121
+ }
122
+ catch { /* best-effort */ }
123
+ const newMemory = content
124
+ .filter((p) => p.type === 'text')
125
+ .map(p => p.text)
126
+ .join('\n')
127
+ .trim();
128
+ if (!newMemory.startsWith('#')) {
129
+ return { consolidated: false, logsConsumed: 0, reason: 'consolidation produced no usable file' };
130
+ }
131
+ fs.writeFileSync(workspaceMemoryPath(opts.workDir), newMemory.slice(0, 12_000) + '\n');
132
+ // Archive consumed logs (kept for forensics, out of the search path).
133
+ const archive = path.join(dir, 'archived');
134
+ fs.mkdirSync(archive, { recursive: true });
135
+ for (const f of files) {
136
+ try {
137
+ fs.renameSync(path.join(dir, f), path.join(archive, f));
138
+ }
139
+ catch { /* best-effort */ }
140
+ }
141
+ fs.writeFileSync(lastDreamPath(opts.workDir), String(Date.now()));
142
+ return { consolidated: true, logsConsumed: files.length };
143
+ }
144
+ finally {
145
+ releaseLock(opts.workDir);
146
+ }
147
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Document-memory search — pure-TS chunked TF scoring (no native deps).
3
+ *
4
+ * Chunks of ~1600 chars with 320 overlap; term-frequency scoring reusing
5
+ * the session-search tokenizer; TEMPORAL DECAY applies ONLY to session-log
6
+ * chunks (half-life 7 days) — curated global/workspace/trading files are
7
+ * long-term knowledge and never decay. Old session hits carry a staleness
8
+ * note so the model verifies before trusting. An mtime-keyed cache keeps
9
+ * re-index cost at zero for unchanged files.
10
+ */
11
+ import { type MemoryFileRef } from './store.js';
12
+ export declare const CHUNK_CHARS = 1600;
13
+ export declare const CHUNK_OVERLAP = 320;
14
+ export declare const SESSION_HALF_LIFE_DAYS = 7;
15
+ export interface MemoryHit {
16
+ file: string;
17
+ scope: MemoryFileRef['scope'];
18
+ snippet: string;
19
+ score: number;
20
+ /** Present on old session hits — surfaced verbatim to the model. */
21
+ stalenessNote?: string;
22
+ }
23
+ export declare function resetMemoryIndexCache(): void;
24
+ export declare function searchMemory(query: string, workDir: string, opts?: {
25
+ limit?: number;
26
+ minScore?: number;
27
+ }): MemoryHit[];
28
+ /** Compact context block for prompt injection; ~1.5k-token budget. */
29
+ export declare function formatMemoryContext(hits: MemoryHit[], budgetChars?: number): string;