@joe-broadhead/opencode-mem 0.11.2 → 0.11.4

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/src/tools/wiki.js CHANGED
@@ -2,7 +2,11 @@ import { quarantineNote, quarantineText } from "../curation.js"
2
2
  import { RECORDS_FILE, RECORDS_WIKI, isRecordsText } from "../records.js"
3
3
  import { codedMessage } from "../errors.js"
4
4
  import { errorMessage, neutralizeFenceClosers, oneLine, redactSecrets } from "../util.js"
5
+ import { createWikiIngest, WIKI_INGEST_DELAY_MS } from "../wiki-ingest.js"
6
+ import { createWikiQueue } from "../wiki-queue.js"
7
+ import { wikiCache, wikiErrorOf, wikiStateOf } from "../wiki-state.js"
5
8
  import { discoverKnowledge, isRecordsWikiName, searchKnowledge } from "./knowledge.js"
9
+ import { failedAnswer, refusedAnswer, wikiPlace, withWriteState } from "../views/write-state.js"
6
10
 
7
11
  const MAX_FILE_BYTES = 512 * 1024
8
12
  const DEFAULT_FILE = "README.md"
@@ -81,6 +85,37 @@ export function registerWiki(editor, toolkit) {
81
85
  runtime,
82
86
  } = toolkit
83
87
 
88
+ // 0.11.3 (jelly's #89 ask A4): a write's answer opens with its state line,
89
+ // and a refusal opens with `state: refused` and names nothing.
90
+ const refuse = (content) => refusedAnswer(text(content))
91
+ const failedCall = (message) => failedAnswer(fail(message))
92
+
93
+ /** The last ready page set of each wiki, and why an ingest failed (jelly #89 A1, A2). */
94
+ const cache = wikiCache({ stateDir: config.stateDir, log })
95
+
96
+ /**
97
+ * The write path (jelly #89 A3): every write schedules one debounced ingest,
98
+ * and a write the hub refuses during an ingest is queued, never refused.
99
+ * `toolkit.wikiIngest` lets the engine stop its timers with the tool set's.
100
+ */
101
+ const ingest =
102
+ toolkit.wikiIngest ??
103
+ createWikiIngest({
104
+ backend,
105
+ log,
106
+ delay: config.wikiIngestMs ?? WIKI_INGEST_DELAY_MS,
107
+ // Durable before the answer says queued (jelly #89, 0.11.4): the entry
108
+ // outlives the engine, and the file holds the write's body, owner-only,
109
+ // inside Memory's state directory.
110
+ queue: createWikiQueue({ stateDir: config.stateDir, log }),
111
+ rememberError: (wikiID, message) => cache.rememberError(wikiID, message),
112
+ clearError: (wikiID) => cache.clearError(wikiID),
113
+ rememberPending: (wikiID, scope) => cache.rememberPending(wikiID, scope),
114
+ clearPending: (wikiID) => cache.clearPending(wikiID),
115
+ pending: () => cache.pending(),
116
+ })
117
+ toolkit.wikiIngest = ingest
118
+
84
119
  /** The visibility the call asked for: private, team, or auto (the default). */
85
120
  function requestedVisibility(input) {
86
121
  const value = String(input?.visibility ?? "")
@@ -187,15 +222,15 @@ export function registerWiki(editor, toolkit) {
187
222
  }
188
223
 
189
224
  /**
190
- * The hub refuses every write and delete while a wiki ingests (`409 wiki is
191
- * processing`), and an ingest follows every write by default, so a second
192
- * write within minutes used to fail after the person had approved it.
225
+ * The hub refuses a delete while a wiki ingests (`409 wiki is processing`).
226
+ * Writes no longer wait on that: a write during an ingest is queued
227
+ * (src/wiki-ingest.js), and the answer says so.
193
228
  */
194
229
  function busyMessage(wikiID, asked, done = "written") {
195
230
  return codedMessage(
196
231
  "MEMORY_WIKI_BUSY",
197
- `wiki ${oneLine(wikiID, 80)} is ingesting an earlier write (status: processing) and refuses writes and deletes until it finishes, usually within a few minutes; nothing was ${asked ? "" : "asked or "}${done}`,
198
- "retry once mem_wiki status shows it ready. To write several files in a row, pass ingest: false on each write and ingest: true only on the last one",
232
+ `wiki ${oneLine(wikiID, 80)} is ingesting an earlier write (status: processing) and refuses deletes until it finishes, usually within a few minutes; nothing was ${asked ? "" : "asked or "}${done}`,
233
+ "retry once mem_wiki status shows it ready",
199
234
  )
200
235
  }
201
236
 
@@ -203,10 +238,10 @@ export function registerWiki(editor, toolkit) {
203
238
  function hubFailure(error, wikiID, filename) {
204
239
  const message = errorMessage(error)
205
240
  const what = String(error?.what ?? message)
206
- if (Number(error?.status) === 409 || /wiki is processing/i.test(what)) return text(busyMessage(wikiID, true))
241
+ if (Number(error?.status) === 409 || /wiki is processing/i.test(what)) return refuse(busyMessage(wikiID, true))
207
242
  // The hub's ENOENT names a path on its own disk: never repeat it.
208
243
  if (/\bENOENT\b/.test(what)) {
209
- return text(
244
+ return refuse(
210
245
  codedMessage(
211
246
  "MEMORY_WIKI_NO_FOLDERS",
212
247
  `the wiki cannot create a folder for "${oneLine(filename, 120)}"; nothing was written`,
@@ -240,24 +275,34 @@ export function registerWiki(editor, toolkit) {
240
275
  })
241
276
  }
242
277
 
243
- async function writeRaw(scope, wikiID, filename, content, ingest) {
244
- await backend.writeWikiRaw({ scope, wikiID, files: [{ filename, content }] })
245
- if (ingest === false) return { ingested: false }
246
- try {
247
- await backend.ingestWiki({ scope, wikiID })
248
- return { ingested: true }
249
- } catch (error) {
250
- return { ingested: false, ingestError: errorMessage(error) }
251
- }
278
+ async function writeRaw(scope, wikiID, filename, content) {
279
+ return ingest.write({ scope, wikiID, filename, content })
280
+ }
281
+
282
+ /**
283
+ /**
284
+ * The state a written source file's answer opens with (0.11.3): the file is
285
+ * saved at once, so `processing` while the ingest it started makes search and
286
+ * the pages derived from it current, `failed` when that ingest did not start,
287
+ * and `stored` when no ingest was asked for.
288
+ */
289
+ function writtenState(written) {
290
+ if (written?.queued) return "queued"
291
+ // A3 starts an ingest after every write (ingest: false is ignored), so a
292
+ // write that landed is `processing` until that ingest finishes.
293
+ if (written?.ingestError) return "failed"
294
+ return "processing"
252
295
  }
253
296
 
254
- /** What happens after a write, and how to write several files without the lock. */
297
+ /**
298
+ * What happens after a write. `ingest: false` is accepted and ignored: the
299
+ * ingest starts on its own, so nothing here asks the agent to batch.
300
+ */
255
301
  function ingestNote(written) {
256
- if (written.ingested) {
257
- return "ingestion started (asynchronous); until it finishes the wiki refuses writes, so when writing several files pass ingest: false on each and ingest: true only on the last"
302
+ if (written.queued) {
303
+ return "the wiki is ingesting an earlier write, so this write is written after that ingest finishes, even after a restart"
258
304
  }
259
- if (written.ingestError) return `ingestion not started (${written.ingestError}); the source file is written, and search finds it after the next ingest`
260
- return "ingestion not started (ingest: false); pass ingest: true on the last write so search finds the changes"
305
+ return "ingestion starts on its own a moment after the last write, so a burst of writes makes one ingest; search finds the changes once it finishes"
261
306
  }
262
307
 
263
308
  /**
@@ -346,10 +391,18 @@ export function registerWiki(editor, toolkit) {
346
391
  }
347
392
  }
348
393
 
394
+ /** A page/ls answer as the cache keeps it: `{ ref, title }`, bounded. */
395
+ function listedPages(data) {
396
+ return (data?.items ?? [])
397
+ .map((item) => ({ ref: String(item?.path ?? item?.id ?? ""), title: oneLine(item?.title || item?.path || item?.id || "", 200) }))
398
+ .filter((page) => page.ref)
399
+ .slice(0, 100)
400
+ }
401
+
349
402
  /**
350
403
  * What exists, so the next read can name it. The hub lists no pages while a
351
- * wiki ingests (page/ls answers [] unless it is ready), which read as
352
- * "pages: none" right after status had counted them; say why instead.
404
+ * wiki ingests (page/ls answers [] unless it is ready); the last ready set
405
+ * this engine saw is listed instead, marked stale (jelly #89 A2).
353
406
  */
354
407
  async function notFound(scoped, wikiID, name) {
355
408
  const failed = Symbol("failed")
@@ -359,7 +412,9 @@ export function registerWiki(editor, toolkit) {
359
412
  orNull(backend.getWiki({ scope: scoped, wikiID })).catch(() => null),
360
413
  ])
361
414
  const status = String(wiki?.status ?? "")
415
+ const state = status ? wikiStateOf(wiki) : ""
362
416
  const pageNames = pages === failed ? [] : (pages?.items ?? []).map((item) => item?.path ?? item?.id).filter(Boolean).slice(0, 15)
417
+ if (pages !== failed && state === "ready") cache.rememberPages(wikiID, listedPages(pages))
363
418
  const sourceNames = sources === failed
364
419
  ? []
365
420
  : (Array.isArray(sources) ? sources : sources?.items ?? [])
@@ -368,10 +423,13 @@ export function registerWiki(editor, toolkit) {
368
423
  .sort()
369
424
  .slice(0, 15)
370
425
  const list = (names) => names.map((entry) => oneLine(entry, 120)).join(", ")
426
+ const staleNames = state && state !== "ready" ? cache.pages(wikiID).map((page) => page.ref).slice(0, 15) : []
371
427
  let pageLine
372
428
  if (pageNames.length) pageLine = list(pageNames)
373
429
  else if (pages === failed) pageLine = "could not be listed now"
374
- else if (status && status !== "ready") pageLine = `none listed while the wiki is ${oneLine(status, 40)}; pages are listed again once ingestion finishes (mem_wiki status shows ready). Source files read at once`
430
+ else if (staleNames.length) {
431
+ pageLine = `${list(staleNames)}. The wiki is ${oneLine(state, 40)}, so these are the last ready set, stale until it finishes; source files read at once`
432
+ } else if (status && state !== "ready") pageLine = `none listed while the wiki is ${oneLine(status, 40)}; pages are listed again once ingestion finishes (mem_wiki status shows ready). Source files read at once`
375
433
  else if (Number(wiki?.page_count) > 0) pageLine = `none listed, though the wiki reports ${Number(wiki.page_count)}; read by filename meanwhile`
376
434
  else pageLine = "none"
377
435
  const sourceLine = sourceNames.length ? list(sourceNames) : sources === failed ? "could not be listed now" : "none"
@@ -408,20 +466,20 @@ export function registerWiki(editor, toolkit) {
408
466
  /** A refusal of a delete by the hub or the gateway, in words that say what to do. */
409
467
  function deleteFailure(error, wikiID, target) {
410
468
  const what = String(error?.what ?? errorMessage(error))
411
- if (Number(error?.status) === 409 || /wiki is processing/i.test(what)) return text(busyMessage(wikiID, true, "deleted"))
469
+ if (Number(error?.status) === 409 || /wiki is processing/i.test(what)) return refuse(busyMessage(wikiID, true, "deleted"))
412
470
  if (/endpoint_not_allowed|not available through the gateway/i.test(what)) {
413
- return text(
471
+ return refuse(
414
472
  codedMessage("MEMORY_WIKI_DELETE_UNAVAILABLE", "this Memory server does not allow wiki deletes yet (its gateway predates them); nothing was deleted", "ask the Memory server's operator to upgrade the gateway"),
415
473
  )
416
474
  }
417
475
  if (/forbidden path/i.test(what)) {
418
- return text(codedMessage("MEMORY_WIKI_STRUCTURAL", `"${oneLine(target, 120)}" is one of the wiki's structural pages (index, schema, purpose); nothing was deleted`, "delete a source file or another page"))
476
+ return refuse(codedMessage("MEMORY_WIKI_STRUCTURAL", `"${oneLine(target, 120)}" is one of the wiki's structural pages (index, schema, purpose); nothing was deleted`, "delete a source file or another page"))
419
477
  }
420
- if (/invalid path/i.test(what)) return text(`not deleted: ${oneLine(target, 120)} was not found in wiki ${oneLine(wikiID, 80)}; nothing was deleted.`)
478
+ if (/invalid path/i.test(what)) return refuse(`not deleted: ${oneLine(target, 120)} was not found in wiki ${oneLine(wikiID, 80)}; nothing was deleted.`)
421
479
  if (/resource_delete_forbidden|resource owner or a space owner or admin/i.test(what)) {
422
- return text(`not deleted: only the wiki's owner or a space owner or admin can delete it. Nothing was deleted.`)
480
+ return refuse(`not deleted: only the wiki's owner or a space owner or admin can delete it. Nothing was deleted.`)
423
481
  }
424
- return fail(errorMessage(error))
482
+ return failedCall(errorMessage(error))
425
483
  }
426
484
 
427
485
  /** Names of pages a delete removed or rewrote, bounded. */
@@ -443,43 +501,43 @@ export function registerWiki(editor, toolkit) {
443
501
  const rawFilename = input?.filename === undefined || input?.filename === null ? "" : String(input.filename).trim()
444
502
  const rawRef = String(input?.ref ?? input?.path ?? "").trim()
445
503
  if (rawFilename && rawRef) {
446
- return text("not deleted: delete takes one target: filename (a source file), ref (a generated page), or neither with wiki_id (the whole wiki). Nothing was asked or deleted.")
504
+ return refuse("not deleted: delete takes one target: filename (a source file), ref (a generated page), or neither with wiki_id (the whole wiki). Nothing was asked or deleted.")
447
505
  }
448
506
  const kind = rawFilename ? "source" : rawRef ? "page" : "wiki"
449
507
  const givenWiki = String(input?.wiki_id ?? "").trim()
450
508
  if (kind === "wiki" && !givenWiki) {
451
- return text(
509
+ return refuse(
452
510
  "not deleted: name what to delete. filename deletes a source file, ref a generated page, and wiki_id alone the whole wiki (mem_wiki list shows the ids). Nothing was asked or deleted.",
453
511
  )
454
512
  }
455
513
  let target = ""
456
514
  if (kind === "source") {
457
515
  target = filenameOf({ filename: rawFilename.replace(/^\/*wiki\//, "") })
458
- if (!target) return text("invalid filename")
459
- if (target === RECORDS_FILE) return text(`not deleted: ${RECORDS_REFUSAL}`)
516
+ if (!target) return refuse("invalid filename")
517
+ if (target === RECORDS_FILE) return refuse(`not deleted: ${RECORDS_REFUSAL}`)
460
518
  } else if (kind === "page") {
461
- if (rawRef.split("/").some((part) => part === "..")) return text("invalid ref")
519
+ if (rawRef.split("/").some((part) => part === "..")) return refuse("invalid ref")
462
520
  target = oneLine(rawRef, 240)
463
521
  if (STRUCTURAL_PAGES.has(target.replace(/^\/*wiki\//, "").replace(/\.md$/i, ""))) {
464
- return text(`not deleted: "${target}" is one of the wiki's structural pages (index, schema, purpose), which the wiki keeps. Nothing was asked or deleted.`)
522
+ return refuse(`not deleted: "${target}" is one of the wiki's structural pages (index, schema, purpose), which the wiki keeps. Nothing was asked or deleted.`)
465
523
  }
466
524
  }
467
- if (toolkit.runtime.records?.isRecordsWiki(givenWiki)) return text(`not deleted: ${RECORDS_REFUSAL}`)
525
+ if (toolkit.runtime.records?.isRecordsWiki(givenWiki)) return refuse(`not deleted: ${RECORDS_REFUSAL}`)
468
526
 
469
527
  const chosenVisibility = await writeVisibility(input, context)
470
- if (chosenVisibility.error) return fail(chosenVisibility.error)
528
+ if (chosenVisibility.error) return failedCall(chosenVisibility.error)
471
529
  const { visibility } = chosenVisibility
472
530
  const resolved = await resolveWrite(input, context, visibility)
473
- if (resolved.invalid) return text(resolved.invalid)
474
- if (resolved.error) return fail(resolved.error)
531
+ if (resolved.invalid) return refuse(resolved.invalid)
532
+ if (resolved.error) return failedCall(resolved.error)
475
533
  const { spaceContext, scoped } = resolved
476
534
  const where = spaceContext ? toolkit.describeSpace(spaceContext) : "the local scope"
477
535
 
478
536
  try {
479
537
  const found = kind === "wiki" ? { wikiID: givenWiki, note: "" } : await wikiFor(input, scoped, "delete")
480
- if (found.error) return text(found.error)
538
+ if (found.error) return refuse(found.error)
481
539
  const { wikiID, note } = found
482
- if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return text(`not deleted: ${RECORDS_REFUSAL}`)
540
+ if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return refuse(`not deleted: ${RECORDS_REFUSAL}`)
483
541
 
484
542
  // What would go, read now, so the preview and the approval name it.
485
543
  let subject
@@ -489,30 +547,30 @@ export function registerWiki(editor, toolkit) {
489
547
  try {
490
548
  wiki = await backend.getWiki({ scope: scoped, wikiID })
491
549
  } catch (error) {
492
- if ([403, 404].includes(Number(error?.status))) return text(`not deleted: wiki ${oneLine(wikiID, 80)} was not found in ${where}. Nothing was asked or deleted.`)
550
+ if ([403, 404].includes(Number(error?.status))) return refuse(`not deleted: wiki ${oneLine(wikiID, 80)} was not found in ${where}. Nothing was asked or deleted.`)
493
551
  throw error
494
552
  }
495
553
  if (isRecordsWikiName(wiki?.name)) {
496
554
  toolkit.runtime.records?.noteRecordsWiki(wikiID)
497
- return text(`not deleted: ${RECORDS_REFUSAL}`)
555
+ return refuse(`not deleted: ${RECORDS_REFUSAL}`)
498
556
  }
499
557
  if (spaceContext && control) {
500
558
  resourceID = await catalogResourceOf(scoped, wikiID)
501
- if (!resourceID) return text(`not deleted: wiki ${oneLine(wikiID, 80)} is not in ${where}'s catalog, so it cannot be deleted from here. Nothing was asked or deleted.`)
559
+ if (!resourceID) return refuse(`not deleted: wiki ${oneLine(wikiID, 80)} is not in ${where}'s catalog, so it cannot be deleted from here. Nothing was asked or deleted.`)
502
560
  const userId = spaceContext.user_id || runtime.config.user
503
561
  try {
504
562
  await control.deleteResource({ userId, spaceId: spaceContext.space_id, resourceId: resourceID, dryRun: true })
505
563
  } catch (error) {
506
- if ([400, 403, 404].includes(Number(error?.status))) return text(`not deleted: ${errorMessage(error)}. Nothing was asked or deleted.`)
564
+ if ([400, 403, 404].includes(Number(error?.status))) return refuse(`not deleted: ${errorMessage(error)}. Nothing was asked or deleted.`)
507
565
  throw error
508
566
  }
509
567
  }
510
568
  const pages = Number(wiki?.page_count) || 0
511
569
  subject = `the whole wiki ${oneLine(wikiID, 80)} (${oneLine(wiki?.name ?? "", 120)}${pages ? `, ${pages} pages` : ""}): every source file and page${resourceID ? ", and its catalog entry and grants" : ""}`
512
570
  } else {
513
- if ((await wikiStatus(scoped, wikiID)) === "processing") return text(busyMessage(wikiID, false, "deleted"))
571
+ if ((await wikiStatus(scoped, wikiID)) === "processing") return refuse(busyMessage(wikiID, false, "deleted"))
514
572
  const existing = kind === "source" ? await readSource(scoped, wikiID, target) : await readPage(scoped, wikiID, target)
515
- if (!existing) return text(`${note}${await notFound(scoped, wikiID, target)}\nNothing was asked or deleted.`)
573
+ if (!existing) return refuse(`${note}${await notFound(scoped, wikiID, target)}\nNothing was asked or deleted.`)
516
574
  subject =
517
575
  kind === "source"
518
576
  ? `source file ${target} (${Buffer.byteLength(existing.content)} bytes) from wiki ${oneLine(wikiID, 80)}; the wiki also deletes the pages ingested only from it and rewrites the pages that cite it`
@@ -520,7 +578,7 @@ export function registerWiki(editor, toolkit) {
520
578
  }
521
579
 
522
580
  if (input?.confirm !== true) {
523
- return text(
581
+ return refuse(
524
582
  `${note}Preview only: nothing was deleted and nothing was asked. In ${where}, mem_wiki delete with confirm: true would delete ${subject}. That call asks the person first, then reads the deletion back. Only delete it if the person asked: a wiki or file you created by mistake is reported, and removed only if the person asks.`,
525
583
  )
526
584
  }
@@ -536,14 +594,14 @@ export function registerWiki(editor, toolkit) {
536
594
  metadata: { kind: "wiki", target: kind, wiki: wikiID, ...(target ? { name: target } : {}), space: spaceContext?.space_id ?? "local", visibility },
537
595
  })
538
596
  } catch (error) {
539
- return text(`wiki delete denied: ${errorMessage(error)}. Nothing was deleted.`)
597
+ return refuse(`wiki delete denied: ${errorMessage(error)}. Nothing was deleted.`)
540
598
  }
541
599
 
542
600
  if (kind === "wiki") {
543
601
  if (resourceID) {
544
602
  try {
545
603
  const result = await control.deleteResource({ userId: spaceContext.user_id || runtime.config.user, spaceId: spaceContext.space_id, resourceId: resourceID })
546
- if (result?.deleted !== true) return fail(`wiki ${oneLine(wikiID, 80)} was not deleted: the gateway did not confirm the delete.`)
604
+ if (result?.deleted !== true) return failedCall(`wiki ${oneLine(wikiID, 80)} was not deleted: the gateway did not confirm the delete.`)
547
605
  } catch (error) {
548
606
  return deleteFailure(error, wikiID, wikiID)
549
607
  }
@@ -556,12 +614,12 @@ export function registerWiki(editor, toolkit) {
556
614
  }
557
615
  const deleted = (data?.deleted_ids ?? []).map(String).includes(wikiID)
558
616
  const missing = (data?.failed ?? []).some((entry) => String(entry?.id) === wikiID && /not\s*found/i.test(String(entry?.reason ?? "")))
559
- if (!deleted && !missing) return fail(`wiki ${oneLine(wikiID, 80)} was not deleted: ${oneLine(errorMessage((data?.failed ?? [])[0]?.reason ?? "the wiki did not confirm it"), 200)}.`)
617
+ if (!deleted && !missing) return failedCall(`wiki ${oneLine(wikiID, 80)} was not deleted: ${oneLine(errorMessage((data?.failed ?? [])[0]?.reason ?? "the wiki did not confirm it"), 200)}.`)
560
618
  }
561
619
  const back = await wikiGone(scoped, wikiID)
562
620
  log.info("wiki deleted", { wikiID, catalog: Boolean(resourceID), verified: back.gone })
563
- if (back.gone === false) return fail(`wiki ${oneLine(wikiID, 80)}: the delete was reported, but ${back.text}. Report this to the Memory server's operator.`)
564
- return text(`deleted the whole wiki ${oneLine(wikiID, 80)} from ${where}${resourceID ? ", with its catalog entry" : ""}. Read back: ${back.text}.`)
621
+ if (back.gone === false) return failedCall(`wiki ${oneLine(wikiID, 80)}: the delete was reported, but ${back.text}. Report this to the Memory server's operator.`)
622
+ return withWriteState(text(`deleted the whole wiki ${oneLine(wikiID, 80)} from ${where}${resourceID ? ", with its catalog entry" : ""}. Read back: ${back.text}.`), { state: "ready" })
565
623
  }
566
624
 
567
625
  let data
@@ -583,20 +641,21 @@ export function registerWiki(editor, toolkit) {
583
641
  ]
584
642
  : [Array.isArray(data?.rewritten_files) && data.rewritten_files.length ? `It removed links to it from ${data.rewritten_files.length} file(s).` : ""]
585
643
  log.info("wiki file deleted", { wikiID, kind, verified: !still })
586
- if (still) return fail(`${kind === "source" ? "source file" : "page"} ${target} in wiki ${oneLine(wikiID, 80)}: the delete was reported, but it still reads back. Report this to the Memory server's operator.`)
587
- return text(
588
- `${note}deleted ${kind === "source" ? "source file" : "page"} ${target} from wiki ${oneLine(wikiID, 80)}. ${cascade.filter(Boolean).join(" ")}${cascade.some(Boolean) ? " " : ""}Read back: it is gone.`,
644
+ if (still) return failedCall(`${kind === "source" ? "source file" : "page"} ${target} in wiki ${oneLine(wikiID, 80)}: the delete was reported, but it still reads back. Report this to the Memory server's operator.`)
645
+ return withWriteState(
646
+ text(`${note}deleted ${kind === "source" ? "source file" : "page"} ${target} from wiki ${oneLine(wikiID, 80)}. ${cascade.filter(Boolean).join(" ")}${cascade.some(Boolean) ? " " : ""}Read back: it is gone.`),
647
+ { state: "ready" },
589
648
  )
590
649
  } catch (error) {
591
650
  log.warn("wiki delete failed", error)
592
- return fail(errorMessage(error))
651
+ return failedCall(errorMessage(error))
593
652
  }
594
653
  }
595
654
 
596
655
  const wiki = {
597
656
  name: "wiki",
598
657
  description:
599
- "When asked to read a named document or wiki file, use mem_wiki read (or search to find it), even if mem_recall might answer. Call list, search and read for documentation, architecture, ownership and call-graph questions about what was uploaded or indexed. Write only documents the person gave you, as flat source files (\"notes.md\"; a name with a folder is refused). A space has a knowledge wiki only once action create makes one (name it \"My knowledge\" in the personal space); list shows which wikis exist. A write starts an ingest that locks the wiki for a few minutes: to write several files, pass ingest: false on each and ingest: true on the last. Like mem_recall it uses the session's space by default: your personal space, or a shared space bound to the session. A write to a shared space asks the person and shows the file and an excerpt; a write to your personal space does not. delete removes one source file (filename), one generated page (ref), or a whole wiki (wiki_id alone): without confirm it only previews; with confirm: true it always asks the person, then deletes and reads it back. Never put things to do (mem_commitments), where a project stands, or person and project pages (mem_page) here.",
658
+ "When asked to read a named document or wiki file, use mem_wiki read (or search to find it), even if mem_recall might answer. Call list, search and read for documentation, architecture, ownership and call-graph questions about what was uploaded or indexed. Write only documents the person gave you, as flat source files (\"notes.md\"; a name with a folder is refused). A space has a knowledge wiki only once action create makes one (name it \"My knowledge\" in the personal space); list shows which wikis exist. A write starts one ingest by itself a moment after the last one; a write during an ingest is queued, not refused. Like mem_recall it uses the session's space by default: your personal space, or a shared space bound to the session. A write to a shared space asks the person and shows the file and an excerpt; a write to your personal space does not. delete removes one source file (filename), one generated page (ref), or a whole wiki (wiki_id alone): without confirm it only previews; with confirm: true it always asks the person, then deletes and reads it back. Never put things to do (mem_commitments), where a project stands, or person and project pages (mem_page) here.",
600
659
  input: {
601
660
  type: "object",
602
661
  properties: {
@@ -629,7 +688,7 @@ export function registerWiki(editor, toolkit) {
629
688
  ingest: {
630
689
  type: "boolean",
631
690
  description:
632
- "Start ingestion after create, write, or append (default true). The wiki refuses writes while it ingests (a few minutes), so to write several files pass ingest: false on each and ingest: true only on the last",
691
+ "Ignored: ingestion always starts on its own a short while after the last write, so a burst of writes makes one ingest",
633
692
  },
634
693
  ref: {
635
694
  type: "string",
@@ -662,22 +721,28 @@ export function registerWiki(editor, toolkit) {
662
721
  execute: async (input, context) => {
663
722
  const action = String(input?.action ?? "list")
664
723
  const asked = requestedVisibility(input)
724
+ // 0.11.3 (jelly's #89 ask A4): a write's answer opens with its state
725
+ // line, and a refusal opens with `state: refused` and names nothing. A
726
+ // read's answer is exactly what it was.
727
+ const isWrite = FILE_WRITE_ACTIONS.includes(action)
728
+ const answer = (content) => (isWrite ? refusedAnswer(text(content)) : text(content))
729
+ const failure = (message) => (isWrite ? failedAnswer(fail(message)) : fail(message))
665
730
 
666
731
  if (action === "delete") return deleteAction(input, context)
667
732
 
668
733
  if (FILE_WRITE_ACTIONS.includes(action)) {
669
734
  const content = String(input?.content ?? "")
670
- if (action !== "create" && !content.trim()) return text(`nothing to ${action}: content is empty`)
671
- if (Buffer.byteLength(content) > MAX_FILE_BYTES) return text("wiki content is too large (max 512 KB)")
735
+ if (action !== "create" && !content.trim()) return answer(`nothing to ${action}: content is empty`)
736
+ if (Buffer.byteLength(content) > MAX_FILE_BYTES) return answer("wiki content is too large (max 512 KB)")
672
737
  // Everything that can be refused from the call alone is refused before
673
738
  // anything is asked: a person never approves a write that cannot run.
674
- if (action === "create" && !oneLine(input?.name, 200).trim()) return text("wiki name is required")
739
+ if (action === "create" && !oneLine(input?.name, 200).trim()) return answer("wiki name is required")
675
740
  const createName = action === "create" ? filenameOf(input) : ""
676
741
  const chosen = action !== "create" ? writeTarget(input) : createName ? { filename: createName } : { invalid: true }
677
- if (chosen.missing) return text(`filename is required for ${action}: the source file, for example "project-harbour.md"`)
678
- if (chosen.invalid) return text("invalid filename")
742
+ if (chosen.missing) return answer(`filename is required for ${action}: the source file, for example "project-harbour.md"`)
743
+ if (chosen.invalid) return answer("invalid filename")
679
744
  const target = chosen.filename
680
- if (target.includes("/")) return text(nestedRefusal(action, target))
745
+ if (target.includes("/")) return answer(nestedRefusal(action, target))
681
746
  // The records wiki is mem_commitments' store: never written here.
682
747
  if (
683
748
  (action === "create" && isRecordsWikiName(oneLine(input?.name, 200).trim())) ||
@@ -685,22 +750,22 @@ export function registerWiki(editor, toolkit) {
685
750
  target === RECORDS_FILE ||
686
751
  isRecordsText(content)
687
752
  ) {
688
- return text(`not written: ${RECORDS_REFUSAL}`)
753
+ return answer(`not written: ${RECORDS_REFUSAL}`)
689
754
  }
690
755
 
691
756
  const chosenVisibility = await writeVisibility(input, context)
692
- if (chosenVisibility.error) return fail(chosenVisibility.error)
757
+ if (chosenVisibility.error) return failure(chosenVisibility.error)
693
758
  const { visibility } = chosenVisibility
694
759
  const resolved = await resolveWrite(input, context, visibility)
695
- if (resolved.invalid) return text(resolved.invalid)
696
- if (resolved.error) return fail(resolved.error)
760
+ if (resolved.invalid) return answer(resolved.invalid)
761
+ if (resolved.error) return failure(resolved.error)
697
762
 
698
763
  try {
699
764
  if (action === "create") {
700
765
  const name = oneLine(input?.name, 200).trim()
701
766
  const filename = target
702
767
  const denied = await approveWrite(context, visibility, resolved.spaceContext, approvalOf(action, input, target, content))
703
- if (denied) return text(`wiki write denied: ${denied}`)
768
+ if (denied) return answer(`wiki write denied: ${denied}`)
704
769
  const wiki = await backend.createWiki({ scope: resolved.scoped, name })
705
770
  const wikiID = String(wiki?.wiki_id ?? "")
706
771
  if (!wikiID) throw new Error("wiki/create returned no wiki_id")
@@ -708,60 +773,74 @@ export function registerWiki(editor, toolkit) {
708
773
  try {
709
774
  resource = await registerWikiResource(resolved.spaceContext, wiki, name)
710
775
  } catch (error) {
711
- return fail(
776
+ return failure(
712
777
  `wiki ${wikiID} was created but resource registration failed: ${errorMessage(error)}. An operator must register it before the gateway can expose it.`,
713
778
  )
714
779
  }
715
780
  let written
716
781
  try {
717
- written = await writeRaw(resolved.scoped, wikiID, filename, content || `# ${name}\n`, input?.ingest !== false)
782
+ written = await writeRaw(resolved.scoped, wikiID, filename, content || `# ${name}\n`)
718
783
  } catch (error) {
719
784
  log.warn("wiki create write failed", error)
720
785
  return hubFailure(error, wikiID, filename)
721
786
  }
722
787
  log.info("wiki created", { wikiID, visibility, resource: resource?.id ?? null })
723
- return text(
724
- `created wiki ${wikiID} (${name}); wrote ${filename}; ${ingestNote(written)}${resource?.id ? `; resource ${resource.id}` : ""}`,
788
+ return withWriteState(
789
+ text(`created wiki ${wikiID} (${name}); wrote ${filename}; ${ingestNote(written)}${resource?.id ? `; resource ${resource.id}` : ""}`),
790
+ { state: writtenState(written), id: `${wikiID}/${filename}`, link: wikiPlace(wikiID, filename) },
725
791
  )
726
792
  }
727
793
 
728
794
  // As read does: with one visible wiki, it is the target, and the
729
795
  // answer names it. With none or several, the refusal lists them.
730
796
  const found = await wikiFor(input, resolved.scoped, action)
731
- if (found.error) return text(found.error)
797
+ if (found.error) return answer(found.error)
732
798
  const { wikiID, note } = found
733
- if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return text(`not written: ${RECORDS_REFUSAL}`)
799
+ if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return answer(`not written: ${RECORDS_REFUSAL}`)
734
800
  const filename = target
735
- // An ingesting wiki refuses the write: say so before anyone is asked.
736
- if ((await wikiStatus(resolved.scoped, wikiID)) === "processing") return text(busyMessage(wikiID, false))
737
-
738
801
  let body = content
739
802
  if (action === "append") {
740
803
  const existing = await backend.readWikiRaw({ scope: resolved.scoped, wikiID, filenames: [filename] })
741
804
  const current = (existing?.items ?? []).find((item) => item?.filename === filename)?.content ?? ""
742
805
  body = current ? `${current.replace(/\s+$/, "")}\n\n${content}` : content
743
- if (Buffer.byteLength(body) > MAX_FILE_BYTES) return text("wiki file is too large after append")
806
+ if (Buffer.byteLength(body) > MAX_FILE_BYTES) return answer("wiki file is too large after append")
744
807
  }
745
808
 
746
809
  const denied = await approveWrite(context, visibility, resolved.spaceContext, approvalOf(action, input, target, content))
747
- if (denied) return text(`wiki write denied: ${denied}`)
810
+ if (denied) return answer(`wiki write denied: ${denied}`)
748
811
  let written
749
812
  try {
750
- written = await writeRaw(resolved.scoped, wikiID, filename, body, input?.ingest !== false)
813
+ written = await writeRaw(resolved.scoped, wikiID, filename, body)
751
814
  } catch (error) {
752
815
  log.warn("wiki write failed", error)
753
816
  return hubFailure(error, wikiID, filename)
754
817
  }
755
818
  // Say what the write guarantees, so the agent does not read its own
756
819
  // write back to check it: the source file now holds exactly this.
757
- return text(
758
- `${note}${action === "append" ? "appended to" : "wrote"} ${filename} in wiki ${wikiID}: the source file now holds ${
759
- action === "append" ? "its earlier text and then" : "exactly"
760
- } the content you sent (${Buffer.byteLength(body)} bytes), and a read of it returns that; ${ingestNote(written)}`,
820
+ // A queued write guarantees nothing yet: the wiki is ingesting, and
821
+ // it is on disk until the hub accepts it. A queue the disk refused
822
+ // saved nothing, so the answer is `refused` (jelly #89, 0.11.4).
823
+ if (written.refused) {
824
+ return withWriteState(text(`${note}not written: the wiki is busy, nothing was saved, try again in about a minute`), { state: "refused" })
825
+ }
826
+ if (written.queued) {
827
+ const what = action === "append" ? "the append to" : ""
828
+ return withWriteState(
829
+ text(`${note}queued ${what ? `${what} ` : ""}${filename} in wiki ${wikiID} (${Buffer.byteLength(body)} bytes); ${ingestNote(written)}`),
830
+ { state: writtenState(written), id: `${wikiID}/${filename}`, link: wikiPlace(wikiID, filename) },
831
+ )
832
+ }
833
+ return withWriteState(
834
+ text(
835
+ `${note}${action === "append" ? "appended to" : "wrote"} ${filename} in wiki ${wikiID}: the source file now holds ${
836
+ action === "append" ? "its earlier text and then" : "exactly"
837
+ } the content you sent (${Buffer.byteLength(body)} bytes), and a read of it returns that; ${ingestNote(written)}`,
838
+ ),
839
+ { state: writtenState(written), id: `${wikiID}/${filename}`, link: wikiPlace(wikiID, filename) },
761
840
  )
762
841
  } catch (error) {
763
842
  log.warn("wiki write failed", error)
764
- return fail(errorMessage(error))
843
+ return failure(errorMessage(error))
765
844
  }
766
845
  }
767
846
 
@@ -773,8 +852,8 @@ export function registerWiki(editor, toolkit) {
773
852
  : asked === "auto" && control
774
853
  ? await resolveReadSpace(input, context, "auto")
775
854
  : await resolveSpace(input, context)
776
- if (resolved.invalid) return text(resolved.invalid)
777
- if (resolved.error) return fail(resolved.error)
855
+ if (resolved.invalid) return answer(resolved.invalid)
856
+ if (resolved.error) return failure(resolved.error)
778
857
  const spaceContext = resolved.context
779
858
  const scoped = spaceContext
780
859
  ? toolkit.scopeFor(spaceContext, {
@@ -830,6 +909,7 @@ export function registerWiki(editor, toolkit) {
830
909
  )}`,
831
910
  )
832
911
  }
912
+ const wikiByID = new Map()
833
913
  for (const wiki of wikis?.items ?? []) {
834
914
  const wikiID = String(wiki.wiki_id ?? "")
835
915
  if (!wikiID || seen.has(wikiID)) continue
@@ -839,10 +919,11 @@ export function registerWiki(editor, toolkit) {
839
919
  continue
840
920
  }
841
921
  seen.add(wikiID)
922
+ wikiByID.set(wikiID, wiki)
842
923
  lines.push(
843
924
  `- ${neutralizeFenceClosers(oneLine(wikiID, 120))} [wiki] ${neutralizeFenceClosers(
844
925
  oneLine(wiki.name ?? "", 200),
845
- )} (${neutralizeFenceClosers(oneLine(wiki.status ?? "?", 40))}${wiki.page_count ? `, ${wiki.page_count} pages` : ""})`,
926
+ )} (${neutralizeFenceClosers(oneLine(wikiStateOf(wiki), 40))}${wiki.page_count ? `, ${wiki.page_count} pages` : ""})`,
846
927
  )
847
928
  }
848
929
  for (const graph of graphs?.items ?? []) {
@@ -855,7 +936,7 @@ export function registerWiki(editor, toolkit) {
855
936
  )} (${neutralizeFenceClosers(oneLine(graph.status ?? "?", 40))})`,
856
937
  )
857
938
  }
858
- if (lines.length === 0) return text(emptyKnowledge(input, spaceContext))
939
+ if (lines.length === 0) return answer(emptyKnowledge(input, spaceContext))
859
940
  // Each wiki's source files, so the next call can read a page by name
860
941
  // (filename) instead of searching for its path first. Bounded: the
861
942
  // first five wikis, fifteen names each.
@@ -863,21 +944,33 @@ export function registerWiki(editor, toolkit) {
863
944
  const listed = await Promise.all(wikiRows.slice(0, 5).map((row) => sourceFiles(scoped, row.id)))
864
945
  wikiRows.slice(0, 5).forEach((row, index) => {
865
946
  const { names, more } = listed[index]
866
- if (names.length === 0) return
867
- lines[row.index] = `${row.line}\n files (pass as filename): ${names.map((name) => neutralizeFenceClosers(oneLine(name, 120))).join(", ")}${more ? `, +${more} more` : ""}`
947
+ const extra = []
948
+ if (names.length > 0) {
949
+ extra.push(` files (pass as filename): ${names.map((name) => neutralizeFenceClosers(oneLine(name, 120))).join(", ")}${more ? `, +${more} more` : ""}`)
950
+ }
951
+ // While a wiki ingests the hub lists no pages; the last ready set
952
+ // this engine saw is listed instead, saying it is stale (A2).
953
+ const state = wikiByID.has(row.id) ? wikiStateOf(wikiByID.get(row.id)) : "ready"
954
+ const stale = state === "ready" ? [] : cache.pages(row.id).slice(0, 10)
955
+ if (stale.length > 0) {
956
+ extra.push(
957
+ ` pages (pass as ref): ${stale.map((page) => neutralizeFenceClosers(oneLine(page.ref, 120))).join(", ")}. The wiki is ${oneLine(state, 40)}, so these are the last ready set, stale until it finishes.`,
958
+ )
959
+ }
960
+ if (extra.length > 0) lines[row.index] = `${row.line}\n${extra.join("\n")}`
868
961
  })
869
- return text(["<knowledge_assets>", ...lines, "</knowledge_assets>"].join("\n"))
962
+ return answer(["<knowledge_assets>", ...lines, "</knowledge_assets>"].join("\n"))
870
963
  }
871
964
 
872
965
  if (action === "read") {
873
966
  const target = await wikiFor(input, scoped, "read")
874
- if (target.empty) return text(emptyKnowledge(input, spaceContext))
875
- if (target.error) return text(target.error)
967
+ if (target.empty) return answer(emptyKnowledge(input, spaceContext))
968
+ if (target.error) return answer(target.error)
876
969
  const { wikiID, note } = target
877
- if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return text(RECORDS_REFUSAL)
970
+ if (toolkit.runtime.records?.isRecordsWiki(wikiID)) return answer(RECORDS_REFUSAL)
878
971
  const ref = String(input?.ref ?? input?.path ?? "").trim()
879
972
  const name = ref || filenameOf(input)
880
- if (!name) return text("invalid filename")
973
+ if (!name) return answer("invalid filename")
881
974
  // The source file first: it is what the agent writes, and it is
882
975
  // current at once, while the extracted page lags until ingestion
883
976
  // finishes (a model that re-read the page after a write saw the old
@@ -894,25 +987,25 @@ export function registerWiki(editor, toolkit) {
894
987
  const found = await read(scoped, wikiID, target)
895
988
  if (found && isRecordsText(found.content)) {
896
989
  toolkit.runtime.records?.noteRecordsWiki(wikiID)
897
- return text(RECORDS_REFUSAL)
990
+ return answer(RECORDS_REFUSAL)
898
991
  }
899
992
  if (found) {
900
993
  const safe = quarantineText(found.content.slice(0, 12_000))
901
994
  const after = quarantineNote(safe.removed)
902
- return text(
995
+ return answer(
903
996
  `${note}<knowledge source="${neutralizeFenceClosers(oneLine(found.source, 120))}">\n${neutralizeFenceClosers(
904
997
  safe.text,
905
998
  )}\n</knowledge>${after ? `\n${after}` : ""}`,
906
999
  )
907
1000
  }
908
1001
  }
909
- return text(`${note}${await notFound(scoped, wikiID, name)}`)
1002
+ return answer(`${note}${await notFound(scoped, wikiID, name)}`)
910
1003
  }
911
1004
 
912
1005
  if (action === "status") {
913
1006
  const target = await wikiFor(input, scoped, "status")
914
- if (target.empty) return text(emptyKnowledge(input, spaceContext))
915
- if (target.error) return text(target.error)
1007
+ if (target.empty) return answer(emptyKnowledge(input, spaceContext))
1008
+ if (target.error) return answer(target.error)
916
1009
  const { wikiID } = target
917
1010
  const [wiki, pages] = await Promise.all([
918
1011
  backend.getWiki({ scope: scoped, wikiID }),
@@ -921,28 +1014,30 @@ export function registerWiki(editor, toolkit) {
921
1014
  // While it ingests the hub lists no pages; its own count is the answer then.
922
1015
  const listed = Array.isArray(pages?.items) ? pages.items.length : 0
923
1016
  const pageCount = listed || Number(wiki?.page_count) || 0
924
- const status = String(wiki?.status ?? "unknown")
1017
+ const state = wikiStateOf(wiki)
1018
+ if (state === "ready" && Array.isArray(pages?.items)) cache.rememberPages(wikiID, listedPages(pages))
1019
+ const error = state === "failed" ? wikiErrorOf(wiki, cache.error(wikiID)) : ""
925
1020
  return text(
926
- `wiki: ${oneLine(wiki?.wiki_id ?? wikiID, 120)}\nname: ${oneLine(wiki?.name ?? "", 200)}\nstatus: ${oneLine(status, 40)}${
927
- status === "processing" ? " (ingesting: writes and deletes are refused until it is ready)" : ""
928
- }\npages: ${pageCount}`,
1021
+ `wiki: ${oneLine(wiki?.wiki_id ?? wikiID, 120)}\nname: ${oneLine(wiki?.name ?? "", 200)}\nstatus: ${oneLine(state, 40)}${
1022
+ state === "processing" ? " (ingesting: a write during it is queued until it finishes)" : ""
1023
+ }\npages: ${pageCount}${error ? `\nerror: ${oneLine(error, 400)}` : ""}`,
929
1024
  )
930
1025
  }
931
1026
 
932
1027
  const query = String(input?.query ?? "").trim()
933
- if (!query) return text("nothing to search: query is empty")
1028
+ if (!query) return answer("nothing to search: query is empty")
934
1029
  const ids = input?.knowledge_id
935
1030
  ? [String(input.knowledge_id)]
936
1031
  : await discoverKnowledge(backend, log, assetType, scoped)
937
- if (ids.length === 0) return text(emptyKnowledge(input, spaceContext))
1032
+ if (ids.length === 0) return answer(emptyKnowledge(input, spaceContext))
938
1033
  const result = await searchKnowledge(backend, ids.slice(0, 8), query, scoped, {
939
1034
  maxChars: config.recallChars,
940
1035
  })
941
- if (!result) return text("no knowledge results")
942
- return text(assetType === "code_graph" ? result : `${result}\n\n${READ_HINT}`)
1036
+ if (!result) return answer("no knowledge results")
1037
+ return answer(assetType === "code_graph" ? result : `${result}\n\n${READ_HINT}`)
943
1038
  } catch (error) {
944
1039
  log.warn("wiki failed", error)
945
- return fail(errorMessage(error))
1040
+ return failure(errorMessage(error))
946
1041
  }
947
1042
  },
948
1043
  }