@mcoda/codali 0.1.134 → 0.1.135-codali.4

package/dist/session/WorkState.js

@@ -0,0 +1,367 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+const timestamp = () => new Date().toISOString();
+const assert = (value, message) => { if (!value)
+    throw new Error(message); };
+const unique = (values, label) => {
+    assert(values.every(v => typeof v === "string" && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/.test(v)), `Invalid ${label} id`);
+    assert(new Set(values).size === values.length, `Duplicate ${label} id`);
+};
+const taskDependencies = (state, task) => {
+    const phase = state.phases?.find(p => p.id === task.phaseId);
+    return [...new Set([...task.dependsOn, ...state.tasks.filter(t => t.phaseId && phase?.dependsOn.includes(t.phaseId)).map(t => t.id)])];
+};
+const dependenciesVerified = (state, task) => taskDependencies(state, task).every(id => state.tasks.find(t => t.id === id)?.status === "verified");
+const reopenTask = (task) => {
+    task.status = "planned";
+    task.evidenceIds = [];
+    task.attemptId = undefined;
+    task.leaseExpiresAt = undefined;
+};
+export const createWorkState = (objective, requirements) => {
+    assert(objective.trim(), "Objective is required");
+    const at = timestamp();
+    const criteria = requirements ?? [{ id: "R1", description: objective, required: true }];
+    const state = {
+        schemaVersion: 1, revision: 1, goalRevision: 1, goalId: randomUUID(), originalObjective: objective,
+        objective, requirements: criteria, constraints: [], nonGoals: [], decisions: [], evidence: [], checkpoints: [], amendments: [],
+        createdAt: at, updatedAt: at, status: "active", phases: [], planRevision: 1, planHistory: [],
+        tasks: [{ id: "T1", title: objective, requirementIds: criteria.map(c => c.id), dependsOn: [], allowedPaths: [], status: "ready", evidenceIds: [] }],
+    };
+    validateWorkState(state);
+    return state;
+};
+export const validateWorkState = (state) => {
+    assert(state.schemaVersion === 1 && Number.isSafeInteger(state.revision) && state.revision > 0 && Number.isSafeInteger(state.goalRevision) && state.goalRevision > 0, "Unsupported/invalid work-state revision");
+    assert(typeof state.objective === "string" && state.objective.trim() && typeof state.originalObjective === "string" && state.originalObjective.trim(), "Missing work objective");
+    assert(["active", "blocked", "cancelled", "completed"].includes(state.status), "Invalid goal status");
+    for (const key of ["requirements", "tasks", "decisions", "evidence", "checkpoints", "amendments", "constraints", "nonGoals"])
+        assert(Array.isArray(state[key]), `Invalid ${key}`);
+    unique(state.requirements.map(r => r.id), "requirement");
+    unique(state.tasks.map(t => t.id), "task");
+    unique(state.decisions.map(d => d.id), "decision");
+    unique(state.evidence.map(e => e.id), "evidence");
+    assert(state.requirements.length > 0, "At least one acceptance criterion is required");
+    const tasks = new Map(state.tasks.map(t => [t.id, t]));
+    const requirements = new Set(state.requirements.map(r => r.id));
+    const evidence = new Map(state.evidence.map(e => [e.id, e]));
+    const phases = state.phases ?? [];
+    assert(Array.isArray(phases) && (state.planRevision === undefined || Number.isSafeInteger(state.planRevision) && state.planRevision > 0), "Invalid plan revision/phases");
+    unique(phases.map(p => p.id), "phase");
+    for (const phase of phases) {
+        assert(typeof phase.title === "string" && phase.title.trim(), `Phase ${phase.id}: missing title`);
+        assert(Array.isArray(phase.dependsOn) && phase.dependsOn.every(id => id !== phase.id && phases.some(p => p.id === id)), `Phase ${phase.id}: missing/self dependency`);
+        assert(Array.isArray(phase.exitRequirementIds) && phase.exitRequirementIds.length > 0 && phase.exitRequirementIds.every(id => requirements.has(id)), `Phase ${phase.id}: invalid exit criteria`);
+        assert(state.tasks.some(t => t.phaseId === phase.id), `Phase ${phase.id}: no tasks`);
+        assert(phase.exitRequirementIds.every(id => state.tasks.some(t => t.phaseId === phase.id && t.requirementIds.includes(id))), `Phase ${phase.id}: uncovered exit criterion`);
+    }
+    for (const r of state.requirements)
+        assert(typeof r.description === "string" && r.description.trim() && typeof r.required === "boolean", "Invalid acceptance criterion");
+    for (const task of state.tasks) {
+        assert(typeof task.title === "string" && task.title.trim(), `Task ${task.id}: missing title`);
+        assert(["planned", "ready", "running", "review_pending", "verified", "blocked", "cancelled", "superseded"].includes(task.status), `Task ${task.id}: invalid status`);
+        assert(Array.isArray(task.dependsOn) && Array.isArray(task.requirementIds) && Array.isArray(task.allowedPaths) && Array.isArray(task.evidenceIds), `Task ${task.id}: invalid arrays`);
+        assert(task.requirementIds.length > 0 && task.requirementIds.every(r => requirements.has(r)), `Task ${task.id}: unknown/missing requirement`);
+        assert(task.dependsOn.every(id => tasks.has(id) && id !== task.id), `Task ${task.id}: missing/self dependency`);
+        assert(!task.phaseId || phases.some(p => p.id === task.phaseId), `Task ${task.id}: unknown phase`);
+        for (const file of task.allowedPaths)
+            assert(typeof file === "string" && !path.isAbsolute(file) && !file.split(/[\\/]/).includes(".."), `Task ${task.id}: invalid path`);
+        assert(task.evidenceIds.every(id => evidence.get(id)?.taskId === task.id), `Task ${task.id}: invalid evidence reference`);
+    }
+    const visited = new Set();
+    const visiting = new Set();
+    const visit = (id) => {
+        assert(!visiting.has(id), `Task dependency cycle at ${id}`);
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        const task = tasks.get(id);
+        const phase = phases.find(p => p.id === task.phaseId);
+        const dependencies = [...task.dependsOn, ...state.tasks.filter(t => t.phaseId && phase?.dependsOn.includes(t.phaseId)).map(t => t.id)];
+        for (const dep of dependencies)
+            visit(dep);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const task of state.tasks)
+        visit(task.id);
+    for (const criterion of state.requirements.filter(r => r.required)) {
+        assert(state.tasks.some(t => !["cancelled", "superseded"].includes(t.status) && t.requirementIds.includes(criterion.id)), `Uncovered requirement: ${criterion.id}. Link this existing ID in task.requirementIds rather than inventing a replacement. Put whole-request R1 on the final integration task.`);
+    }
+};
+export const refreshReadyTasks = (state) => {
+    for (const task of state.tasks)
+        if (task.status === "planned" || task.status === "ready") {
+            task.status = dependenciesVerified(state, task) ? "ready" : "planned";
+        }
+};
+export const replaceWorkPlan = (state, tasks, phases = state.phases ?? [], reason = "Task plan refined") => {
+    assert(!state.tasks.some(t => ["running", "review_pending"].includes(t.status)), "Finish the current attempt or call work_release with its taskId and attemptId before replacing the plan");
+    const existing = new Map(state.tasks.map(t => [t.id, t]));
+    const next = tasks.map(t => {
+        const old = existing.get(t.id);
+        if (old?.status === "verified") {
+            assert(JSON.stringify([old.title, old.requirementIds, old.dependsOn, old.allowedPaths, old.phaseId]) === JSON.stringify([t.title, t.requirementIds, t.dependsOn, t.allowedPaths, t.phaseId]), `Cannot silently rewrite verified task ${t.id}`);
+            return old;
+        }
+        return { ...t, status: "planned", evidenceIds: [] };
+    });
+    for (const old of state.tasks.filter(t => t.status === "verified"))
+        assert(next.some(t => t.id === old.id), `Cannot remove verified task ${old.id}`);
+    const candidate = { ...state, tasks: next, phases };
+    validateWorkState(candidate);
+    const phaseContract = (all, id) => {
+        const selected = new Map();
+        const add = (phaseId) => {
+            const phase = all.find(p => p.id === phaseId);
+            if (!phase || selected.has(phaseId))
+                return;
+            selected.set(phaseId, phase);
+            phase.dependsOn.forEach(add);
+        };
+        if (id)
+            add(id);
+        return [...selected.values()].sort((a, b) => a.id.localeCompare(b.id));
+    };
+    for (const task of next.filter(t => t.status === "verified")) {
+        assert(JSON.stringify(phaseContract(state.phases ?? [], task.phaseId)) === JSON.stringify(phaseContract(phases, task.phaseId)), `Cannot silently rewrite the phase contract of verified task ${task.id}`);
+        assert(dependenciesVerified(candidate, task), `Verified task ${task.id} has an unverified prerequisite in the revised plan`);
+    }
+    state.planHistory ?? (state.planHistory = []);
+    state.planHistory.push({ revision: state.planRevision ?? 1, goalRevision: state.goalRevision, at: timestamp(), reason, tasks: structuredClone(state.tasks), phases: structuredClone(state.phases ?? []) });
+    state.planRevision = (state.planRevision ?? 1) + 1;
+    state.tasks = next;
+    state.phases = structuredClone(phases);
+    refreshReadyTasks(state);
+};
+/** Update named contracts while retaining every unmentioned task and phase. */
+export const updateWorkPlan = (state, updates, phaseUpdates = [], reason = "Task plan updated") => {
+    unique(updates.map(task => task.id), "task update");
+    unique(phaseUpdates.map(phase => phase.id), "phase update");
+    const tasks = new Map(state.tasks.map(task => [task.id, task]));
+    const phases = new Map((state.phases ?? []).map(phase => [phase.id, phase]));
+    for (const task of updates)
+        tasks.set(task.id, { ...task, status: "planned", evidenceIds: [] });
+    for (const phase of phaseUpdates)
+        phases.set(phase.id, phase);
+    // Reuse the same coverage, verified-contract, dependency and lease fences.
+    const candidate = structuredClone(state);
+    replaceWorkPlan(candidate, [...tasks.values()], [...phases.values()], reason);
+    const updatedIds = new Set(updates.map(task => task.id));
+    candidate.tasks = candidate.tasks.map(task => {
+        const old = state.tasks.find(previous => previous.id === task.id);
+        return old && !updatedIds.has(task.id) && ["blocked", "cancelled", "superseded"].includes(old.status) ? structuredClone(old) : task;
+    });
+    validateWorkState(candidate);
+    refreshReadyTasks(candidate);
+    Object.assign(state, candidate);
+};
+export const claimWorkTask = (state, taskId, leaseMs = 300000) => {
+    assert(state.status === "active", "Goal is not active");
+    refreshReadyTasks(state);
+    const task = state.tasks.find(t => t.id === taskId);
+    assert(task?.status === "ready", "Task is not ready");
+    assert(!state.tasks.some(t => ["running", "review_pending"].includes(t.status)), "A task already owns this workspace");
+    assert(Number.isFinite(leaseMs) && leaseMs > 0, "Invalid lease");
+    task.status = "running";
+    task.attemptId = randomUUID();
+    task.goalRevision = state.goalRevision;
+    task.planRevision = state.planRevision ?? 1;
+    task.leaseExpiresAt = new Date(Date.now() + leaseMs).toISOString();
+    return task;
+};
+export const releaseWorkTask = (state, taskId, attemptId, note) => {
+    const task = state.tasks.find(t => t.id === taskId);
+    assert(task && ["running", "review_pending"].includes(task.status) && task.attemptId === attemptId, "Cannot release a stale or inactive task attempt");
+    assert(note.trim(), "Explain why the attempt is released and what changes next");
+    state.checkpoints.push({ id: randomUUID(), at: timestamp(), goalRevision: state.goalRevision,
+        activeTaskId: taskId, note: `Released attempt ${attemptId}: ${note}`, uncertainInvocationIds: [] });
+    reopenTask(task);
+    refreshReadyTasks(state);
+};
+/** Withdraw a disproven verification and fence all dependent attempts without rewriting the plan. */
+export const reopenVerifiedTask = (state, taskId, reason) => {
+    const task = state.tasks.find(t => t.id === taskId);
+    assert(state.status === "active" && task?.status === "verified", "Only a verified task in an active goal can be reopened");
+    assert(reason.trim(), "Explain the new evidence that disproves this verification");
+    const affected = new Set([taskId]);
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const candidate of state.tasks)
+            if (!affected.has(candidate.id) && !["cancelled", "superseded"].includes(candidate.status)
+                && taskDependencies(state, candidate).some(id => affected.has(id))) {
+                affected.add(candidate.id);
+                changed = true;
+            }
+    }
+    for (const candidate of state.tasks)
+        if (affected.has(candidate.id))
+            reopenTask(candidate);
+    state.checkpoints.push({ id: randomUUID(), at: timestamp(), goalRevision: state.goalRevision,
+        activeTaskId: taskId, note: `Reopened verified task ${taskId}; invalidated ${[...affected].join(", ")}: ${reason}`, uncertainInvocationIds: [] });
+    refreshReadyTasks(state);
+    return [...affected];
+};
+export const assertWorkAttempt = (state, taskId, attemptId) => {
+    const task = state.tasks.find(t => t.id === taskId);
+    assert(state.status === "active" && task && ["running", "review_pending"].includes(task.status) && task.attemptId === attemptId && task.goalRevision === state.goalRevision, "Stale task attempt or goal revision");
+    assert(Date.parse(task.leaseExpiresAt ?? "") > Date.now(), "Task lease expired; reconcile before retrying");
+    assert(task.planRevision === undefined || task.planRevision === (state.planRevision ?? 1), "Stale plan revision");
+    assert(dependenciesVerified(state, task), "Task prerequisite was invalidated; reconcile before continuing");
+    return task;
+};
+export const recordWorkEvidence = (state, taskId, attemptId, evidence) => {
+    const task = assertWorkAttempt(state, taskId, attemptId);
+    assert(evidence.taskId === taskId && evidence.criterionIds.length > 0 && evidence.criterionIds.every(id => task.requirementIds.includes(id)), "Evidence does not match the task criteria");
+    assert(evidence.kind !== "tool" || evidence.invocationId, "Tool evidence requires an invocation receipt");
+    const previous = state.evidence.find(e => e.id === evidence.id);
+    if (previous) {
+        assert(JSON.stringify(previous) === JSON.stringify(evidence), "Conflicting evidence id");
+        return;
+    }
+    state.evidence.push(evidence);
+    task.evidenceIds.push(evidence.id);
+    task.status = "review_pending";
+};
+export const verifyWorkTask = (state, taskId, attemptId, currentHashes) => {
+    const task = assertWorkAttempt(state, taskId, attemptId);
+    const applicable = state.evidence.filter(e => task.evidenceIds.includes(e.id) && e.ok && Object.entries(e.inputHashes).every(([file, hash]) => currentHashes[file] === hash));
+    for (const requirement of task.requirementIds)
+        assert(applicable.some(e => e.criterionIds.includes(requirement)), `Unverified/stale criterion: ${requirement}`);
+    task.status = "verified";
+    refreshReadyTasks(state);
+};
+/** Reopen stale proofs and their dependent tasks without discarding audit history. */
+export const refreshStaleEvidence = (state, currentHashes) => {
+    const reopened = [];
+    let changed = true;
+    while (changed) {
+        changed = false;
+        for (const task of state.tasks.filter(t => ["verified", "running", "review_pending"].includes(t.status))) {
+            const proofs = state.evidence.filter(e => task.evidenceIds.includes(e.id) && e.ok && Object.entries(e.inputHashes).every(([file, hash]) => currentHashes[file] === hash));
+            if ((task.status !== "verified" || task.requirementIds.every(id => proofs.some(e => e.criterionIds.includes(id)))) && dependenciesVerified(state, task))
+                continue;
+            reopenTask(task);
+            reopened.push(task.id);
+            changed = true;
+        }
+    }
+    if (reopened.length && state.status === "completed")
+        state.status = "active";
+    refreshReadyTasks(state);
+    return reopened;
+};
+export const amendWorkGoal = (state, objective, reason) => {
+    assert(objective.trim() && reason.trim(), "Goal amendment needs an objective and reason");
+    state.amendments.push({ revision: state.goalRevision, at: timestamp(), reason, previousObjective: state.objective });
+    state.goalRevision += 1;
+    state.objective = objective;
+    state.status = "active";
+    const criterionId = `steering-${state.goalRevision}`;
+    state.requirements.push({ id: criterionId, description: reason, required: true });
+    state.tasks.push({ id: criterionId, title: reason, requirementIds: [criterionId], dependsOn: [], allowedPaths: [], status: "planned", evidenceIds: [] });
+    for (const task of state.tasks)
+        if (!["cancelled", "superseded"].includes(task.status)) {
+            task.status = "planned";
+            task.attemptId = undefined;
+            task.leaseExpiresAt = undefined;
+            task.evidenceIds = [];
+        }
+    refreshReadyTasks(state);
+};
+export const recordDecision = (state, decision) => {
+    assert(decision.title.trim() && decision.rationale.trim(), "Decision requires a title and rationale");
+    assert(!state.decisions.some(d => d.id === decision.id), "Decision id already exists");
+    if (decision.supersedes)
+        assert(state.decisions.some(d => d.id === decision.supersedes), "Superseded decision does not exist");
+    if (decision.supersedes)
+        assert(!state.decisions.some(d => d.supersedes === decision.supersedes), "Decision was already superseded; supersede its current replacement");
+    state.decisions.push(decision);
+    if (decision.supersedes) {
+        const previous = state.decisions.find(d => d.id === decision.supersedes);
+        const affected = [...previous.paths, ...decision.paths];
+        const invalidated = new Set();
+        for (const task of state.tasks)
+            if (["verified", "running", "review_pending"].includes(task.status) && (!affected.length || !task.allowedPaths.length || task.allowedPaths.some(scope => affected.some(file => scope === "." || file === scope || file.startsWith(`${scope}/`) || scope.startsWith(`${file}/`))))) {
+                reopenTask(task);
+                invalidated.add(task.id);
+            }
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const task of state.tasks)
+                if (!invalidated.has(task.id) && !["cancelled", "superseded"].includes(task.status) && taskDependencies(state, task).some(id => invalidated.has(id))) {
+                    reopenTask(task);
+                    invalidated.add(task.id);
+                    changed = true;
+                }
+        }
+        if (invalidated.size && state.status === "completed")
+            state.status = "active";
+        refreshReadyTasks(state);
+    }
+};
+export const completeWorkGoal = (state, currentHashes, uncertainInvocationIds = []) => {
+    validateWorkState(state);
+    assert(state.status === "active" && uncertainInvocationIds.length === 0, "Goal cannot complete with unresolved side effects");
+    assert(state.tasks.every(t => ["verified", "cancelled", "superseded"].includes(t.status)), "Required task work remains");
+    for (const criterion of state.requirements.filter(r => r.required)) {
+        const tasks = state.tasks.filter(t => t.requirementIds.includes(criterion.id) && t.status === "verified");
+        assert(tasks.length > 0 && tasks.every(t => state.evidence.some(e => t.evidenceIds.includes(e.id) && e.ok && e.criterionIds.includes(criterion.id) && Object.entries(e.inputHashes).every(([file, hash]) => currentHashes[file] === hash))), `Unverified/stale criterion: ${criterion.id}`);
+    }
+    state.status = "completed";
+};
+export const workContext = (state) => JSON.stringify({
+    goalId: state.goalId, goalRevision: state.goalRevision, planRevision: state.planRevision ?? 1, phases: state.phases ?? [], objective: state.objective,
+    originalObjective: state.originalObjective, requirements: state.requirements, constraints: state.constraints,
+    nonGoals: state.nonGoals, tasks: state.tasks.map(t => ({ id: t.id, title: t.title, phaseId: t.phaseId, status: t.status, dependsOn: t.dependsOn, requirementIds: t.requirementIds, allowedPaths: t.allowedPaths, attemptId: t.attemptId, blocker: t.blocker })),
+    decisions: state.decisions, checkpoint: state.checkpoints.at(-1),
+});
+/** Keep the active contract intact while paging unrelated backlog out of context. */
+export const activeWorkContext = (state, maxChars) => {
+    const full = workContext(state);
+    if (full.length <= maxChars)
+        return full;
+    const active = state.tasks.find(t => ["running", "review_pending"].includes(t.status)) ?? state.tasks.find(t => t.status === "ready");
+    const requiredIds = new Set(active?.requirementIds ?? []);
+    const superseded = new Set(state.decisions.map(d => d.supersedes).filter(Boolean));
+    const relevant = (paths) => !active || !paths.length || !active.allowedPaths.length || paths.some(file => active.allowedPaths.some(scope => scope === "." || file === scope || file.startsWith(`${scope}/`) || scope.startsWith(`${file}/`)));
+    const currentDecisions = state.decisions.filter(d => !superseded.has(d.id) && relevant(d.paths));
+    const view = {
+        goalId: state.goalId, goalRevision: state.goalRevision, planRevision: state.planRevision ?? 1,
+        objective: state.objective, originalObjective: state.originalObjective, constraints: state.constraints, nonGoals: state.nonGoals,
+        activeTask: active,
+        requirements: state.requirements.filter(r => requiredIds.has(r.id)),
+        decisions: currentDecisions,
+        phases: state.phases?.filter(p => p.id === active?.phaseId),
+        prerequisiteTasks: active ? taskDependencies(state, active).map(id => {
+            const task = state.tasks.find(t => t.id === id);
+            return { id, title: task.title, status: task.status };
+        }) : [],
+        taskCounts: Object.fromEntries([...new Set(state.tasks.map(t => t.status))].map(status => [status, state.tasks.filter(t => t.status === status).length])),
+        totalRequirements: state.requirements.length,
+        otherRequirements: [],
+        nextTasks: [],
+        contextPartial: true,
+        continuation: "The complete goal and backlog remain canonical in storage. Use work_status with offset/limit or taskIds/requirementIds to retrieve omitted records. Claiming a task loads its full criteria and relevant decisions. Completion still checks every required criterion.",
+    };
+    const encode = () => JSON.stringify(view);
+    if (encode().length > maxChars)
+        throw new Error("Active goal, constraints, architecture decisions and criteria exceed the context reservation; use a larger compatible model context or split the active task");
+    for (const requirement of state.requirements.filter(r => !requiredIds.has(r.id))) {
+        view.otherRequirements.push(requirement);
+        if (encode().length > maxChars) {
+            view.otherRequirements.pop();
+            break;
+        }
+    }
+    for (const task of state.tasks.filter(t => t.id !== active?.id && !["verified", "cancelled", "superseded"].includes(t.status))) {
+        view.nextTasks.push({ id: task.id, title: task.title, status: task.status });
+        if (encode().length > maxChars) {
+            view.nextTasks.pop();
+            break;
+        }
+    }
+    return encode();
+};

package/dist/session/WorkTypes.d.ts

@@ -0,0 +1,94 @@
+import type { ProjectTaskAttachment } from "@mcoda/shared";
+export type WorkTaskStatus = "planned" | "ready" | "running" | "review_pending" | "verified" | "blocked" | "cancelled" | "superseded";
+export interface Requirement {
+    id: string;
+    description: string;
+    required: boolean;
+}
+export interface WorkTask {
+    id: string;
+    title: string;
+    requirementIds: string[];
+    dependsOn: string[];
+    allowedPaths: string[];
+    status: WorkTaskStatus;
+    evidenceIds: string[];
+    attemptId?: string;
+    goalRevision?: number;
+    leaseExpiresAt?: string;
+    blocker?: string;
+    phaseId?: string;
+    planRevision?: number;
+}
+export interface WorkPhase {
+    id: string;
+    title: string;
+    dependsOn: string[];
+    exitRequirementIds: string[];
+}
+export interface PlanRevision {
+    revision: number;
+    goalRevision: number;
+    at: string;
+    reason: string;
+    tasks: WorkTask[];
+    phases: WorkPhase[];
+}
+export interface DecisionRecord {
+    id: string;
+    title: string;
+    rationale: string;
+    alternatives: string[];
+    paths: string[];
+    supersedes?: string;
+}
+export interface EvidenceReceipt {
+    id: string;
+    taskId: string;
+    criterionIds: string[];
+    kind: "tool" | "review" | "human";
+    ok: boolean;
+    summary: string;
+    invocationId?: string;
+    inputHashes: Record<string, string>;
+    at: string;
+}
+export interface WorkCheckpoint {
+    id: string;
+    at: string;
+    goalRevision: number;
+    note: string;
+    activeTaskId?: string;
+    uncertainInvocationIds: string[];
+}
+export interface GoalAmendment {
+    revision: number;
+    at: string;
+    reason: string;
+    previousObjective: string;
+}
+export interface WorkState {
+    projectTask?: ProjectTaskAttachment;
+    schemaVersion: 1;
+    revision: number;
+    goalRevision: number;
+    goalId: string;
+    originalObjective: string;
+    objective: string;
+    requirements: Requirement[];
+    constraints: string[];
+    nonGoals: string[];
+    tasks: WorkTask[];
+    /** Optional on older v1 records; absence means the initial flat plan. */
+    phases?: WorkPhase[];
+    planRevision?: number;
+    planHistory?: PlanRevision[];
+    decisions: DecisionRecord[];
+    evidence: EvidenceReceipt[];
+    checkpoints: WorkCheckpoint[];
+    amendments: GoalAmendment[];
+    createdAt: string;
+    updatedAt: string;
+    status: "active" | "blocked" | "cancelled" | "completed";
+}
+//# sourceMappingURL=WorkTypes.d.ts.map

package/dist/session/WorkTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WorkTypes.d.ts","sourceRoot":"","sources":["../../src/session/WorkTypes.ts"],"names":[],"mappings":"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"}

package/dist/session/WorkTypes.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/ToolRegistry.d.ts

@@ -12,6 +12,8 @@ export declare class ToolRegistry {
     private tools;
     register(tool: ToolDefinition): void;
     list(): ToolDefinition[];
+    /** Trusted host lifecycle operation; never exposed as an agent tool. */
+    unregister(name: string): void;
     describe(): Array<Pick<ToolDefinition, "name" | "description" | "inputSchema">>;
     /**
      * Model-facing view of the registry, optionally narrowed to a set of tool

package/dist/tools/ToolRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EAGnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAE1B,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,cAAc,KAAG,cAOvD,CAAC;AA4HH,eAAO,MAAM,qBAAqB,GAChC,OAAO,OAAO,EACd,QAAQ,oBAAoB,GAAG,SAAS,KACvC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAwBrC,CAAC;AAyLF,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqC;IAElD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAOpC,IAAI,IAAI,cAAc,EAAE;IAIxB,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC;IAQ/E;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,EAAE;IAOpD,2EAA2E;IAC3E,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,EAAE,cAAc,EAAE,CAAC;IAaxE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAwC/F"}
+{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/tools/ToolRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,cAAc,EAGnB,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EAE1B,MAAM,gBAAgB,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,cAAc,KAAG,cAOvD,CAAC;AA4HH,eAAO,MAAM,qBAAqB,GAChC,OAAO,OAAO,EACd,QAAQ,oBAAoB,GAAG,SAAS,KACvC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAwBrC,CAAC;AAyLF,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAqC;IAElD,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAOpC,IAAI,IAAI,cAAc,EAAE;IAIxB,wEAAwE;IACxE,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAE9B,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC,CAAC;IAQ/E;;;;OAIG;IACH,OAAO,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,EAAE;IAOpD,2EAA2E;IAC3E,YAAY,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,cAAc,EAAE,cAAc,EAAE,CAAC;IAaxE,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAgD/F"}

package/dist/tools/ToolRegistry.js

@@ -339,6 +339,8 @@ export class ToolRegistry {
     list() {
         return Array.from(this.tools.values());
     }
+    /** Trusted host lifecycle operation; never exposed as an agent tool. */
+    unregister(name) { this.tools.delete(name); }
     describe() {
         return this.list().map((tool) => ({
             name: tool.name,
@@ -396,16 +398,24 @@ export class ToolRegistry {
         if (validationError) {
             return { ok: false, output: "", error: validationError };
         }
+        let execution;
         try {
+            context.signal?.throwIfAborted();
+            await context.beforeTool?.(toolDescriptorFor(tool), sanitized.value);
+            context.signal?.throwIfAborted();
             const result = await tool.handler(sanitized.value, context);
-            return { ok: true, output: result.output, data: result.data };
+            execution = { ok: true, output: result.output, data: result.data };
         }
         catch (error) {
-            return {
+            execution = {
                 ok: false,
                 output: "",
                 error: normalizeExecutionError(error),
             };
         }
+        // Persistence failures must stop the run, not silently acknowledge a side effect.
+        await context.afterTool?.(toolDescriptorFor(tool), sanitized.value, execution);
+        context.signal?.throwIfAborted();
+        return execution;
     }
 }

package/dist/tools/ToolTypes.d.ts

@@ -1,4 +1,15 @@
 export interface ToolContext {
+    signal?: AbortSignal;
+    onOutput?: (stream: "stdout" | "stderr", chunk: string) => void;
+    beforeTool?: (tool: ToolDescriptor, args: unknown) => Promise<void>;
+    afterTool?: (tool: ToolDescriptor, args: unknown, result: ToolExecutionResult) => Promise<void>;
+    checkPath?: (resolvedPath: string, action: "read" | "write") => Promise<void>;
+    shellTimeoutMs?: number;
+    shellMaxOutputBytes?: number;
+    /** Process cwd inside workspaceRoot; does not change root-relative write scopes. */
+    shellWorkingDirectory?: string;
+    /** Optional trusted executor wrapper, applied after permission evaluation. */
+    shellExecutor?: (command: string, args: string[], context: ToolContext) => Promise<ToolHandlerResult>;
     workspaceRoot: string;
     runId?: string;
     recordTouchedFile?: (path: string) => void;
@@ -55,6 +66,11 @@ export interface ToolHandlerResult {
 export interface ToolExecutionResult extends ToolHandlerResult {
     ok: boolean;
     error?: ToolError;
+    /** Set by the host's afterTool hook; retained outside output truncation. */
+    invocationReceipt?: {
+        id: string;
+        reference: string;
+    };
 }
 export type ToolHandler = (args: unknown, context: ToolContext) => Promise<ToolHandlerResult>;
 /**

package/dist/tools/ToolTypes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolTypes.d.ts","sourceRoot":"","sources":["../../src/tools/ToolTypes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ToolTypes.d.ts","sourceRoot":"","sources":["../../src/tools/ToolTypes.ts"],"names":[],"mappings":"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"}

package/dist/tools/docdex/DocdexTools.d.ts

@@ -35,6 +35,8 @@ export type RelevanceJudge = (input: {
 }) => Promise<boolean>;
 export interface DocdexToolOptions {
     judgeRelevance?: RelevanceJudge;
+    /** Terminal clients authorize web research as a separate operation. */
+    allowSearchWebFallback?: boolean;
 }
 export declare const createDocdexTools: (client: DocdexClient, options?: DocdexToolOptions) => ToolDefinition[];
 //# sourceMappingURL=DocdexTools.d.ts.map

package/dist/tools/docdex/DocdexTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAuFjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,GAAG,SAAS,EACzB,gBAAgB,MAAM,KACrB,MAAM,GAAG,SAWX,CAAC;AAwCF,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,QAAO,IAG1C,CAAC;AA0DF,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAO3D,CAAC;AAoHF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAgE,CAAC"}
+{"version":3,"file":"DocdexTools.d.ts","sourceRoot":"","sources":["../../../src/tools/docdex/DocdexTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAwFjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,OAAO,MAAM,GAAG,SAAS,EACzB,gBAAgB,MAAM,KACrB,MAAM,GAAG,SAWX,CAAC;AAwCF,0CAA0C;AAC1C,eAAO,MAAM,uBAAuB,QAAO,IAG1C,CAAC;AA0DF,eAAO,MAAM,iBAAiB,GAAI,OAAO,OAAO,KAAG,MAAM,GAAG,SAO3D,CAAC;AAoHF;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,iBAAiB;IAChC,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,YAAY,EACpB,UAAS,iBAAsB,KAC9B,cAAc,EAAiG,CAAC"}

package/dist/tools/docdex/DocdexTools.js

@@ -14,6 +14,7 @@ const DOCDEX_WRITE_TOOLS = new Set([
     "docdex_memory_save",
     "docdex_save_preference",
     "docdex_delegate",
+    "docdex_diary_write",
 ]);
 /**
  * Docdex is one capability from the orchestrator's point of view, except web
@@ -313,7 +314,21 @@ const withDocdexMetadata = (tools) => tools.map((tool) => ({
     readOnly: tool.readOnly ?? !DOCDEX_WRITE_TOOLS.has(tool.name),
     capability: tool.capability ?? docdexCapabilityFor(tool.name),
 }));
-export const createDocdexTools = (client, options = {}) => withDocdexMetadata(docdexToolDefinitions(client, options));
+export const createDocdexTools = (client, options = {}) => withDocdexMetadata([...docdexToolDefinitions(client, options), ...continuityTools(client)]);
+const continuityTools = (client) => {
+    const single = (name, description, key, call) => ({
+        name, description, inputSchema: { type: "object", properties: { [key]: { type: "string", minLength: 1, maxLength: 12000 } }, required: [key], additionalProperties: false },
+        handler: async (args) => toOutput(await call(args[key])),
+    });
+    return [
+        single("docdex_wakeup", "Read bounded continuity context for this repository and agent. Canonical goal and authorization remain authoritative.", "query", query => client.wakeup(query)),
+        single("docdex_conversation_search", "Find source-linked prior conversation records in this repository.", "query", query => client.conversationSearch(query)),
+        single("docdex_conversation_read", "Read a prior repository conversation by its returned session ID.", "sessionId", id => client.conversationRead(id)),
+        single("docdex_kg_query", "Inspect temporal knowledge-graph facts and provenance for this repository.", "query", query => client.knowledgeQuery(query)),
+        single("docdex_diary_write", "Save a concise durable handoff with the current goal, observed outcome and next action. Requires memory-write permission.", "content", content => client.diaryWrite(content)),
+        { name: "docdex_diary_read", description: "Read the agent's recent durable repository handoffs.", inputSchema: { type: "object", properties: {}, additionalProperties: false }, handler: async () => toOutput(await client.diaryRead()) },
+    ];
+};
 const docdexToolDefinitions = (client, options) => [
     {
         name: "docdex_health",
@@ -377,7 +392,7 @@ const docdexToolDefinitions = (client, options) => [
                 }
             }
             const webQuery = normalizeWebQuery(query);
-            if (!localAnswers && webQuery && !webResearchBlocked()) {
+            if (options.allowSearchWebFallback !== false && !localAnswers && webQuery && !webResearchBlocked()) {
                 try {
                     const web = await client.search(webQuery, { limit, forceWeb: true });
                     if (hasWebFindings(web)) {

package/dist/tools/filesystem/FileTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAgEnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAgGhD,CAAC"}
+{"version":3,"file":"FileTools.d.ts","sourceRoot":"","sources":["../../../src/tools/filesystem/FileTools.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAe,cAAc,EAAE,MAAM,iBAAiB,CAAC;AA8EnE,eAAO,MAAM,eAAe,QAAO,cAAc,EAkGhD,CAAC"}