mptyl/ThothII
1
0
Fork 0
Code Issues 25 Pull Requests Actions Packages Projects Releases 1 Wiki Activity

feat: implement memory and evidence administration with guided repairs
Publish documentation / publish (push) Successful in 1m27s
Details

Browse Source 
Add PostgreSQL-backed memory, editable evidence with source review and activation, and human-approved archive repairs across the harness, API, and UI. Include migrations, deployment support, regression coverage, and validation documentation.

Refresh permissions from validated session roles so existing administrator logins can access newly deployed archive management features.
This commit is contained in:
Codex
2026-09-10 10:31:34 +02:00
parent 8fe526dd6e
commit 82e2c91f42
168 changed files with 11914 additions and 1772 deletions
Download Patch File Download Diff File Expand all files Collapse all files
harness/.pi/extensions/gate/memory/index.js
+60 -198
View File
@@ -1,4 +1,5 @@
import { Type } from "typebox";
import { installRepairGate } from "./repair.js";
// Compatibility note: reviewer labels move verbatim from the composition root.
// Tickets #22 and #23 require observable parity; translating existing chrome is a
@@ -9,7 +10,7 @@ function normalizedText(value) {
}
const MEMORY_ID_RE = /\bmem-\d{4,}\b/i;
const MEMORY_ID_RE = /\bmem-(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|\d{4,})\b/i;
function memoryOptionKey(option) {
@@ -160,208 +161,69 @@ async function reviewRecall(ctx, params, phase, dependencies) {
}
// The candidates come from `tht memory promote --preview --json` (deterministic,
// reviewer-approved decisions only); the model never authors them.
function dedupePromotionCandidates(candidates) {
const seen = new Set();
return candidates.filter((candidate) => {
if (candidate.type !== "concept_clarified") return false;
const key = [
candidate.type,
candidate.subject,
candidate.detail,
candidate.rationale,
candidate.question_context,
].map(normalizedText).join("\u0000");
if (seen.has(key)) return false;
seen.add(key);
return true;
});
}
function promotionOptions(candidates) {
return candidates.map((candidate) => ({
id: `seq-${candidate.decision_seq}`,
label: `${candidate.type}: ${candidate.subject}`,
detail: candidate.detail || "",
rationale: candidate.rationale || "",
meta: { question_context: candidate.question_context || "" },
}));
}
function promotionContent(candidates) {
return candidates
.map(
(candidate) =>
`- **${candidate.type}: ${candidate.subject}** (decisione #${candidate.decision_seq})\n` +
` ${candidate.detail || ""}\n` +
` Motivo: ${candidate.rationale || "—"}\n` +
` Domanda di contesto: ${candidate.question_context || "—"}`,
)
.join("\n");
}
function splitPromotionChoices(candidates, choices) {
const chosen = new Set(choices ?? []);
const promote = [];
const decline = [];
for (const candidate of candidates) {
(chosen.has(`seq-${candidate.decision_seq}`) ? promote : decline).push(candidate);
}
return { promote, decline };
}
/**
* Install the public F8 Memory tool against the narrow capability supplied by the
* workflow composition root. Memory owns candidate policy, presentation and mutation
* order; the capability keeps shared phase, ledger and persistence mechanisms in core.
*/
function installMemoryGate(
pi,
{ workflow, memory, ledger, reviewer, waitForReviewer, toTextResult },
) {
pi.registerTool({
name: "reviewer_memory_promote",
label: "Promozione memorie riusabili (reviewer)",
description:
"F8 (prima della chiusura di fase): propone al reviewer i candidati di promozione " +
"calcolati dalla CLI (tht memory promote --preview: solo concept_clarified, " +
"max 5, esclusi i gia' promossi/rifiutati). Le selezioni " +
"vengono salvate nel vectordb (tht memory save-one) e registrate come memory_promoted; " +
"le deselezioni come memory_promotion_declined (non riproposte). Nessun parametro oltre " +
"alla sessione: i candidati sono deterministici, NON li scrivi tu. Registrata la " +
"promozione, in F8 il gate chiude la fase e finalizza la sessione da solo: NON " +
"presentare un reviewer_confirm dopo.",
parameters: Type.Object({
session: Type.String(),
}),
async execute(_id, params, _signal, _onUpdate, ctx) {
workflow.activate();
try {
const { session } = params;
const phase = workflow.phase(ctx, session);
let candidates;
try {
candidates = JSON.parse(memory.execute(
ctx,
["promote", "--session", session, "--preview", "--json"],
));
} catch (error) {
const message = (error.stderr || error.message || String(error)).toString().trim();
return toTextResult(`Preview di promozione non disponibile: ${message}`);
}
if (!Array.isArray(candidates) || candidates.length === 0) {
await ctx.ui.notify(
"Nessuna decisione riusabile da promuovere in memoria per questa sessione.",
"info",
);
const closed = workflow.close(
ctx, session, phase.number, "Nessun candidato di promozione.",
);
if (closed) return closed;
return toTextResult(
"Nessun candidato di promozione: prosegui con la chiusura della sessione.",
);
}
candidates = dedupePromotionCandidates(candidates);
if (candidates.length === 0) {
await ctx.ui.notify(
"Nessun concetto chiarito da salvare come memory per questa sessione.",
"info",
);
const closed = workflow.close(
ctx, session, phase.number, "Nessun candidato di promozione.",
);
if (closed) return closed;
return toTextResult(
"Nessun candidato di promozione: prosegui con la chiusura della sessione.",
);
}
const options = promotionOptions(candidates);
const widget = reviewer.buildMultiselect({
id: `u${Date.now()}`,
phase: phase.id,
title: "Quali concetti chiariti salvare nella memoria riutilizzabile?",
allowEmpty: true,
options,
selected: options.map((option) => option.id),
content: promotionContent(candidates),
});
const response = await waitForReviewer(ctx, widget);
if (response.control === "freetext") {
return toTextResult(
`Altro (reviewer): ${response.text}. Valuta e ripresenta il gate.`,
);
}
if (response.control === "back") {
return toTextResult("Il reviewer vuole tornare indietro.");
}
if (response.control === "exit") {
return toTextResult("Il reviewer vuole uscire.");
}
const { promote, decline } = splitPromotionChoices(candidates, response.choices);
let saved = 0;
for (const candidate of promote) {
const saveError = memory.mutate(
ctx,
[
"save-one", "--session", session,
"--decision", String(candidate.decision_seq), "--json",
],
`Recupero manuale (umano): tht memory save-one --session ${session} ` +
`--decision ${candidate.decision_seq}. Finora salvate: ${saved}.`,
);
if (saveError) return saveError;
const ledgerError = ledger.record(
ctx,
session,
{
type: "memory_promoted",
subject: candidate.subject,
detail: `seq:${candidate.decision_seq}`,
rationale: candidate.rationale || candidate.detail || "",
},
"Memoria salvata nel vectordb ma decisione memory_promoted NON registrata: " +
`recupero manuale (umano) con tht decision add --session ${session} ` +
`--type memory_promoted --subject "${candidate.subject}" ` +
`--detail seq:${candidate.decision_seq}.`,
);
if (ledgerError) return ledgerError;
saved++;
}
for (const candidate of decline) {
const ledgerError = ledger.record(ctx, session, {
type: "memory_promotion_declined",
subject: candidate.subject,
detail: `seq:${candidate.decision_seq}`,
}, "");
if (ledgerError) return ledgerError;
}
const summary =
`Promozione registrata: ${saved} memorie salvate nel vectordb, ` +
`${decline.length} candidati scartati.`;
const closed = workflow.close(ctx, session, phase.number, summary);
if (closed) return closed;
return toTextResult(summary);
} catch (fatal) {
const message = (fatal.stderr || fatal.message || String(fatal)).toString().trim();
return toTextResult(
`[reviewer_memory_promote ERRORE INTERNO] ${message}. ` +
"Riprova o usa un approccio diverso.",
);
}
},
});
function installMemoryGate(pi, { workflow, memory, ledger, waitForReviewer, toTextResult }) {
pi.registerTool({
name: "reviewer_memory_promote",
label: "Review Memory summary",
description: "F8: show the editable Memory summary from persisted proposals and approved " +
"decisions. The reviewer selects additions, updates and links. Only those choices " +
"are saved. Then close F8 and finalize. Prepare reusable rules during the workflow " +
"with tht memory propose; do not call review-apply yourself.",
parameters: Type.Object({ session: Type.String() }),
async execute(_id, params, _signal, _onUpdate, ctx) {
workflow.activate();
try {
const { session } = params;
const phase = workflow.phase(ctx, session);
if (phase.number > 8) return workflow.close(ctx, session, phase.number, "Memory reviewed.");
if (phase.number !== 8) return toTextResult("Review the Memory summary at the end of F8.");
const summary = JSON.parse(memory.execute(ctx, ["summary", "--session", session, "--json"]));
if (summary.reviewed) {
const failure = ledger.record(ctx, session, {
type: "memory_summary_reviewed", subject: summary.summary_id,
detail: "Previously saved Memory review recovered.",
}, "Retry to record the recovered Memory review.");
if (failure) return failure;
return workflow.close(ctx, session, phase.number, "Memory review recovered.");
}
const response = await waitForReviewer(ctx, {
id: `u${Date.now()}`, schema_version: 1, phase: phase.id,
widget: "memory-review", title: "Memory for future questions",
summary, reserved: ["other", "back", "exit"],
});
if (response.control) return toTextResult(
response.control === "freetext"
? `Reviewer feedback: ${response.text}. Revise the proposals and present the summary again.`
: `Reviewer requested: ${response.control}.`);
const selection = JSON.parse(response.text || "{}");
if (selection.summary_id !== summary.summary_id || !Array.isArray(selection.items))
return toTextResult("Invalid Memory review response. Present the summary again.");
const failure = await memory.mutate(ctx, [
"review-apply", "--session", session, "--review-json", JSON.stringify(selection), "--json",
], "The Memory review is recoverable. Present the summary again if its content changed.");
if (failure) return failure;
const selected = new Set(selection.items.map(item => item.id));
const ledgerFailure = ledger.record(ctx, session, {
type: "memory_summary_reviewed", subject: summary.summary_id,
detail: `Saved ${selected.size} cards; declined ${summary.items.length-selected.size}.`,
}, "Memory is saved. Retry to record the review and finalize.");
if (ledgerFailure) return ledgerFailure;
const message = `Memory reviewed: ${selected.size} cards saved, ${summary.items.length-selected.size} declined.`;
return workflow.close(ctx, session, phase.number, message) || toTextResult(message);
} catch (error) {
return toTextResult(`[reviewer_memory_promote] ${String(error.stderr || error.message || error).trim()}`);
}
},
});
}
export function createMemoryGate(dependencies) {
return {
install: (pi) => installMemoryGate(pi, dependencies),
install: (pi) => {
installMemoryGate(pi, dependencies);
installRepairGate(pi, dependencies);
},
reviewRecall: (ctx, params, phase) => reviewRecall(ctx, params, phase, dependencies),
};
}
harness/.pi/extensions/gate/memory/repair.js
+74
View File
@@ -0,0 +1,74 @@
import { Type } from "typebox";
export function installRepairGate(pi, { workflow, memory, waitForReviewer, toTextResult }) {
pi.registerTool({
name: "reviewer_archive_repair",
label: "Resolve Memory / Evidence conflict",
description: "Present closed archive correction choices with current and resulting content. " +
"Pass a reason and options (id, label, archive memory|evidence, target_id, revision, " +
"complete content). Only the human selects the persistent correction. " +
"Resume with repair_id from tht memory repairs --session. Never run repair-apply yourself. " +
"This gate does not approve or advance the current workflow phase.",
parameters: Type.Object({
session: Type.String(),
repair_id: Type.Optional(Type.String()),
proposal: Type.Optional(Type.Object({
reason: Type.String(), options: Type.Array(Type.Object({
id: Type.String(), label: Type.String(),
archive: Type.Union([Type.Literal("memory"), Type.Literal("evidence")]),
target_id: Type.String(), revision: Type.String(),
content: Type.Record(Type.String(), Type.Unknown()),
}), { minItems: 1, maxItems: 5 }),
})),
}),
async execute(_id, params, _signal, _update, ctx) {
workflow.activate();
try {
if (!!params.repair_id === !!params.proposal)
return toTextResult("Supply either a new proposal or an existing repair_id.");
const run = args => JSON.parse(memory.execute(ctx,
[...args, "--session", params.session, "--json"]));
let repair = params.repair_id
? run(["repair-show", "--repair-id", params.repair_id])
: run(["repair-prepare", "--proposal-json", JSON.stringify(params.proposal)]);
let error;
while (true) {
const response = await waitForReviewer(ctx, {
id: `u${Date.now()}`, schema_version: 1,
phase: workflow.phase(ctx, params.session).id,
widget: "archive-repair", title: "Resolve archive conflict",
repair, error, reserved: ["other", "back", "exit"],
});
if (response.control) return toTextResult(response.control === "freetext"
? `Reviewer feedback: ${response.text}. Reformulate the repair choices. ` +
`Existing receipt ${repair.repair_id}: ${repair.status}.`
: `Reviewer requested ${response.control}. Repair ${repair.repair_id}: ${repair.status}.`);
const selected = response.choices;
if (!Array.isArray(selected) || selected.length !== 1)
return toTextResult("Invalid archive repair selection. Present the gate again.");
const choice = selected[0];
if (choice === "continue" && (repair.choice || !repair.can_apply))
return toTextResult(JSON.stringify({ repair_id: repair.repair_id,
status: repair.status, saved: repair.saved, indexed: repair.indexed,
choice: repair.choice,
correction: repair.options.find(o => o.id === repair.choice)?.content,
next: "Continue the normal question review gates. Archive status above is authoritative." }));
if (choice !== "reject" && !repair.options.some(o => o.id === choice))
return toTextResult("Select only a displayed repair choice.");
try {
repair = run(["repair-apply", "--repair-id", repair.repair_id, "--choice", choice]);
error = undefined;
if (repair.status === "rejected")
return toTextResult("All repair proposals were rejected as inadequate. " +
"No archive was changed. Reformulate the options for the reviewer.");
} catch (failure) {
error = "The correction could not complete. Review the current archive state before retrying.";
repair = run(["repair-show", "--repair-id", repair.repair_id]);
}
}
} catch (error) {
return toTextResult(`[reviewer_archive_repair] ${String(error.stderr || error.message || error).trim()}`);
}
},
});
}