@joe-broadhead/opencode-mem 0.11.3 → 0.12.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.
- package/CHANGELOG.md +29 -0
- package/docs/agent-instructions.md +3 -2
- package/docs/agent-protocol.md +6 -5
- package/package.json +264 -2
- package/src/call-shapes.js +0 -4
- package/src/protocol.js +20 -11
- package/src/tools/commitments.js +1 -1
- package/src/tools/index.js +11 -18
- package/src/tools/page.js +40 -14
- package/src/tools/recall.js +1 -1
- package/src/tools/share.js +1 -1
- package/src/tools/wiki.js +13 -3
- package/src/views/contracts.js +29 -0
- package/src/views/receipt.js +28 -11
- package/src/views/records-reads.js +102 -0
- package/src/wiki-ingest.js +70 -15
- package/src/wiki-queue.js +252 -0
- package/views/remembered.html +7 -4
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
import fs from "node:fs"
|
|
2
|
+
import path from "node:path"
|
|
3
|
+
import { createHash, randomBytes } from "node:crypto"
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* The durable queue of wiki writes the hub refused because it was ingesting
|
|
7
|
+
* (jelly #89, 0.11.4). A write held only in the engine's memory dies with it,
|
|
8
|
+
* and that is the silent loss the ask exists to end: each one is written here
|
|
9
|
+
* **before** the tool answers `state: queued`, and replayed at the next start.
|
|
10
|
+
*
|
|
11
|
+
* - **Where.** One file per write in `wiki-queue/` under the plugin's own state
|
|
12
|
+
* directory (the one `config.stateDir` names, beside the spool and the pause
|
|
13
|
+
* file). Each file holds the write's body, so it is owner-only (`0600`), in a
|
|
14
|
+
* `0700` directory, and its content never goes into a log line.
|
|
15
|
+
* - **Bounds.** At most `WIKI_QUEUE_MAX_ENTRIES` writes and
|
|
16
|
+
* `WIKI_QUEUE_MAX_BYTES` of bodies (8 MiB); a write that would pass either
|
|
17
|
+
* is not saved, and the answer is `state: refused` rather than `queued`.
|
|
18
|
+
* - **Atomic.** Each file is written as a private temp file in the same
|
|
19
|
+
* directory, fsynced, renamed into place, and the directory is fsynced, so a
|
|
20
|
+
* crash leaves no file or the whole one, never a torn one. One file per
|
|
21
|
+
* write also means two engine processes on one machine never overwrite each
|
|
22
|
+
* other's queue: an append only ever creates its own file.
|
|
23
|
+
* - **Once.** A file is removed only after the hub accepted the write. A
|
|
24
|
+
* crash between the accept and the removal leaves it, and the replay checks
|
|
25
|
+
* the wiki's own file (its filename and a digest of the body) before
|
|
26
|
+
* writing, so the same body is never written twice.
|
|
27
|
+
*/
|
|
28
|
+
|
|
29
|
+
export const WIKI_QUEUE_DIR = "wiki-queue"
|
|
30
|
+
/** Writes the queue holds. */
|
|
31
|
+
export const WIKI_QUEUE_MAX_ENTRIES = 100
|
|
32
|
+
/** Bodies the queue holds, together. */
|
|
33
|
+
export const WIKI_QUEUE_MAX_BYTES = 8 * 1024 * 1024
|
|
34
|
+
|
|
35
|
+
const ENTRY = /^wq_[a-f0-9]{16}\.json$/
|
|
36
|
+
|
|
37
|
+
/** A queue failure the answer can name without repeating the file system's words. */
|
|
38
|
+
export class WikiQueueError extends Error {
|
|
39
|
+
constructor(code, message) {
|
|
40
|
+
super(message)
|
|
41
|
+
this.name = "WikiQueueError"
|
|
42
|
+
this.code = code
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** A body's key, so a replay never writes one the wiki already holds. */
|
|
47
|
+
export function wikiWriteDigest(content) {
|
|
48
|
+
return createHash("sha256").update(String(content ?? ""), "utf8").digest("hex")
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** The scope a replay needs, without a session or any text. */
|
|
52
|
+
function scopeOf(scope) {
|
|
53
|
+
const kept = {}
|
|
54
|
+
for (const key of ["team_id", "space_id", "user_id", "agent_id"]) {
|
|
55
|
+
const value = String(scope?.[key] ?? "").trim()
|
|
56
|
+
if (value) kept[key] = value
|
|
57
|
+
}
|
|
58
|
+
return kept
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function validEntry(entry) {
|
|
62
|
+
return Boolean(
|
|
63
|
+
entry &&
|
|
64
|
+
typeof entry.id === "string" &&
|
|
65
|
+
ENTRY.test(`${entry.id}.json`) &&
|
|
66
|
+
typeof entry.wiki === "string" &&
|
|
67
|
+
entry.wiki &&
|
|
68
|
+
typeof entry.file === "string" &&
|
|
69
|
+
entry.file &&
|
|
70
|
+
typeof entry.content === "string" &&
|
|
71
|
+
typeof entry.digest === "string" &&
|
|
72
|
+
entry.digest,
|
|
73
|
+
)
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* @param {{ stateDir?: string, log?: any }} input
|
|
78
|
+
*/
|
|
79
|
+
export function createWikiQueue({ stateDir = "", log = null } = {}) {
|
|
80
|
+
const base = String(stateDir ?? "")
|
|
81
|
+
const dir = base ? path.join(base, WIKI_QUEUE_DIR) : ""
|
|
82
|
+
let ensured = false
|
|
83
|
+
/** This process's append counter, so entries of one millisecond keep their order. */
|
|
84
|
+
let sequence = 0
|
|
85
|
+
|
|
86
|
+
/** Create the queue directory when it is missing; never override an operator's mode. */
|
|
87
|
+
function ensureDir() {
|
|
88
|
+
if (ensured) return
|
|
89
|
+
const existed = fs.existsSync(dir)
|
|
90
|
+
fs.mkdirSync(dir, { recursive: true, mode: 0o700 })
|
|
91
|
+
if (!existed) {
|
|
92
|
+
try {
|
|
93
|
+
fs.chmodSync(dir, 0o700)
|
|
94
|
+
} catch {
|
|
95
|
+
/* best effort on platforms without POSIX modes */
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
ensured = true
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/** Make a rename or a new file in the directory survive a crash. Best effort. */
|
|
102
|
+
function syncDir() {
|
|
103
|
+
let fd
|
|
104
|
+
try {
|
|
105
|
+
fd = fs.openSync(dir, "r")
|
|
106
|
+
fs.fsyncSync(fd)
|
|
107
|
+
} catch {
|
|
108
|
+
/* not supported on every platform (Windows) */
|
|
109
|
+
} finally {
|
|
110
|
+
if (fd !== undefined) {
|
|
111
|
+
try {
|
|
112
|
+
fs.closeSync(fd)
|
|
113
|
+
} catch {
|
|
114
|
+
/* ignore */
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
/** Every entry file, newest last, read from disk so a second process's are seen. */
|
|
121
|
+
function read() {
|
|
122
|
+
if (!dir) return []
|
|
123
|
+
ensureDir()
|
|
124
|
+
let names
|
|
125
|
+
try {
|
|
126
|
+
names = fs.readdirSync(dir)
|
|
127
|
+
} catch (error) {
|
|
128
|
+
if (error?.code !== "ENOENT") log?.debug?.("the wiki write queue is unreadable", { error: String(error?.code ?? error) })
|
|
129
|
+
return []
|
|
130
|
+
}
|
|
131
|
+
const entries = []
|
|
132
|
+
for (const name of names) {
|
|
133
|
+
if (!ENTRY.test(name)) continue
|
|
134
|
+
let parsed
|
|
135
|
+
try {
|
|
136
|
+
parsed = JSON.parse(fs.readFileSync(path.join(dir, name), "utf8"))
|
|
137
|
+
} catch {
|
|
138
|
+
log?.warn?.("a wiki write queue entry is unreadable and is left alone", { entry: name })
|
|
139
|
+
continue
|
|
140
|
+
}
|
|
141
|
+
if (!validEntry(parsed)) {
|
|
142
|
+
log?.warn?.("a wiki write queue entry is not one, and is left alone", { entry: name })
|
|
143
|
+
continue
|
|
144
|
+
}
|
|
145
|
+
entries.push({
|
|
146
|
+
id: parsed.id,
|
|
147
|
+
wiki: parsed.wiki,
|
|
148
|
+
file: parsed.file,
|
|
149
|
+
digest: parsed.digest,
|
|
150
|
+
bytes: Number(parsed.bytes) || Buffer.byteLength(parsed.content),
|
|
151
|
+
scope: scopeOf(parsed.scope),
|
|
152
|
+
content: parsed.content,
|
|
153
|
+
at: typeof parsed.at === "string" ? parsed.at : "",
|
|
154
|
+
seq: Number(parsed.seq) || 0,
|
|
155
|
+
})
|
|
156
|
+
}
|
|
157
|
+
// The order the writes were queued: time, then this process's own counter.
|
|
158
|
+
entries.sort((a, b) => String(a.at).localeCompare(String(b.at)) || a.seq - b.seq || a.id.localeCompare(b.id))
|
|
159
|
+
return entries.map(({ seq: _seq, ...entry }) => entry)
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
/** One entry, atomically: temp file, fsync, rename, directory fsync. */
|
|
163
|
+
function saveFile(entry) {
|
|
164
|
+
ensureDir()
|
|
165
|
+
const target = path.join(dir, `${entry.id}.json`)
|
|
166
|
+
const temp = path.join(dir, `.${entry.id}.${process.pid}-${randomBytes(4).toString("hex")}.tmp`)
|
|
167
|
+
const body = Buffer.from(JSON.stringify(entry, null, 2))
|
|
168
|
+
let fd
|
|
169
|
+
try {
|
|
170
|
+
fd = fs.openSync(temp, "wx", 0o600)
|
|
171
|
+
try {
|
|
172
|
+
fs.fchmodSync(fd, 0o600)
|
|
173
|
+
} catch {
|
|
174
|
+
/* best effort on platforms without POSIX modes */
|
|
175
|
+
}
|
|
176
|
+
let offset = 0
|
|
177
|
+
while (offset < body.length) offset += fs.writeSync(fd, body, offset, body.length - offset)
|
|
178
|
+
fs.fsyncSync(fd)
|
|
179
|
+
fs.closeSync(fd)
|
|
180
|
+
fd = undefined
|
|
181
|
+
fs.renameSync(temp, target)
|
|
182
|
+
syncDir()
|
|
183
|
+
} catch (error) {
|
|
184
|
+
if (fd !== undefined) {
|
|
185
|
+
try {
|
|
186
|
+
fs.closeSync(fd)
|
|
187
|
+
} catch {
|
|
188
|
+
/* ignore */
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
try {
|
|
192
|
+
fs.unlinkSync(temp)
|
|
193
|
+
} catch {
|
|
194
|
+
/* the temp file never existed */
|
|
195
|
+
}
|
|
196
|
+
throw new WikiQueueError("queue_io", `the queue could not be written (${String(error?.code ?? error?.message ?? error)})`)
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
return {
|
|
201
|
+
/** Every waiting write, in the order it was queued. */
|
|
202
|
+
entries() {
|
|
203
|
+
return read()
|
|
204
|
+
},
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Save one write, or throw `queue_full` / `queue_io`. The entry is on disk
|
|
208
|
+
* when this returns.
|
|
209
|
+
*/
|
|
210
|
+
append({ wikiID, scope, filename, content }) {
|
|
211
|
+
const body = String(content ?? "")
|
|
212
|
+
const bytes = Buffer.byteLength(body)
|
|
213
|
+
const waiting = read()
|
|
214
|
+
if (waiting.length >= WIKI_QUEUE_MAX_ENTRIES) throw new WikiQueueError("queue_full", "the wiki write queue is full")
|
|
215
|
+
if (waiting.reduce((sum, entry) => sum + entry.bytes, 0) + bytes > WIKI_QUEUE_MAX_BYTES) {
|
|
216
|
+
throw new WikiQueueError("queue_full", "the wiki write queue holds too many bytes")
|
|
217
|
+
}
|
|
218
|
+
const entry = {
|
|
219
|
+
id: `wq_${randomBytes(8).toString("hex")}`,
|
|
220
|
+
wiki: String(wikiID),
|
|
221
|
+
file: String(filename),
|
|
222
|
+
digest: wikiWriteDigest(body),
|
|
223
|
+
bytes,
|
|
224
|
+
scope: scopeOf(scope),
|
|
225
|
+
content: body,
|
|
226
|
+
at: new Date().toISOString(),
|
|
227
|
+
seq: (sequence += 1),
|
|
228
|
+
}
|
|
229
|
+
saveFile(entry)
|
|
230
|
+
const { seq: _seq, ...saved } = entry
|
|
231
|
+
return saved
|
|
232
|
+
},
|
|
233
|
+
|
|
234
|
+
/**
|
|
235
|
+
* Forget a write the hub accepted. A removal the disk refuses is logged
|
|
236
|
+
* and left to the replay's digest check, which writes nothing twice.
|
|
237
|
+
*/
|
|
238
|
+
remove(id) {
|
|
239
|
+
if (!dir || !ENTRY.test(`${id}.json`)) return
|
|
240
|
+
try {
|
|
241
|
+
fs.unlinkSync(path.join(dir, `${id}.json`))
|
|
242
|
+
} catch (error) {
|
|
243
|
+
if (error?.code !== "ENOENT") log?.warn?.("a wiki write could not be removed from the queue; the replay will skip it by its content", { error: String(error?.code ?? error) })
|
|
244
|
+
}
|
|
245
|
+
},
|
|
246
|
+
|
|
247
|
+
/** A write with the same file and body already waits here. */
|
|
248
|
+
has(wikiID, filename, digest) {
|
|
249
|
+
return read().some((entry) => entry.wiki === wikiID && entry.file === filename && entry.digest === digest)
|
|
250
|
+
},
|
|
251
|
+
}
|
|
252
|
+
}
|
package/views/remembered.html
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
<html lang="en-GB">
|
|
3
3
|
<head>
|
|
4
4
|
<meta charset="utf-8">
|
|
5
|
-
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-5dtPKkjegOPG8bawdSzGBjixnIaSCLYcZOUAwbRWFAc=' 'sha256-
|
|
5
|
+
<meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'sha256-5dtPKkjegOPG8bawdSzGBjixnIaSCLYcZOUAwbRWFAc=' 'sha256-c1C+7C6yrEXPJonY9V4OSkmT3TOMQFh7iSU/03IUBk0='; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'">
|
|
6
6
|
<title>Saved to memory</title>
|
|
7
7
|
<style>
|
|
8
8
|
:root { color: var(--jelly-text, CanvasText); background: var(--jelly-surface, Canvas); font: 14px/1.5 var(--jelly-font, system-ui, sans-serif); }
|
|
@@ -109,20 +109,23 @@ jellyView().then(async (view) => {
|
|
|
109
109
|
const data = result?.metadata?.memoryReceipt;
|
|
110
110
|
const receipt = document.getElementById("receipt");
|
|
111
111
|
const where = document.getElementById("where");
|
|
112
|
-
const ACTIONS = ["remembered", "corrected", "confirmed", "retired", "restored", "committed"];
|
|
112
|
+
const ACTIONS = ["remembered", "corrected", "confirmed", "retired", "restored", "committed", "written"];
|
|
113
113
|
const yes = data && data.v === 1 && typeof data.id === "string" && ACTIONS.includes(data.action);
|
|
114
114
|
if (!yes) {
|
|
115
115
|
receipt.textContent = "Receipt details are not available for this result.";
|
|
116
116
|
return;
|
|
117
117
|
}
|
|
118
|
-
const said = { remembered: "Remembered", corrected: "Corrected", confirmed: "Confirmed", retired: "Retired", restored: "Restored", committed: "Commitment added" }[data.action];
|
|
118
|
+
const said = { remembered: "Remembered", corrected: "Corrected", confirmed: "Confirmed", retired: "Retired", restored: "Restored", committed: "Commitment added", written: "Page written" }[data.action];
|
|
119
119
|
// Memory's own text is data: it is set as text, never as markup.
|
|
120
120
|
receipt.textContent = typeof data.title === "string" && data.title ? `${said}: ${data.title}` : said;
|
|
121
121
|
receipt.className = "";
|
|
122
122
|
const parts = [data.kind, data.type, data.status].filter((part) => typeof part === "string" && part);
|
|
123
123
|
const space = data.space;
|
|
124
124
|
const at = space && typeof space.name === "string" && space.name ? `in ${space.name}` : "";
|
|
125
|
-
|
|
125
|
+
// A page write names its path and version; a memory or a commitment has neither.
|
|
126
|
+
const where_ = typeof data.path === "string" && data.path ? data.path : "";
|
|
127
|
+
const version = Number.isSafeInteger(data.version) && data.version > 0 ? `version ${data.version}` : "";
|
|
128
|
+
where.textContent = [where_, parts.join(" · "), version, at].filter(Boolean).join(" ");
|
|
126
129
|
where.className = "muted";
|
|
127
130
|
}).catch(() => { document.getElementById("receipt").textContent = "Receipt details are not available for this result."; });
|
|
128
131
|
</script>
|