@phren/cli 0.3.70 → 0.3.72
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/dist/bridge/browser-env.d.ts +5 -0
- package/dist/bridge/browser-env.js +86 -0
- package/dist/bridge/browser-protocol.d.ts +120 -0
- package/dist/bridge/browser-protocol.js +70 -0
- package/dist/bridge/browser-recordings.d.ts +63 -0
- package/dist/bridge/browser-recordings.js +148 -0
- package/dist/bridge/browser-registry.d.ts +64 -0
- package/dist/bridge/browser-registry.js +262 -0
- package/dist/bridge/browser-routes.d.ts +4 -0
- package/dist/bridge/browser-routes.js +39 -0
- package/dist/bridge/browser-shim/phren-playwright.cjs +184 -0
- package/dist/bridge/browser-socket.d.ts +2 -0
- package/dist/bridge/browser-socket.js +10 -0
- package/dist/bridge/browser-stream.d.ts +3 -0
- package/dist/bridge/browser-stream.js +129 -0
- package/dist/bridge/claude-question-dialog.js +32 -7
- package/dist/bridge/dispatch.d.ts +10 -0
- package/dist/bridge/dispatch.js +3 -1
- package/dist/bridge/dream-schedule.d.ts +133 -0
- package/dist/bridge/dream-schedule.js +322 -0
- package/dist/bridge/herdr.js +15 -6
- package/dist/bridge/install.js +4 -0
- package/dist/bridge/launch-brief.d.ts +11 -0
- package/dist/bridge/launch-brief.js +22 -0
- package/dist/bridge/pane-status.js +1 -1
- package/dist/bridge/server-routes.d.ts +3 -0
- package/dist/bridge/server-routes.js +15 -15
- package/dist/bridge/server-stream.d.ts +4 -0
- package/dist/bridge/server-stream.js +24 -5
- package/dist/bridge/server.js +23 -3
- package/dist/bridge/session-move.d.ts +10 -4
- package/dist/bridge/session-move.js +65 -34
- package/dist/bridge/simulator-stream.d.ts +2 -0
- package/dist/bridge/simulator-stream.js +2 -0
- package/dist/bridge/tab-activity.d.ts +2 -0
- package/dist/bridge/tab-activity.js +15 -2
- package/dist/bridge/task-routes.d.ts +20 -16
- package/dist/bridge/task-routes.js +1 -1
- package/dist/bridge/terminal-herdr.js +2 -1
- package/dist/bridge/terminal-tmux.js +2 -1
- package/dist/bridge/worker-reports.js +15 -3
- package/dist/bridge-hook.mjs +36819 -35219
- package/dist/capabilities/mcp.js +1 -1
- package/dist/cli/config-dreaming.d.ts +7 -0
- package/dist/cli/config-dreaming.js +72 -0
- package/dist/cli/config.js +6 -0
- package/dist/cli/dream.d.ts +59 -0
- package/dist/cli/dream.js +315 -0
- package/dist/cli/namespaces-tasks.js +14 -0
- package/dist/cli-registry.js +24 -1
- package/dist/config/dreaming.d.ts +82 -0
- package/dist/config/dreaming.js +195 -0
- package/dist/config/resolve.js +11 -0
- package/dist/config/schema.d.ts +4 -4
- package/dist/config/schema.js +157 -1
- package/dist/content/citation-freshness.js +6 -0
- package/dist/content/learning.d.ts +1 -0
- package/dist/content/learning.js +2 -0
- package/dist/data/access.d.ts +1 -1
- package/dist/data/access.js +3 -1
- package/dist/data/task-contract.d.ts +5 -4
- package/dist/data/tasks.d.ts +5 -0
- package/dist/data/tasks.js +28 -2
- package/dist/dream/apply.d.ts +69 -0
- package/dist/dream/apply.js +372 -0
- package/dist/dream/budget.d.ts +78 -0
- package/dist/dream/budget.js +180 -0
- package/dist/dream/collect.d.ts +86 -0
- package/dist/dream/collect.js +449 -0
- package/dist/dream/eval/dream-adapter.d.ts +16 -0
- package/dist/dream/eval/dream-adapter.js +21 -0
- package/dist/dream/eval/fixture.d.ts +53 -0
- package/dist/dream/eval/fixture.js +172 -0
- package/dist/dream/eval/index.d.ts +40 -0
- package/dist/dream/eval/index.js +78 -0
- package/dist/dream/eval/score.d.ts +34 -0
- package/dist/dream/eval/score.js +99 -0
- package/dist/dream/eval/scripted-model.d.ts +19 -0
- package/dist/dream/eval/scripted-model.js +70 -0
- package/dist/dream/pages.d.ts +68 -0
- package/dist/dream/pages.js +220 -0
- package/dist/dream/privacy.d.ts +3 -0
- package/dist/dream/privacy.js +18 -0
- package/dist/dream/prompt.d.ts +13 -0
- package/dist/dream/prompt.js +84 -0
- package/dist/dream/run.d.ts +98 -0
- package/dist/dream/run.js +317 -0
- package/dist/dream/types.d.ts +74 -0
- package/dist/dream/types.js +4 -0
- package/dist/finding/lifecycle.d.ts +2 -2
- package/dist/finding/lifecycle.js +5 -2
- package/dist/finding/versions.d.ts +4 -0
- package/dist/finding/versions.js +28 -0
- package/dist/index.js +1 -0
- package/dist/modules/registry.js +9 -7
- package/dist/project-config.d.ts +3 -0
- package/dist/task/merge-links.d.ts +38 -0
- package/dist/task/merge-links.js +45 -0
- package/dist/task/reconcile.d.ts +39 -0
- package/dist/task/reconcile.js +201 -0
- package/dist/task/report-links.d.ts +10 -0
- package/dist/task/report-links.js +47 -0
- package/dist/tools/config.js +46 -4
- package/dist/tools/dispatch.js +2 -1
- package/dist/tools/dream.d.ts +3 -0
- package/dist/tools/dream.js +123 -0
- package/dist/tools/tasks.js +4 -1
- package/package.json +1 -1
|
@@ -0,0 +1,220 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Pages: one markdown file per subject under `<store>/<project>/reference/pages/<slug>.md`.
|
|
3
|
+
*
|
|
4
|
+
* Dreaming writes these instead of growing shared files (one page per subject
|
|
5
|
+
* beats a big FINDINGS.md). A page is frontmatter (`title`, `summary`), then a
|
|
6
|
+
* body that links other pages as `[[slug]]` and cites findings as `fid:xxxxxxxx`.
|
|
7
|
+
*
|
|
8
|
+
* Search needs no extra wiring: the indexer globs every `**\/*.md` in a project
|
|
9
|
+
* (DEFAULT_INDEX_POLICY.includeGlobs) and `classifyFile` types anything under a
|
|
10
|
+
* `reference/` segment as `reference`, so a page is found like any archive doc
|
|
11
|
+
* on the next index build.
|
|
12
|
+
*/
|
|
13
|
+
import * as fs from "fs";
|
|
14
|
+
import * as path from "path";
|
|
15
|
+
import { atomicWriteText } from "../phren-paths.js";
|
|
16
|
+
import { storeAwareProjectPath } from "../store-routing.js";
|
|
17
|
+
import { withFileLock } from "../shared/governance.js";
|
|
18
|
+
import { appendAuditLog } from "../shared.js";
|
|
19
|
+
export const PAGES_DIR = path.join("reference", "pages");
|
|
20
|
+
/** A page is a summary of one subject, not an archive. Larger pages are refused. */
|
|
21
|
+
export const MAX_PAGE_BYTES = 16 * 1024;
|
|
22
|
+
const SLUG_RE = /^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$/;
|
|
23
|
+
const LINK_RE = /\[\[([^\]\n|]+)(?:\|[^\]\n]*)?\]\]/g;
|
|
24
|
+
const FID_RE = /\bfid:([a-f0-9]{8})\b/g;
|
|
25
|
+
const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
|
|
26
|
+
export class PageError extends Error {
|
|
27
|
+
constructor(message) {
|
|
28
|
+
super(message);
|
|
29
|
+
this.name = "PageError";
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
export function isValidPageSlug(slug) {
|
|
33
|
+
return SLUG_RE.test(slug);
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* Accepts a bare slug or the changeset's page reference (`reference/pages/<slug>.md`)
|
|
37
|
+
* and returns the slug. Throws on anything else, including traversal attempts.
|
|
38
|
+
*/
|
|
39
|
+
export function pageSlug(ref) {
|
|
40
|
+
const trimmed = ref.trim().replace(/\\/g, "/");
|
|
41
|
+
const m = trimmed.match(/^(?:reference\/pages\/)?([^/]+?)(?:\.md)?$/);
|
|
42
|
+
const slug = m?.[1] ?? "";
|
|
43
|
+
if (!isValidPageSlug(slug)) {
|
|
44
|
+
throw new PageError(`Invalid page "${ref}": a slug is lowercase letters, digits and dashes, at most 64 characters.`);
|
|
45
|
+
}
|
|
46
|
+
return slug;
|
|
47
|
+
}
|
|
48
|
+
function pagesDir(store, project) {
|
|
49
|
+
const dir = storeAwareProjectPath(store, project, PAGES_DIR);
|
|
50
|
+
const projectDir = storeAwareProjectPath(store, project);
|
|
51
|
+
if (!dir || !projectDir || !fs.existsSync(projectDir))
|
|
52
|
+
throw new PageError(`Project "${project}" not found in phren.`);
|
|
53
|
+
return dir;
|
|
54
|
+
}
|
|
55
|
+
function parseFrontmatter(markdown) {
|
|
56
|
+
const m = markdown.match(FRONTMATTER_RE);
|
|
57
|
+
if (!m)
|
|
58
|
+
return { fields: {}, body: markdown };
|
|
59
|
+
const fields = {};
|
|
60
|
+
for (const line of m[1].split(/\r?\n/)) {
|
|
61
|
+
const kv = line.match(/^([A-Za-z_][\w-]*):\s*(.*)$/);
|
|
62
|
+
if (kv)
|
|
63
|
+
fields[kv[1].toLowerCase()] = unquote(kv[2].trim());
|
|
64
|
+
}
|
|
65
|
+
return { fields, body: markdown.slice(m[0].length) };
|
|
66
|
+
}
|
|
67
|
+
function unquote(value) {
|
|
68
|
+
if (value.length >= 2 && ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'")))) {
|
|
69
|
+
return value.slice(1, -1);
|
|
70
|
+
}
|
|
71
|
+
return value;
|
|
72
|
+
}
|
|
73
|
+
function frontmatterValue(value) {
|
|
74
|
+
const flat = value.replace(/\s+/g, " ").trim();
|
|
75
|
+
return /[:#"'\[\]{}]|^[-?!&*|>%@`]/.test(flat) ? JSON.stringify(flat) : flat;
|
|
76
|
+
}
|
|
77
|
+
/** `[[slug]]` targets in a body, deduplicated. Invalid targets are kept verbatim so the link check reports them. */
|
|
78
|
+
export function extractPageLinks(body) {
|
|
79
|
+
const seen = new Set();
|
|
80
|
+
for (const m of body.matchAll(LINK_RE))
|
|
81
|
+
seen.add(m[1].trim());
|
|
82
|
+
return [...seen];
|
|
83
|
+
}
|
|
84
|
+
export function extractPageFids(body) {
|
|
85
|
+
const seen = new Set();
|
|
86
|
+
for (const m of body.matchAll(FID_RE))
|
|
87
|
+
seen.add(m[1]);
|
|
88
|
+
return [...seen];
|
|
89
|
+
}
|
|
90
|
+
function firstHeading(body) {
|
|
91
|
+
return body.match(/^#\s+(.+)$/m)?.[1].trim();
|
|
92
|
+
}
|
|
93
|
+
function firstParagraph(body) {
|
|
94
|
+
for (const block of body.split(/\r?\n\s*\r?\n/)) {
|
|
95
|
+
const text = block.trim();
|
|
96
|
+
if (text && !text.startsWith("#"))
|
|
97
|
+
return text.replace(/\s+/g, " ").slice(0, 200);
|
|
98
|
+
}
|
|
99
|
+
return "";
|
|
100
|
+
}
|
|
101
|
+
function parsePage(slug, file, markdown) {
|
|
102
|
+
const { fields, body } = parseFrontmatter(markdown);
|
|
103
|
+
return {
|
|
104
|
+
slug,
|
|
105
|
+
title: fields.title || firstHeading(body) || slug,
|
|
106
|
+
summary: fields.summary || firstParagraph(body),
|
|
107
|
+
links: extractPageLinks(body),
|
|
108
|
+
fids: extractPageFids(body),
|
|
109
|
+
path: file,
|
|
110
|
+
body,
|
|
111
|
+
markdown,
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Puts the markdown in page shape: frontmatter with a title and a summary
|
|
116
|
+
* (taken from the model's frontmatter, else the first heading and paragraph),
|
|
117
|
+
* an `updated` date, and the body. `links` the caller declares but the body
|
|
118
|
+
* does not mention are appended as a "Related" line so they stay visible.
|
|
119
|
+
*/
|
|
120
|
+
export function normalizePage(slug, markdown, links, now = new Date()) {
|
|
121
|
+
const { fields, body: rawBody } = parseFrontmatter(markdown.replace(/\r\n/g, "\n"));
|
|
122
|
+
let body = rawBody.trim();
|
|
123
|
+
const title = fields.title || firstHeading(body) || slug;
|
|
124
|
+
const summary = fields.summary || firstParagraph(body);
|
|
125
|
+
const inBody = new Set(extractPageLinks(body));
|
|
126
|
+
const extra = links.map((l) => l.trim()).filter((l) => l && !inBody.has(l) && l !== slug);
|
|
127
|
+
if (extra.length)
|
|
128
|
+
body += `\n\nRelated: ${[...new Set(extra)].map((l) => `[[${l}]]`).join(", ")}`;
|
|
129
|
+
const head = [
|
|
130
|
+
"---",
|
|
131
|
+
`title: ${frontmatterValue(title)}`,
|
|
132
|
+
`summary: ${frontmatterValue(summary)}`,
|
|
133
|
+
`updated: ${now.toISOString().slice(0, 10)}`,
|
|
134
|
+
"---",
|
|
135
|
+
].join("\n");
|
|
136
|
+
return `${head}\n\n${body}\n`;
|
|
137
|
+
}
|
|
138
|
+
export function listPages(store, project) {
|
|
139
|
+
const dir = pagesDir(store, project);
|
|
140
|
+
let names = [];
|
|
141
|
+
try {
|
|
142
|
+
names = fs.readdirSync(dir);
|
|
143
|
+
}
|
|
144
|
+
catch {
|
|
145
|
+
return [];
|
|
146
|
+
}
|
|
147
|
+
const pages = [];
|
|
148
|
+
for (const name of names.sort()) {
|
|
149
|
+
if (!name.endsWith(".md"))
|
|
150
|
+
continue;
|
|
151
|
+
const slug = name.slice(0, -3);
|
|
152
|
+
if (!isValidPageSlug(slug))
|
|
153
|
+
continue;
|
|
154
|
+
const file = path.join(dir, name);
|
|
155
|
+
try {
|
|
156
|
+
if (!fs.lstatSync(file).isFile())
|
|
157
|
+
continue;
|
|
158
|
+
const { body: _body, markdown: _markdown, ...meta } = parsePage(slug, file, fs.readFileSync(file, "utf8"));
|
|
159
|
+
pages.push(meta);
|
|
160
|
+
}
|
|
161
|
+
catch { /* unreadable page: skip */ }
|
|
162
|
+
}
|
|
163
|
+
return pages;
|
|
164
|
+
}
|
|
165
|
+
export function readPage(store, project, slugOrRef) {
|
|
166
|
+
const slug = pageSlug(slugOrRef);
|
|
167
|
+
const file = path.join(pagesDir(store, project), `${slug}.md`);
|
|
168
|
+
try {
|
|
169
|
+
if (!fs.lstatSync(file).isFile())
|
|
170
|
+
return null;
|
|
171
|
+
return parsePage(slug, file, fs.readFileSync(file, "utf8"));
|
|
172
|
+
}
|
|
173
|
+
catch {
|
|
174
|
+
return null;
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
/**
|
|
178
|
+
* Writes (creates or replaces) one page. The write is locked and atomic and
|
|
179
|
+
* goes to the audit log. Broken links do not stop the write; they are returned
|
|
180
|
+
* so the caller can record them beside the change.
|
|
181
|
+
*/
|
|
182
|
+
export async function writePage(store, project, slug, markdown, links) {
|
|
183
|
+
const clean = pageSlug(slug);
|
|
184
|
+
const dir = pagesDir(store, project);
|
|
185
|
+
const content = normalizePage(clean, markdown, links);
|
|
186
|
+
if (Buffer.byteLength(content, "utf8") > MAX_PAGE_BYTES) {
|
|
187
|
+
throw new PageError(`Page "${clean}" is over ${MAX_PAGE_BYTES / 1024} KB; split it into smaller subjects.`);
|
|
188
|
+
}
|
|
189
|
+
const file = path.join(dir, `${clean}.md`);
|
|
190
|
+
fs.mkdirSync(dir, { recursive: true });
|
|
191
|
+
withFileLock(file, () => {
|
|
192
|
+
try {
|
|
193
|
+
if (fs.lstatSync(file).isSymbolicLink())
|
|
194
|
+
throw new PageError(`Refusing to write through a symlink at ${file}.`);
|
|
195
|
+
}
|
|
196
|
+
catch (err) {
|
|
197
|
+
if (err instanceof PageError)
|
|
198
|
+
throw err;
|
|
199
|
+
}
|
|
200
|
+
atomicWriteText(file, content);
|
|
201
|
+
});
|
|
202
|
+
appendAuditLog(store, "write_page", `project=${project} page=${clean}`);
|
|
203
|
+
const existing = new Set(listPages(store, project).map((p) => p.slug));
|
|
204
|
+
const brokenLinks = extractPageLinks(parseFrontmatter(content).body).filter((l) => !existing.has(l));
|
|
205
|
+
return { path: file, brokenLinks };
|
|
206
|
+
}
|
|
207
|
+
/** Link check across every page of a project. Only pages with a problem are returned. */
|
|
208
|
+
export function checkPageLinks(store, project, knownFids) {
|
|
209
|
+
const pages = listPages(store, project);
|
|
210
|
+
const slugs = new Set(pages.map((p) => p.slug));
|
|
211
|
+
const fids = knownFids ? new Set(knownFids) : null;
|
|
212
|
+
const reports = [];
|
|
213
|
+
for (const page of pages) {
|
|
214
|
+
const brokenLinks = page.links.filter((l) => !slugs.has(l));
|
|
215
|
+
const unknownFids = fids ? page.fids.filter((f) => !fids.has(f)) : [];
|
|
216
|
+
if (brokenLinks.length || unknownFids.length)
|
|
217
|
+
reports.push({ slug: page.slug, brokenLinks, unknownFids });
|
|
218
|
+
}
|
|
219
|
+
return reports;
|
|
220
|
+
}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
import { redactSecretsForLog, scanForSecrets } from "../content/secrets.js";
|
|
2
|
+
/** Redact strings individually so safe surrounding structure survives. Scan the serialized
|
|
3
|
+
* whole too: credential patterns can cross field boundaries or JSON escapes. */
|
|
4
|
+
export function sanitizeDream(value) {
|
|
5
|
+
const visit = (v) => {
|
|
6
|
+
if (typeof v === "string")
|
|
7
|
+
return redactSecretsForLog(v);
|
|
8
|
+
if (Array.isArray(v))
|
|
9
|
+
return v.map(visit);
|
|
10
|
+
if (v && typeof v === "object")
|
|
11
|
+
return Object.fromEntries(Object.entries(v).map(([k, x]) => [redactSecretsForLog(k), visit(x)]));
|
|
12
|
+
return v;
|
|
13
|
+
};
|
|
14
|
+
const safe = visit(value);
|
|
15
|
+
if (scanForSecrets(JSON.stringify(safe)))
|
|
16
|
+
throw new Error("Dream data withheld: secret detected after redaction.");
|
|
17
|
+
return safe;
|
|
18
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { DreamInputs } from "./collect.js";
|
|
2
|
+
import type { DreamOp } from "./types.js";
|
|
3
|
+
export declare const DREAM_PHASES: readonly ["capture", "correct", "organize", "prune"];
|
|
4
|
+
export type DreamPhase = typeof DREAM_PHASES[number];
|
|
5
|
+
/** Which operations each phase allows. An op is allowed when any enabled phase lists it. */
|
|
6
|
+
export declare const PHASE_OPS: Record<DreamPhase, DreamOp[]>;
|
|
7
|
+
export declare const CHANGESET_SCHEMA = "{\n \"changes\": DreamChange[], // at most MAX_CHANGES; fewer is better than padding\n \"notes\": string // one or two sentences: what you noticed, what you left alone and why\n}\nDreamEvidence = { \"kind\": \"transcript\"|\"code\"|\"git\"|\"finding\", \"ref\": string, \"quote\"?: string }\n // ref: transcript \u2192 \"<session>#t<turn>\" exactly as shown; code \u2192 \"path:line\"; git \u2192 short sha; finding \u2192 fid\nDreamChange =\n | { \"op\": \"add_finding\", \"text\": string, \"findingType\"?: \"decision\"|\"pitfall\"|\"pattern\"|\"bug\", \"topic\"?: string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"supersede\", \"findingId\": string, \"newText\": string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"retract\", \"findingId\": string, \"reason\": string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"edit\", \"findingId\": string, \"newText\": string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"merge\", \"findingIds\": string[], \"newText\": string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"move_topic\", \"findingId\": string, \"topic\": string }\n | { \"op\": \"promote_truth\", \"findingId\": string, \"text\": string, \"evidence\": DreamEvidence[] }\n | { \"op\": \"demote_truth\", \"truth\": string, \"reason\": string }\n | { \"op\": \"write_page\", \"page\": \"reference/pages/<slug>.md\", \"markdown\": string, \"links\": string[] }\n | { \"op\": \"link\", \"findingId\": string, \"entity\": string }\nfindingId / findingIds are fids from the findings list (8 hex characters). demote_truth.truth is the truth's text as listed.\nwrite_page markdown starts with frontmatter (title, summary), then the body; cite findings as fid:xxxxxxxx and other pages as [[slug]]; links lists those slugs.";
|
|
8
|
+
export interface DreamPromptOptions {
|
|
9
|
+
phases: DreamPhase[];
|
|
10
|
+
maxChanges: number;
|
|
11
|
+
now: Date;
|
|
12
|
+
}
|
|
13
|
+
export declare function buildDreamPrompt(inputs: DreamInputs, options: DreamPromptOptions): string;
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// The dreaming prompt. It tells the model what this memory is for and what makes it
|
|
2
|
+
// useful, then hands it the evidence and the current memory, and asks for a changeset.
|
|
3
|
+
// Purpose-led on purpose: procedural rules ("record only failures") make worse memory.
|
|
4
|
+
import { sanitizeDream } from "./privacy.js";
|
|
5
|
+
import { scanForSecrets } from "../content/secrets.js";
|
|
6
|
+
export const DREAM_PHASES = ["capture", "correct", "organize", "prune"];
|
|
7
|
+
/** Which operations each phase allows. An op is allowed when any enabled phase lists it. */
|
|
8
|
+
export const PHASE_OPS = {
|
|
9
|
+
capture: ["add_finding"],
|
|
10
|
+
correct: ["supersede", "retract", "edit"],
|
|
11
|
+
organize: ["merge", "move_topic", "write_page", "link", "promote_truth"],
|
|
12
|
+
prune: ["retract", "merge", "demote_truth"],
|
|
13
|
+
};
|
|
14
|
+
const PHASE_PURPOSE = {
|
|
15
|
+
capture: "Capture: knowledge the sessions produced that a future session would otherwise have to rediscover (decisions and their reasons, pitfalls, working fixes, conventions the owner stated) and that is not already saved.",
|
|
16
|
+
correct: "Correct: saved findings that the sessions, the code or the git history now contradict or make outdated. Supersede when there is a newer truth, edit when the wording is wrong but the point stands, retract when it was simply wrong.",
|
|
17
|
+
organize: "Organize: one subject per page, duplicates merged, findings filed under the right topic, fragments linked, and the few facts every session truly needs promoted to truths.",
|
|
18
|
+
prune: "Prune: what no longer earns its place. Retract the obsolete, merge the repetitive, and demote truths when the always-injected layer is over its budget.",
|
|
19
|
+
};
|
|
20
|
+
export const CHANGESET_SCHEMA = `{
|
|
21
|
+
"changes": DreamChange[], // at most MAX_CHANGES; fewer is better than padding
|
|
22
|
+
"notes": string // one or two sentences: what you noticed, what you left alone and why
|
|
23
|
+
}
|
|
24
|
+
DreamEvidence = { "kind": "transcript"|"code"|"git"|"finding", "ref": string, "quote"?: string }
|
|
25
|
+
// ref: transcript → "<session>#t<turn>" exactly as shown; code → "path:line"; git → short sha; finding → fid
|
|
26
|
+
DreamChange =
|
|
27
|
+
| { "op": "add_finding", "text": string, "findingType"?: "decision"|"pitfall"|"pattern"|"bug", "topic"?: string, "evidence": DreamEvidence[] }
|
|
28
|
+
| { "op": "supersede", "findingId": string, "newText": string, "evidence": DreamEvidence[] }
|
|
29
|
+
| { "op": "retract", "findingId": string, "reason": string, "evidence": DreamEvidence[] }
|
|
30
|
+
| { "op": "edit", "findingId": string, "newText": string, "evidence": DreamEvidence[] }
|
|
31
|
+
| { "op": "merge", "findingIds": string[], "newText": string, "evidence": DreamEvidence[] }
|
|
32
|
+
| { "op": "move_topic", "findingId": string, "topic": string }
|
|
33
|
+
| { "op": "promote_truth", "findingId": string, "text": string, "evidence": DreamEvidence[] }
|
|
34
|
+
| { "op": "demote_truth", "truth": string, "reason": string }
|
|
35
|
+
| { "op": "write_page", "page": "reference/pages/<slug>.md", "markdown": string, "links": string[] }
|
|
36
|
+
| { "op": "link", "findingId": string, "entity": string }
|
|
37
|
+
findingId / findingIds are fids from the findings list (8 hex characters). demote_truth.truth is the truth's text as listed.
|
|
38
|
+
write_page markdown starts with frontmatter (title, summary), then the body; cite findings as fid:xxxxxxxx and other pages as [[slug]]; links lists those slugs.`;
|
|
39
|
+
function section(title, body) {
|
|
40
|
+
return `## ${title}\n\n${body.trim() || "(none)"}\n`;
|
|
41
|
+
}
|
|
42
|
+
export function buildDreamPrompt(inputs, options) {
|
|
43
|
+
inputs = sanitizeDream(inputs);
|
|
44
|
+
const phases = options.phases.length ? options.phases : [...DREAM_PHASES];
|
|
45
|
+
const allowed = [...new Set(phases.flatMap(phase => PHASE_OPS[phase]))];
|
|
46
|
+
const budget = inputs.budget;
|
|
47
|
+
const kb = (bytes) => `${(bytes / 1024).toFixed(1)} KB`;
|
|
48
|
+
const budgetLine = budget.over
|
|
49
|
+
? `The always-injected layer is ${kb(budget.sizeBytes)}, over its ${kb(budget.budgetBytes)} budget. Demote until it fits; least recently cited first: ${budget.candidates.slice(0, 10).map(c => JSON.stringify(c)).join("; ") || "(no candidates listed)"}.`
|
|
50
|
+
: `The always-injected layer is ${kb(budget.sizeBytes)} of its ${kb(budget.budgetBytes)} budget. A promotion that would push it over needs a matching demotion in the same changeset.`;
|
|
51
|
+
const transcripts = inputs.transcripts.map(t => `### ${t.source} session ${t.session} (${t.cwd}, ${t.first} → ${t.last}${t.trimmed ? ", oldest turns trimmed" : ""})\n${t.text}`).join("\n\n");
|
|
52
|
+
const findings = inputs.findings.map(f => `- fid:${f.fid} [${f.date}${f.status !== "active" ? `, ${f.status}` : ""}] ${f.text}${f.citation ? ` (cites ${f.citation})` : ""}`).join("\n");
|
|
53
|
+
const prompt = [
|
|
54
|
+
`You are dreaming for the Phren project "${inputs.project}": an offline pass between sessions that reorganizes the project's memory. It is ${options.now.toISOString()}.`,
|
|
55
|
+
"",
|
|
56
|
+
section("What this memory is for", `
|
|
57
|
+
Coding agents start every session knowing nothing. This memory is what lets the next session start where the last one ended: why things are the way they are, what was tried and failed, what the owner decided, what will bite you. It is read by agents, so it should be true, specific and short.
|
|
58
|
+
|
|
59
|
+
What good memory looks like:
|
|
60
|
+
- It records what the environment can't show. Code, file listings, git history and current screen state can be read fresh at any time and go stale when copied; the reasons behind them, decisions, dead ends and the owner's preferences cannot.
|
|
61
|
+
- It is true. A wrong note does more harm than a missing one, because agents trust it. The transcripts below are what actually happened; where they, the code or git contradict a saved finding, the transcript is the better witness, and the finding should be corrected.
|
|
62
|
+
- The always-injected layer (truths) is small. Everything in it reaches every session, including its errors, so it holds only what nearly every session needs.
|
|
63
|
+
- One page per subject beats a long shared file. Related findings belong together under a topic or on a page that links to the others.
|
|
64
|
+
- It does not bloat. Merging two notes into one better note is progress; restating what is already saved is not.
|
|
65
|
+
|
|
66
|
+
Be selective. Changing nothing is a fine outcome when the memory is already right. Every change that asserts something must cite evidence from the material below: the session and turn, a path:line you read, a commit, or an existing fid. You may read files in the working directory to check a claim against the code; do not edit anything.`),
|
|
67
|
+
section("This pass", `
|
|
68
|
+
${phases.map(phase => `- ${PHASE_PURPOSE[phase]}`).join("\n")}
|
|
69
|
+
|
|
70
|
+
Allowed operations: ${allowed.join(", ")}. At most ${options.maxChanges} changes.
|
|
71
|
+
${budgetLine}`),
|
|
72
|
+
section("Earlier dreams (journal)", inputs.journal.join("\n")),
|
|
73
|
+
section(`Sessions ${inputs.from} → ${inputs.to}`, `${transcripts}${inputs.transcriptsDropped ? `\n\n(${inputs.transcriptsDropped} older sessions left out for length)` : ""}`),
|
|
74
|
+
section("Saved findings", findings),
|
|
75
|
+
section("Truths (always injected)", inputs.truths.map(t => `- ${t}`).join("\n")),
|
|
76
|
+
section("Topics", inputs.topics.map(t => `- ${t.slug}: ${t.label}`).join("\n")),
|
|
77
|
+
section("Pages", inputs.pages.map(p => `- ${p.slug}: ${p.title}${p.summary ? ` — ${p.summary}` : ""}`).join("\n")),
|
|
78
|
+
section(`Recent commits${inputs.repoDir ? ` (${inputs.repoDir})` : ""}`, inputs.gitLog.join("\n")),
|
|
79
|
+
section("Answer", `Reply with one JSON object and nothing else (no prose, no code fence), in this shape:\n\n${CHANGESET_SCHEMA.replace("MAX_CHANGES", String(options.maxChanges))}`),
|
|
80
|
+
].join("\n");
|
|
81
|
+
if (scanForSecrets(prompt))
|
|
82
|
+
throw new Error("Dream prompt withheld: secret detected.");
|
|
83
|
+
return prompt;
|
|
84
|
+
}
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
import { type DreamCounts, type DreamDrop, type DreamMode, type DreamOutcome } from "./apply.js";
|
|
2
|
+
import { type CollectOptions } from "./collect.js";
|
|
3
|
+
import { type DreamPhase } from "./prompt.js";
|
|
4
|
+
import type { DreamChange, DreamChangeset } from "./types.js";
|
|
5
|
+
export interface DreamConfig {
|
|
6
|
+
enabled: boolean;
|
|
7
|
+
mode: DreamMode;
|
|
8
|
+
cadence: "nightly" | "idle" | "weekly" | "manual";
|
|
9
|
+
window: string;
|
|
10
|
+
idleMinutes: number;
|
|
11
|
+
lookbackHours: number;
|
|
12
|
+
maxChanges: number;
|
|
13
|
+
injectBudgetKB: number;
|
|
14
|
+
phases: DreamPhase[];
|
|
15
|
+
model: string;
|
|
16
|
+
}
|
|
17
|
+
export declare const DREAM_CONFIG_DEFAULTS: DreamConfig;
|
|
18
|
+
/** Coerce raw values (from the `dreaming` config domain or a caller) onto the defaults; anything malformed falls back. */
|
|
19
|
+
export declare function normalizeDreamConfig(raw: Record<string, unknown>): DreamConfig;
|
|
20
|
+
/** The project's resolved `dreaming.*` settings (defaults → global → project), via the shared config resolver. */
|
|
21
|
+
export declare function readDreamConfig(phrenPath: string, project: string): DreamConfig;
|
|
22
|
+
/** The JSON object in a model reply, tolerating a code fence or stray prose around it. */
|
|
23
|
+
export declare function parseChangesetJson(output: string): {
|
|
24
|
+
ok: true;
|
|
25
|
+
value: {
|
|
26
|
+
changes: unknown[];
|
|
27
|
+
notes: string;
|
|
28
|
+
};
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
error: string;
|
|
32
|
+
};
|
|
33
|
+
export interface ValidationContext {
|
|
34
|
+
fids: Set<string>;
|
|
35
|
+
truths: string[];
|
|
36
|
+
topics: Set<string>;
|
|
37
|
+
phases: DreamPhase[];
|
|
38
|
+
maxChanges: number;
|
|
39
|
+
}
|
|
40
|
+
/** Keep the well-formed, allowed, evidenced changes up to maxChanges; say why each other one was dropped. */
|
|
41
|
+
export declare function validateChanges(rawChanges: unknown[], ctx: ValidationContext): {
|
|
42
|
+
changes: DreamChange[];
|
|
43
|
+
dropped: DreamDrop[];
|
|
44
|
+
};
|
|
45
|
+
export interface DreamRunnerRequest {
|
|
46
|
+
prompt: string;
|
|
47
|
+
cwd: string;
|
|
48
|
+
model?: string;
|
|
49
|
+
timeoutSeconds: number;
|
|
50
|
+
signal?: AbortSignal;
|
|
51
|
+
}
|
|
52
|
+
export interface DreamRunnerResult {
|
|
53
|
+
ok: boolean;
|
|
54
|
+
output: string;
|
|
55
|
+
model?: string;
|
|
56
|
+
costUSD?: number;
|
|
57
|
+
durationMs?: number;
|
|
58
|
+
}
|
|
59
|
+
/** Runs the model once. The default is the project's helper (`claude -p`, read-only). */
|
|
60
|
+
export type DreamRunner = (request: DreamRunnerRequest, project: string, phrenPath: string) => Promise<DreamRunnerResult>;
|
|
61
|
+
export type DreamStatus = "ok" | "disabled" | "busy" | "empty" | "failed";
|
|
62
|
+
export interface DreamOptions {
|
|
63
|
+
trigger?: "manual" | "scheduled";
|
|
64
|
+
dryRun?: boolean;
|
|
65
|
+
mode?: DreamMode;
|
|
66
|
+
now?: Date;
|
|
67
|
+
/** Run even when dreaming is disabled, or when nothing happened in the window (a manual `--force`). */
|
|
68
|
+
force?: boolean;
|
|
69
|
+
phrenPath?: string;
|
|
70
|
+
runner?: DreamRunner;
|
|
71
|
+
/** Overrides on the resolved config (tests, CLI flags). */
|
|
72
|
+
config?: Partial<DreamConfig>;
|
|
73
|
+
/** Overrides on collection (tests: transcript roots, project folders, git). */
|
|
74
|
+
collect?: Partial<Omit<CollectOptions, "from" | "to">>;
|
|
75
|
+
timeoutSeconds?: number;
|
|
76
|
+
signal?: AbortSignal;
|
|
77
|
+
}
|
|
78
|
+
export interface DreamResult {
|
|
79
|
+
status: DreamStatus;
|
|
80
|
+
project: string;
|
|
81
|
+
mode: DreamMode;
|
|
82
|
+
dryRun: boolean;
|
|
83
|
+
runId?: string;
|
|
84
|
+
message: string;
|
|
85
|
+
warnings?: string[];
|
|
86
|
+
changeset?: DreamChangeset;
|
|
87
|
+
outcomes: DreamOutcome[];
|
|
88
|
+
dropped: DreamDrop[];
|
|
89
|
+
counts?: DreamCounts;
|
|
90
|
+
/** dreams/<runId>.json, when recorded. */
|
|
91
|
+
record?: string;
|
|
92
|
+
model?: string;
|
|
93
|
+
costUSD?: number;
|
|
94
|
+
}
|
|
95
|
+
export declare const defaultDreamRunner: DreamRunner;
|
|
96
|
+
export declare function newRunId(now: Date): string;
|
|
97
|
+
export declare function dreamLockPath(phrenPath: string, project: string): string;
|
|
98
|
+
export declare function dream(project: string, opts?: DreamOptions): Promise<DreamResult>;
|