oh-my-llmwikimode 1.5.0 → 1.6.0

package/docs/design/EOS_CHAT_HOME_IA.md

@@ -101,6 +101,9 @@ Do not use these labels in the Eos Chat MVP:
 - `GET /workspace` redirects to `/workspace/`.
 - `GET /side-review/` serves the review desk for local artifacts, evidence, and prepare-only decision notes.
 - `GET /api/home` remains a read-only home data snapshot.
+- `POST /api/agent/side-review/approval-requests` prepares a review-required approval request from an existing `prepare_approval` Side Review decision artifact only.
+- `GET /api/workspace/artifacts/inspect` returns whitelisted read-only artifact inspector data by `{type,id}` only.
+- `GET /api/workspace/timeline-status` returns a local lifecycle timeline/status panel derived from EOS local artifacts only.
 - `POST /api/chat/requests` creates a review-required local artifact only.
 
 ## 12. Browser-first Workspace Slice
@@ -166,3 +169,22 @@ Stable fields:
 - `review_queue.side_review_decision_recent`: latest prepared decision artifacts for the right inspector/Home summary
 
 The snapshot is a read model only. It must not become an execution queue, approval queue, hosted sync contract, or source wiki mutation path.
+
+## 14. Approval Inspector workspace slice - 2026-06-01
+
+`EOS Workspace` now includes an Approval Queue and Artifact Inspector for review-required approval request artifacts.
+
+Stable surfaces:
+
+- `review_queue.approval_request_recent`: latest local approval request artifacts visible in Home/Workspace.
+- `approval_surface`: local approval queue metadata and route hints for the browser workbench.
+- `/api/agent/side-review/approval-requests`: prepare-only route from `prepare_approval` Side Review decisions to approval request artifacts.
+- `/api/workspace/artifacts/inspect`: safe inspector route for whitelisted artifact types and ids.
+- `/api/workspace/timeline-status`: local lifecycle timeline and Timeline Gate status.
+- Workspace regions: `Approval Queue`, `Artifact Inspector`, `Lifecycle Timeline`, and `Timeline Gate`.
+
+Safety contract:
+
+- Approval Queue is a review queue, not an execution queue.
+- Artifact Inspector must reject raw local paths, traversal, unsupported types, symlinks, oversized artifacts, and malformed JSON without leaking secrets or user-home paths.
+- Timeline Gate may show `approved_not_executed`, but this is a review state only. It must not imply shell, git, provider, Discord, sync, publish, merge, push, or source wiki mutation work has happened.

package/docs/design/EOS_DESIGN.md

@@ -339,3 +339,36 @@ Verification anchors:
 - `test/eos/uiux-product-shape.test.js`
 - `npm run test:eos`
 - `npm run verify:eos-workspace-completion`
+
+## Implemented EOS Workspace Approval Inspector Slice - 2026-06-01
+
+The EOS Workspace Approval Inspector slice makes approval requests first-class local review artifacts inside the browser-first workbench.
+
+What changed:
+
+- Approval request artifacts now live under `.system/eos/approval/requests/` with review-required lifecycle statuses, deterministic duplicate handling, and append-only audit metadata.
+- `GET /api/home` includes a local approval queue summary with recent approval request artifacts.
+- `POST /api/agent/side-review/approval-requests` prepares an approval request only from an existing `prepare_approval` Side Review decision artifact.
+- `GET /api/workspace/artifacts/inspect` exposes a whitelisted, read-only artifact inspector for approval requests and adjacent EOS artifacts.
+- `GET /api/workspace/timeline-status` exposes a local-only lifecycle timeline/status panel derived from chat, Side Review, approval, visual QA, and local evidence artifacts.
+- `/workspace/` renders Approval Queue, Artifact Inspector, Lifecycle Timeline, and Timeline Gate surfaces with Local Only, Review Required, and Not Applied safety labels.
+- Browser product evidence is captured under `.omo/ulw-loop/evidence/eos-approval-inspector-20260601/`.
+
+Boundary:
+
+- The slice remains web-service first, not a VS Code extension or VSIX.
+- Approval statuses such as `approved_not_executed` mean explicit review state only; they do not execute shell, git, provider, Discord, or wiki mutation actions.
+- Side Review approval request creation is prepare-only; it creates a local review artifact and never applies the underlying decision.
+- The inspector reads only whitelisted local artifacts by type/id, rejects raw paths and traversal, redacts secrets and user-home paths, and degrades safely on malformed artifacts.
+- This slice does not add hosted sync, production Discord control, marketplace/account/payment features, package splitting, npm publish, auto-apply, auto-promotion, auto-merge/delete, auto-push, hidden execution, or source wiki mutation.
+
+Verification anchors:
+
+- `test/eos/approval-request-artifacts.test.js`
+- `test/eos/approval-queue-read-model.test.js`
+- `test/eos/side-review-approval-requests.test.js`
+- `test/eos/artifact-inspector-view-model.test.js`
+- `test/eos/workspace-approval-inspector-routes.test.js`
+- `test/eos/timeline-status-panel.test.js`
+- `test/eos/approval-inspector-gate.test.js`
+- `npm run verify:eos-approval-inspector`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-llmwikimode",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "LLM Wiki plugin for OpenCode ??auto-memory, retrieval, and knowledge promotion",
   "type": "module",
   "main": "./src/server.js",
@@ -30,6 +30,7 @@
     "test:eos": "node --test test/eos/**/*.test.js",
     "verify:eos-workspace-product": "npm run test:eos && npm run verify:eos-boundary-policy && npm run verify:eos-boundary && npm run eos:a11y-snapshot -- --json",
     "verify:eos-workspace-completion": "node scripts/verify-eos-workspace-completion.js",
+    "verify:eos-approval-inspector": "node scripts/verify-eos-approval-inspector.js",
     "verify:package": "node test/verify-package.test.js",
     "verify:docs": "node test/verify-docs.test.js",
     "verify:side-effects": "node scripts/side-effect-audit.js",

package/src/eos/approval/artifacts.js

@@ -0,0 +1,164 @@
+import { appendFile, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import {
+  APPROVAL_REQUEST_STATUSES,
+  createApprovalAuditEntry,
+  createApprovalRequestArtifact,
+  validateApprovalRequest,
+} from "./contract.js";
+
+export { APPROVAL_REQUEST_STATUSES } from "./contract.js";
+
+const AUDIT_ACTIONS = Object.freeze([
+  "approval_requested",
+  "reject_approval_request",
+]);
+
+function resolveUnderWikiRoot(wikiRoot, relativePath) {
+  const root = path.resolve(wikiRoot);
+  const target = path.resolve(root, ...relativePath.split("/"));
+  const relative = path.relative(root, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes wiki root");
+  }
+  return target;
+}
+
+function resolveRequestArtifactPath(wikiRoot, relativePath) {
+  const target = resolveUnderWikiRoot(wikiRoot, relativePath);
+  const requestsRoot = path.resolve(getApprovalArtifactPaths(wikiRoot).requests);
+  const relative = path.relative(requestsRoot, target);
+  if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error("Eos approval artifact path escapes requests directory");
+  }
+  return target;
+}
+
+export function getApprovalArtifactPaths(wikiRoot) {
+  const root = path.join(wikiRoot, ".system", "eos", "approval");
+  return Object.freeze({
+    root,
+    requests: path.join(root, "requests"),
+    auditFile: path.join(root, "audit.jsonl"),
+  });
+}
+
+export async function ensureApprovalArtifactStructure(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  await mkdir(paths.requests, { recursive: true });
+  return paths;
+}
+
+export async function prepareApprovalRequestArtifact(wikiRoot, input = {}, options = {}) {
+  if (!wikiRoot || typeof wikiRoot !== "string") {
+    throw new Error("wikiRoot is required for Eos approval artifacts");
+  }
+
+  const now = options.now instanceof Date ? options.now : new Date(options.now || Date.now());
+  const validation = validateApprovalRequest(input);
+  if (!validation.valid) {
+    await appendApprovalAudit(wikiRoot, "reject_approval_request", {
+      source_decision_id: input.source_decision_id || "",
+      requested_action: input.requested_action || "",
+      reason: validation.errors.join("; "),
+    }, { ...options, now });
+    return rejected(validation.errors.join("; "));
+  }
+
+  const prepared = createApprovalRequestArtifact(validation.value, { ...options, now });
+  const resolvedArtifactPath = resolveRequestArtifactPath(wikiRoot, prepared.artifactPath);
+  const existing = await readExistingJson(resolvedArtifactPath);
+  if (existing.exists) {
+    return Object.freeze({
+      success: true,
+      duplicate: true,
+      request: existing.value,
+      artifactPath: prepared.artifactPath,
+      executed: false,
+      sourceEntryMutated: false,
+    });
+  }
+
+  await ensureApprovalArtifactStructure(wikiRoot);
+  await writeFile(resolvedArtifactPath, `${JSON.stringify(prepared.artifact, null, 2)}\n`, {
+    encoding: "utf-8",
+    flag: "wx",
+  });
+  await appendApprovalAuditEntry(wikiRoot, prepared.auditEntry);
+
+  return Object.freeze({
+    success: true,
+    duplicate: false,
+    request: prepared.artifact,
+    artifactPath: prepared.artifactPath,
+    audit: prepared.auditEntry,
+    auditPath: ".system/eos/approval/audit.jsonl",
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}
+
+export async function readApprovalRequestArtifacts(wikiRoot) {
+  const paths = getApprovalArtifactPaths(wikiRoot);
+  const requests = [];
+  const load_errors = [];
+  try {
+    const entries = await readdir(paths.requests, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+      const filePath = path.join(paths.requests, entry.name);
+      try {
+        const artifact = JSON.parse(await readFile(filePath, "utf-8"));
+        if (artifact?.type === "eos_approval_request" && APPROVAL_REQUEST_STATUSES.includes(artifact.status)) {
+          requests.push(artifact);
+        }
+      } catch (error) {
+        load_errors.push({ path: filePath, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+  return Object.freeze({
+    paths,
+    requests: Object.freeze(requests.sort((left, right) => String(left.id).localeCompare(String(right.id)))),
+    load_errors: Object.freeze(load_errors),
+    summary: Object.freeze({ requests: requests.length, load_errors: load_errors.length }),
+  });
+}
+
+async function readExistingJson(filePath) {
+  try {
+    return Object.freeze({ exists: true, value: JSON.parse(await readFile(filePath, "utf-8")) });
+  } catch (error) {
+    if (error?.code === "ENOENT") return Object.freeze({ exists: false, value: null });
+    throw error;
+  }
+}
+
+async function appendApprovalAudit(wikiRoot, action, entry = {}, options = {}) {
+  const payload = {
+    ...createApprovalAuditEntry(action, entry, options),
+    reason: entry.reason || "",
+  };
+  await appendApprovalAuditEntry(wikiRoot, payload);
+  return payload;
+}
+
+async function appendApprovalAuditEntry(wikiRoot, entry) {
+  if (!AUDIT_ACTIONS.includes(entry.action)) {
+    throw new Error(`Unsupported Eos approval audit action: ${entry.action}`);
+  }
+  const paths = await ensureApprovalArtifactStructure(wikiRoot);
+  await appendFile(paths.auditFile, `${JSON.stringify(entry)}\n`, "utf-8");
+}
+
+function rejected(error) {
+  return Object.freeze({
+    success: false,
+    error,
+    executed: false,
+    sourceEntryMutated: false,
+  });
+}

package/src/eos/approval/contract.js

@@ -0,0 +1,165 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export const APPROVAL_REQUEST_STATUSES = Object.freeze([
+  "review_required",
+  "blocked",
+  "approved_not_executed",
+  "handoff_prepared",
+  "rejected",
+]);
+
+export const APPROVAL_ACTION = "prepare_handoff";
+
+const SUPPORTED_SOURCE_ROOTS = Object.freeze([
+  ".system/eos/chat/requests/",
+  ".system/eos/side-review/decisions/",
+  ".system/eos/approval/requests/",
+  ".system/eos/visual-qa/",
+  ".omo/ulw-loop/evidence/",
+]);
+
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function iso(value) {
+  return (value instanceof Date ? value : new Date(value || Date.now())).toISOString();
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (isRecord(value)) {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function shortHash(value) {
+  return createHash("sha256").update(stableJson(value)).digest("hex").slice(0, 12);
+}
+
+function safeId(value, fallback = "approval") {
+  return String(value || fallback)
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 80) || fallback;
+}
+
+export function relativeRequestPath(id) {
+  return path.posix.join(".system", "eos", "approval", "requests", `${id}.json`);
+}
+
+function normalizeRelativePath(value, field, options = {}) {
+  if (typeof value !== "string" || !value.trim()) return { error: `${field} is required` };
+  const normalized = value.trim().replaceAll("\\", "/");
+  if (path.isAbsolute(normalized) || normalized.includes("://")) return { error: `${field} must be a safe relative path` };
+  const collapsed = path.posix.normalize(normalized);
+  if (collapsed.startsWith("../") || collapsed === ".." || collapsed.startsWith("/")) {
+    return { error: `${field} must stay inside the wiki root` };
+  }
+  if (options.supportedRoot && !SUPPORTED_SOURCE_ROOTS.some((root) => collapsed.startsWith(root))) {
+    return { error: `${field} must use a supported approval source root` };
+  }
+  return { value: collapsed };
+}
+
+export function validateApprovalRequest(input = {}) {
+  const errors = [];
+  const sourceDecisionId = typeof input.source_decision_id === "string" ? input.source_decision_id.trim() : "";
+  const requestedAction = typeof input.requested_action === "string" ? input.requested_action.trim() : "";
+  const sourceArtifactPath = normalizeRelativePath(input.source_artifact_path, "source_artifact_path", { supportedRoot: true });
+  const sourcePath = input.source_path ? normalizeRelativePath(input.source_path, "source_path") : { value: null };
+  const evidence = Array.isArray(input.evidence) ? input.evidence : [];
+
+  if (!sourceDecisionId) errors.push("source_decision_id is required");
+  if (requestedAction !== APPROVAL_ACTION) errors.push(`requested_action must be ${APPROVAL_ACTION}`);
+  if (input.status && !APPROVAL_REQUEST_STATUSES.includes(input.status)) errors.push("status is not supported");
+  if (sourceArtifactPath.error) errors.push(sourceArtifactPath.error);
+  if (sourcePath.error) errors.push(sourcePath.error);
+  if (evidence.length === 0) errors.push("evidence is required");
+
+  if (errors.length > 0) return Object.freeze({ valid: false, errors: Object.freeze(errors) });
+
+  return Object.freeze({
+    valid: true,
+    value: Object.freeze({
+      source_decision_id: sourceDecisionId,
+      source_artifact_path: sourceArtifactPath.value,
+      requested_action: requestedAction,
+      reason: typeof input.reason === "string" ? input.reason.trim() : "",
+      source_path: sourcePath.value,
+      evidence: Object.freeze(evidence.map((item) => String(item).trim()).filter(Boolean)),
+      requested_by: typeof input.requested_by === "string" && input.requested_by.trim()
+        ? input.requested_by.trim()
+        : "eos-approval",
+    }),
+  });
+}
+
+export function createApprovalRequestArtifact(request, options = {}) {
+  const seed = {
+    source_decision_id: request.source_decision_id,
+    source_artifact_path: request.source_artifact_path,
+    requested_action: request.requested_action,
+    evidence: request.evidence,
+  };
+  const id = `approval-${safeId(request.source_decision_id)}-${safeId(request.requested_action)}-${shortHash(seed)}`;
+  const artifactPath = relativeRequestPath(id);
+  const auditEntry = createApprovalAuditEntry("approval_requested", request, options, { requestId: id, artifactPath });
+  return Object.freeze({
+    artifactPath,
+    artifact: Object.freeze({
+      schema_version: 1,
+      type: "eos_approval_request",
+      id,
+      source_decision_id: request.source_decision_id,
+      source_artifact_path: request.source_artifact_path,
+      requested_action: request.requested_action,
+      reason: request.reason,
+      source_path: request.source_path,
+      evidence: request.evidence,
+      status: "review_required",
+      requested_by: request.requested_by,
+      safety_flags: Object.freeze({
+        review_required: true,
+        approved_not_executed: false,
+        executed: false,
+        source_entry_mutated: false,
+      }),
+      boundaries: Object.freeze({
+        no_hidden_execution: true,
+        no_source_mutation: true,
+        auto_apply: false,
+        auto_promote: false,
+        auto_merge: false,
+        auto_delete: false,
+        auto_push: false,
+        auto_publish: false,
+        hosted_sync: false,
+      }),
+      audit: Object.freeze([auditEntry]),
+      created_at: iso(options.now),
+      updated_at: iso(options.now),
+      artifact_path: artifactPath,
+    }),
+    auditEntry,
+  });
+}
+
+export function createApprovalAuditEntry(action, request, options = {}, refs = {}) {
+  return Object.freeze({
+    schema_version: 1,
+    action,
+    recorded_at: iso(options.now),
+    actor: options.actor || "eos-approval",
+    request_id: refs.requestId || null,
+    artifact_path: refs.artifactPath || null,
+    source_decision_id: request.source_decision_id || "",
+    requested_action: request.requested_action || "",
+    executed: false,
+    live_execution: false,
+    source_entry_mutated: false,
+  });
+}

package/src/eos/approval/read-model.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import path from "node:path";
+
+import { APPROVAL_REQUEST_STATUSES } from "./contract.js";
+
+function zeroCounts() {
+  return Object.fromEntries(APPROVAL_REQUEST_STATUSES.map((status) => [status, 0]));
+}
+
+function toApprovalSummary(artifact) {
+  return Object.freeze({
+    id: artifact.id,
+    status: artifact.status,
+    requested_action: artifact.requested_action,
+    source_decision_id: artifact.source_decision_id,
+    source_artifact_path: artifact.source_artifact_path,
+    artifact_path: artifact.artifact_path,
+    created_at: artifact.created_at || null,
+    safety_flags: artifact.safety_flags || {},
+    review_required: artifact.status === "review_required",
+  });
+}
+
+export function summarizeApprovalQueue(wikiRoot, options = {}) {
+  const counts = zeroCounts();
+  const recent = [];
+  const loadErrors = [];
+  const requestsDir = path.join(wikiRoot, ".system", "eos", "approval", "requests");
+  let entries;
+
+  try {
+    entries = fs.readdirSync(requestsDir, { withFileTypes: true });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return emptyApprovalQueue(counts);
+    }
+    throw error;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    try {
+      const filePath = path.join(requestsDir, entry.name);
+      const artifact = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+      if (artifact?.type !== "eos_approval_request" || !APPROVAL_REQUEST_STATUSES.includes(artifact.status)) continue;
+      counts[artifact.status] += 1;
+      recent.push(toApprovalSummary(artifact));
+    } catch (error) {
+      loadErrors.push({
+        path: path.posix.join(".system", "eos", "approval", "requests", entry.name),
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  recent.sort((left, right) => {
+    return String(right.created_at || "").localeCompare(String(left.created_at || "")) ||
+      String(left.id).localeCompare(String(right.id));
+  });
+
+  return Object.freeze({
+    counts: Object.freeze(counts),
+    total: recent.length,
+    recent: Object.freeze(recent.slice(0, options.limit || 5)),
+    load_errors: Object.freeze(loadErrors),
+    review_required: counts.review_required,
+    local_only: true,
+    prepare_only: true,
+  });
+}
+
+function emptyApprovalQueue(counts) {
+  return Object.freeze({
+    counts: Object.freeze(counts),
+    total: 0,
+    recent: Object.freeze([]),
+    load_errors: Object.freeze([]),
+    review_required: 0,
+    local_only: true,
+    prepare_only: true,
+  });
+}