@piagent/platform 1.3.0 → 1.4.0

package/packages/piagent-webui/gateway/session-catalog.ts

@@ -0,0 +1,128 @@
+import { createHmac } from "node:crypto";
+import path from "node:path";
+
+import { redactSensitiveText } from "../../piagent-core/security/sensitive-data.js";
+import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
+import type { MetadataSnapshot, SessionMetadata } from "./session-metadata-store.ts";
+import { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
+
+export { projectRefForCwd, sessionRefForPath } from "../ownership/session-refs.ts";
+
+export type PiSessionInfo = {
+  path: string;
+  id: string;
+  cwd: string;
+  name?: string;
+  created: Date;
+  modified: Date;
+  messageCount: number;
+  firstMessage: string;
+  allMessagesText: string;
+};
+
+function catalogRef(key: Buffer, namespace: string, value: string): string {
+  return `${namespace}_${createHmac("sha256", key).update(value).digest("base64url").slice(0, 43)}`;
+}
+
+export type SessionOwnerProjection = Pick<SessionRow, "state" | "liveState" | "composerAvailable" | "needsAttention" | "owner" | "reasonCode">;
+export type SessionOptionProjection = Pick<SessionRow, "modelLabel" | "thinkingLevel">;
+
+function display(value: unknown, maximum: number, fallback: string): string {
+  const clean = redactSensitiveText(String(value ?? "")).text
+    .replace(/[\u0000-\u001f\u007f]+/g, " ").replace(/\s+/g, " ").trim();
+  return (clean || fallback).slice(0, maximum);
+}
+
+function revision(key: Buffer, value: unknown): string {
+  return `rev_${createHmac("sha256", key).update(JSON.stringify(value)).digest("hex")}`;
+}
+
+function row(key: Buffer, info: PiSessionInfo, metadata: SessionMetadata | undefined, metadataReason: string | null,
+  ownership?: SessionOwnerProjection, sessionOptions?: SessionOptionProjection): SessionRow {
+  const projectLabel = display(info.cwd ? path.basename(info.cwd) : "", 120, "Unknown project");
+  const first = info.firstMessage === "(no messages)" ? "" : info.firstMessage;
+  const suppliedName = display(info.name, 500, "").replace(/^pi:\s*/i, "");
+  const normalizedName = suppliedName.toLowerCase();
+  const genericName = !suppliedName || normalizedName === projectLabel.toLowerCase()
+    || ["working", "pi agent platform", "new conversation"].includes(normalizedName);
+  const title = display(genericName && first ? first : suppliedName || first, 500, "New conversation").replace(/^pi:\s*/i, "") || "New conversation";
+  return {
+    sessionRef: sessionRefForPath(key, info.path),
+    projectRef: projectRefForCwd(key, info.cwd),
+    title,
+    projectLabel,
+    preview: display(first, 280, "No messages yet"),
+    createdAt: info.created.toISOString(),
+    updatedAt: info.modified.toISOString(),
+    state: metadata?.archived ? "archived" : ownership?.state ?? "offline",
+    liveState: metadata?.archived ? "offline" : ownership?.liveState ?? "offline",
+    pinned: metadata?.pinned ?? false,
+    archived: metadata?.archived ?? false,
+    unread: metadata?.unread ?? false,
+    composerAvailable: metadata?.archived ? false : ownership?.composerAvailable ?? false,
+    needsAttention: metadata?.archived ? false : ownership?.needsAttention ?? false,
+    modelLabel: sessionOptions?.modelLabel ?? null,
+    thinkingLevel: sessionOptions?.thinkingLevel ?? "unknown",
+    contextUsage: { usedTokens: null, contextWindow: null, ratio: null, state: "unknown" },
+    task: null,
+    owner: metadata?.archived
+      ? { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "released" }
+      : ownership?.owner ?? { kind: "none", ownerEpoch: null, gatewayInstanceRef: null, runtimeInstanceRef: null, continuity: "unknown" },
+    sessionRevision: revision(key, [info.path, info.modified.toISOString(), info.messageCount, info.name ?? null, metadata?.revision ?? null,
+      sessionOptions?.modelLabel ?? null, sessionOptions?.thinkingLevel ?? "unknown",
+      metadata?.archived ? "archived" : ownership ? [ownership.state, ownership.liveState, ownership.owner.kind,
+        ownership.owner.ownerEpoch, ownership.owner.runtimeInstanceRef, ownership.reasonCode] : "offline"]),
+    reasonCode: metadata?.archived ? metadataReason : ownership?.reasonCode ?? metadataReason
+  };
+}
+
+export async function buildSessionCatalog(options: {
+  gatewayInstanceRef: string;
+  key: Buffer;
+  listSessions(): Promise<PiSessionInfo[]>;
+  readMetadata?(): MetadataSnapshot;
+  readOwnership?(sessionRef: string): SessionOwnerProjection;
+  readSessionOptions?(info: PiSessionInfo): SessionOptionProjection;
+  limit?: number;
+}): Promise<Catalog> {
+  const limit = Math.max(1, Math.min(200, options.limit ?? 200));
+  try {
+    const found = await options.listSessions();
+    const metadata = options.readMetadata?.() ?? { state: "ready", revision: null, sessions: new Map(), reasonCode: null };
+    const sessions = found.map((info) => {
+      const sessionRef = sessionRefForPath(options.key, info.path);
+      return row(options.key, info, metadata.sessions.get(sessionRef), metadata.reasonCode, options.readOwnership?.(sessionRef),
+        options.readSessionOptions?.(info));
+    }).sort((left, right) => Number(right.pinned) - Number(left.pinned)
+      || Date.parse(right.updatedAt) - Date.parse(left.updatedAt)).slice(0, limit);
+    return {
+      schemaVersion: 1,
+      version: "piagent-session-catalog-v1",
+      generatedAt: new Date().toISOString(),
+      gatewayInstanceRef: options.gatewayInstanceRef,
+      state: "ready",
+      catalogRevision: revision(options.key, [metadata.revision, sessions.map((item) => [item.sessionRef, item.sessionRevision])]),
+      sessions,
+      page: {
+        limit,
+        returned: sessions.length,
+        total: Math.min(1_000_000, found.length),
+        nextCursor: found.length > sessions.length ? catalogRef(options.key, "cursor", sessions.at(-1)?.sessionRef ?? "empty") : null,
+        truncated: found.length > sessions.length
+      },
+      reasonCode: null
+    };
+  } catch {
+    return {
+      schemaVersion: 1,
+      version: "piagent-session-catalog-v1",
+      generatedAt: new Date().toISOString(),
+      gatewayInstanceRef: options.gatewayInstanceRef,
+      state: "unavailable",
+      catalogRevision: null,
+      sessions: [],
+      page: { limit, returned: 0, total: 0, nextCursor: null, truncated: false },
+      reasonCode: "catalog-read-failed"
+    };
+  }
+}

package/packages/piagent-webui/gateway/session-command-controller.ts

@@ -0,0 +1,237 @@
+import { randomBytes } from "node:crypto";
+
+import type { Catalog, SessionRow } from "../contracts/generated/session-catalog-v1.ts";
+import type { Receipt } from "../contracts/generated/session-command-v1.ts";
+import { GatewayEventStore } from "./gateway-events.ts";
+import { SessionCommandStore, type SessionAction, type SessionCommandIdentity } from "./session-command-store.ts";
+import { SessionRuntimeSupervisor } from "./session-runtime-supervisor.ts";
+import { SessionMetadataStore } from "./session-metadata-store.ts";
+
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const IDEMPOTENCY = /^[A-Za-z0-9_-]{22,96}$/;
+const ACTIONS: SessionAction[] = ["session.create", "session.send", "session.abort", "session.set-model", "session.set-thinking", "session.set-permission", "session.rename", "session.pin", "session.archive",
+  "session.unarchive", "session.fork", "session.acquire", "session.release"];
+
+type SessionCommand = SessionCommandIdentity & {
+  schemaVersion: 1;
+  version: "piagent-session-command-v1";
+  messageType: "command";
+  expiresAt: string;
+  expectedCatalogRevision: string;
+  expectedSessionRevision: string | null;
+  payload: Record<string, unknown>;
+};
+
+function record(value: unknown): value is Record<string, unknown> { return Boolean(value) && typeof value === "object" && !Array.isArray(value); }
+function exactKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  const found = Object.keys(value); return found.length === keys.length && found.every((key) => keys.includes(key));
+}
+function exactTimestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function nullableRef(value: unknown): value is string | null { return value === null || typeof value === "string" && REF.test(value); }
+
+function validPayload(action: SessionAction, payload: Record<string, unknown>): boolean {
+  if (["session.archive", "session.unarchive", "session.acquire", "session.release"].includes(action)) return exactKeys(payload, []);
+  if (action === "session.send") return exactKeys(payload, ["delivery", "message", "messageRequestId", "expectedOperationRef"])
+    && ["new-operation", "follow-up", "steer"].includes(String(payload.delivery)) && typeof payload.message === "string"
+    && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0") && REF.test(String(payload.messageRequestId))
+    && nullableRef(payload.expectedOperationRef) && (payload.delivery === "new-operation" ? payload.expectedOperationRef === null : payload.expectedOperationRef !== null);
+  if (action === "session.abort") return exactKeys(payload, ["operationRef", "clearQueued"])
+    && REF.test(String(payload.operationRef)) && typeof payload.clearQueued === "boolean";
+  if (action === "session.set-model") return exactKeys(payload, ["modelRef"]) && REF.test(String(payload.modelRef));
+  if (action === "session.set-thinking") return exactKeys(payload, ["thinkingLevel"])
+    && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel));
+  if (action === "session.set-permission") return exactKeys(payload, ["permissionMode"])
+    && ["read-only", "workspace-write", "trusted-full-access"].includes(String(payload.permissionMode));
+  if (action === "session.rename") return exactKeys(payload, ["title"]) && typeof payload.title === "string"
+    && payload.title.length >= 1 && payload.title.length <= 500 && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(payload.title);
+  if (action === "session.pin") return exactKeys(payload, ["pinned"]) && typeof payload.pinned === "boolean";
+  if (action === "session.fork") return exactKeys(payload, ["entryRef", "title"]) && nullableRef(payload.entryRef)
+    && (payload.title === null || typeof payload.title === "string" && payload.title.length >= 1 && payload.title.length <= 500
+      && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test(payload.title));
+  return exactKeys(payload, ["projectRef", "placeRef", "modelRef", "thinkingLevel", "message", "messageRequestId"])
+    && REF.test(String(payload.projectRef)) && REF.test(String(payload.placeRef)) && nullableRef(payload.modelRef)
+    && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(String(payload.thinkingLevel))
+    && typeof payload.message === "string" && payload.message.length >= 1 && payload.message.length <= 32_768 && !payload.message.includes("\0")
+    && REF.test(String(payload.messageRequestId));
+}
+
+function parseCommand(value: unknown): SessionCommand | null {
+  if (!record(value) || !exactKeys(value, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKey", "action",
+    "requestedAt", "expiresAt", "sessionRef", "expectedCatalogRevision", "expectedSessionRevision", "payload"])) return null;
+  const action = value.action as SessionAction;
+  if (value.schemaVersion !== 1 || value.version !== "piagent-session-command-v1" || value.messageType !== "command"
+    || typeof value.commandId !== "string" || !REF.test(value.commandId) || typeof value.idempotencyKey !== "string" || !IDEMPOTENCY.test(value.idempotencyKey)
+    || !ACTIONS.includes(action) || !exactTimestamp(value.requestedAt) || !exactTimestamp(value.expiresAt)
+    || Date.parse(value.requestedAt) > Date.parse(value.expiresAt) || Date.parse(value.expiresAt) - Date.parse(value.requestedAt) > 300_000
+    || !nullableRef(value.sessionRef) || typeof value.expectedCatalogRevision !== "string" || !REVISION.test(value.expectedCatalogRevision)
+    || !(value.expectedSessionRevision === null || typeof value.expectedSessionRevision === "string" && REVISION.test(value.expectedSessionRevision))
+    || !record(value.payload) || !validPayload(action, value.payload)) return null;
+  if (action === "session.create") {
+    if (value.sessionRef !== null || value.expectedSessionRevision !== null) return null;
+  } else if (value.sessionRef === null || value.expectedSessionRevision === null) return null;
+  return value as SessionCommand;
+}
+
+function error(code: string, message: string) { return { code, message }; }
+
+export class SessionCommandController {
+  readonly #catalog: () => Promise<Catalog>;
+  readonly #runtimes: SessionRuntimeSupervisor;
+  readonly #store: SessionCommandStore;
+  readonly #events: GatewayEventStore;
+  readonly #metadata: SessionMetadataStore | null;
+  readonly #now: () => Date;
+  readonly #chains = new Map<string, Promise<unknown>>();
+
+  constructor(options: { catalog(): Promise<Catalog>; runtimes: SessionRuntimeSupervisor; store: SessionCommandStore; events: GatewayEventStore;
+    metadata?: SessionMetadataStore;
+    now?: () => Date }) {
+    this.#catalog = options.catalog; this.#runtimes = options.runtimes; this.#store = options.store; this.#events = options.events;
+    this.#metadata = options.metadata ?? null;
+    this.#now = options.now ?? (() => new Date());
+  }
+
+  execute(input: unknown): Promise<Receipt> {
+    const command = parseCommand(input);
+    if (!command) return Promise.reject(new Error("invalid-session-command"));
+    const key = command.sessionRef ?? "session-create";
+    const prior = this.#chains.get(key) ?? Promise.resolve();
+    const run = prior.then(() => this.#execute(command), () => this.#execute(command));
+    const tail = run.catch(() => undefined);
+    this.#chains.set(key, tail);
+    return run.finally(() => { if (this.#chains.get(key) === tail) this.#chains.delete(key); });
+  }
+
+  async #execute(command: SessionCommand): Promise<Receipt> {
+    const current = await this.#readyCatalog(), row = command.sessionRef ? current.sessions.find((item) => item.sessionRef === command.sessionRef) : null;
+    const replay = this.#store.lookup(command);
+    if (replay.state === "settled") return { ...replay.receipt!, deduplicated: true };
+    if (replay.state === "conflict") return this.#rejected(command, current, row, "invalid-command", "idempotency-payload-mismatch");
+    if (replay.state === "unavailable") return this.#rejected(command, current, row, "unavailable", "session-command-journal-unavailable");
+    if (replay.state === "pending") {
+      const uncertain = this.#uncertain(command, current, row, "session-command-effect-unknown");
+      try { this.#store.settle(command, uncertain, this.#now()); } catch { /* returning uncertainty is still safer than replay */ }
+      return uncertain;
+    }
+    const now = this.#now().getTime();
+    if (Date.parse(command.requestedAt) > now + 30_000) return this.#rejected(command, current, row, "invalid-command", "requested-at-in-future");
+    if (now > Date.parse(command.expiresAt)) return this.#rejected(command, current, row, "expired", "session-command-expired");
+    const stale = command.expectedCatalogRevision !== current.catalogRevision || (command.action === "session.create"
+      ? command.expectedSessionRevision !== null : !row || command.expectedSessionRevision !== row.sessionRevision);
+    if (stale) {
+      return this.#rejected(command, current, row, "stale-revision", "session-revision-stale");
+    }
+    if (row?.archived && command.action !== "session.unarchive") return this.#rejected(command, current, row, "unavailable", "session-archived");
+    try { this.#store.admit(command, this.#now()); }
+    catch { return this.#rejected(command, current, row, "unavailable", "session-command-admission-failed"); }
+    let targetSessionRef = command.sessionRef;
+    try {
+      let resultCode: "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
+        | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
+        operationRef: string | null = null;
+      if (command.action === "session.create") {
+        targetSessionRef = await this.#runtimes.create(String(command.payload.projectRef), String(command.payload.placeRef),
+          command.payload.modelRef === null ? null : String(command.payload.modelRef), String(command.payload.thinkingLevel));
+        const created = await this.#readyCatalog(), createdRow = created.sessions.find((item) => item.sessionRef === targetSessionRef);
+        if (!createdRow) throw new Error("session-catalog-refresh-failed");
+        const sent = await this.#runtimes.send(targetSessionRef, { delivery: "new-operation", message: String(command.payload.message),
+          expectedOperationRef: null }, createdRow.sessionRevision);
+        resultCode = sent.resultCode === "started" ? "started" : sent.resultCode; operationRef = sent.operationRef;
+      } else if (command.action === "session.acquire") { await this.#runtimes.acquire(command.sessionRef!); resultCode = "acquired"; }
+      else if (command.action === "session.release") { await this.#runtimes.release(command.sessionRef!); resultCode = "released"; }
+      else if (command.action === "session.send") {
+        await this.#runtimes.acquire(command.sessionRef!);
+        const acquired = await this.#readyCatalog(), acquiredRow = acquired.sessions.find((item) => item.sessionRef === command.sessionRef);
+        if (!acquiredRow) throw new Error("session-catalog-refresh-failed");
+        const sent = await this.#runtimes.send(command.sessionRef!, command.payload as {
+          delivery: "new-operation" | "follow-up" | "steer"; message: string; expectedOperationRef: string | null
+        }, acquiredRow.sessionRevision);
+        resultCode = sent.resultCode; operationRef = sent.operationRef;
+      } else if (command.action === "session.abort") {
+        operationRef = String(command.payload.operationRef);
+        await this.#runtimes.abort(command.sessionRef!, operationRef, command.payload.clearQueued === true);
+        resultCode = "aborted";
+      } else if (command.action === "session.set-model") {
+        resultCode = await this.#runtimes.setModel(command.sessionRef!, String(command.payload.modelRef));
+      } else if (command.action === "session.set-thinking") {
+        resultCode = await this.#runtimes.setThinking(command.sessionRef!, String(command.payload.thinkingLevel));
+      } else if (command.action === "session.set-permission") {
+        resultCode = await this.#runtimes.setPermission(command.sessionRef!, String(command.payload.permissionMode) as
+          "read-only" | "workspace-write" | "trusted-full-access");
+      } else if (command.action === "session.rename") {
+        resultCode = await this.#runtimes.rename(command.sessionRef!, String(command.payload.title).trim());
+      } else if (command.action === "session.fork") {
+        targetSessionRef = await this.#runtimes.fork(command.sessionRef!, command.payload.entryRef === null ? null : String(command.payload.entryRef),
+          command.payload.title === null ? null : String(command.payload.title).trim());
+        resultCode = "forked";
+      } else {
+        if (!this.#metadata) throw new Error("session-metadata-unavailable");
+        if (command.action === "session.archive") await this.#runtimes.release(command.sessionRef!);
+        const snapshot = this.#metadata.read();
+        if (snapshot.state !== "ready") throw new Error(snapshot.reasonCode ?? "session-metadata-unavailable");
+        const prior = snapshot.sessions.get(command.sessionRef!), expected = prior?.revision ?? null;
+        if (command.action === "session.pin") {
+          const pinned = command.payload.pinned === true;
+          if ((prior?.pinned ?? false) === pinned) resultCode = "no-change";
+          else { this.#metadata.update(command.sessionRef!, expected, { pinned }, this.#now()); resultCode = pinned ? "pinned" : "unpinned"; }
+        } else if (command.action === "session.archive") {
+          if (prior?.archived) resultCode = "no-change";
+          else { this.#metadata.update(command.sessionRef!, expected, { archived: true }, this.#now()); resultCode = "archived"; }
+        } else {
+          if (!prior?.archived) resultCode = "no-change";
+          else { this.#metadata.update(command.sessionRef!, expected, { archived: false }, this.#now()); resultCode = "unarchived"; }
+        }
+      }
+      const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef);
+      if (!afterRow) throw new Error("session-catalog-refresh-failed");
+      const receipt = this.#settled(command, after, afterRow, resultCode, operationRef);
+      try { this.#store.settle(command, receipt, this.#now()); }
+      catch { return this.#uncertain(command, after, afterRow, "session-command-settlement-not-durable"); }
+      this.#events.publish("session.changed", { catalogRevision: after.catalogRevision, session: afterRow });
+      return receipt;
+    } catch (cause) {
+      const after = await this.#readyCatalog(), afterRow = after.sessions.find((item) => item.sessionRef === targetSessionRef) ?? row;
+      const code = cause instanceof Error && /recovery/.test(cause.message) ? "recovery-required"
+        : cause instanceof Error && /(owner-conflict|operation-conflict|runtime-busy)/.test(cause.message) ? "owner-conflict" : "effect-unknown";
+      const receipt = code === "effect-unknown" ? this.#uncertain(command, after, afterRow, "session-command-effect-unknown")
+        : this.#rejected(command, after, afterRow, code, cause instanceof Error ? cause.message : "session-command-failed");
+      try { this.#store.settle(command, receipt, this.#now()); } catch { /* intent remains uncertain */ }
+      return receipt;
+    }
+  }
+
+  async #readyCatalog(): Promise<Catalog> {
+    const catalog = await this.#catalog();
+    if (catalog.state !== "ready" || !catalog.catalogRevision) throw new Error(catalog.reasonCode ?? "catalog-unavailable");
+    return catalog;
+  }
+
+  #base(command: SessionCommand, catalog: Catalog, row: SessionRow | null) {
+    return { schemaVersion: 1 as const, version: "piagent-session-receipt-v1" as const, messageType: "receipt" as const,
+      commandId: command.commandId, idempotencyKeyDigest: this.#store.idempotencyDigest(command.idempotencyKey), action: command.action,
+      requestedAt: command.requestedAt, sessionRef: command.action === "session.create" || command.action === "session.fork"
+        ? row?.sessionRef ?? null : command.sessionRef,
+      operationRef: null, catalogRevisionAfter: catalog.catalogRevision!,
+      sessionRevisionAfter: row?.sessionRevision ?? null, deduplicated: false };
+  }
+  #settled(command: SessionCommand, catalog: Catalog, row: SessionRow,
+    resultCode: "acquired" | "released" | "started" | "queued" | "steered" | "aborted" | "model-changed" | "thinking-changed" | "permission-changed"
+      | "renamed" | "pinned" | "unpinned" | "archived" | "unarchived" | "forked" | "no-change",
+    operationRef: string | null): Receipt {
+    return { ...this.#base(command, catalog, row), operationRef, phase: "settled", resultCode, settledAt: this.#now().toISOString(),
+      evidenceRef: `evidence_${randomBytes(24).toString("base64url")}`, error: null };
+  }
+  #uncertain(command: SessionCommand, catalog: Catalog, row: SessionRow | null, code: string): Receipt {
+    return { ...this.#base(command, catalog, row), phase: "uncertain", resultCode: "effect-unknown", settledAt: this.#now().toISOString(),
+      evidenceRef: null, error: error(code, "The command effect cannot be proven. It will not be replayed automatically.") };
+  }
+  #rejected(command: SessionCommand, catalog: Catalog, row: SessionRow | null,
+    resultCode: "stale-revision" | "owner-conflict" | "recovery-required" | "invalid-command" | "expired" | "unavailable", code: string): Receipt {
+    return { ...this.#base(command, catalog, row), phase: "rejected", resultCode, settledAt: this.#now().toISOString(), evidenceRef: null,
+      error: error(code.replace(/[^a-z0-9.-]/g, "-").slice(0, 96) || "session-command-rejected", "The session command was rejected.") };
+  }
+}

package/packages/piagent-webui/gateway/session-command-store.ts

@@ -0,0 +1,224 @@
+import { createHmac } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+import type { Receipt } from "../contracts/generated/session-command-v1.ts";
+
+const FILE_LIMIT = 8 * 1024 * 1024;
+const RECORD_LIMIT = 16 * 1024;
+const ENTRY_LIMIT = 20_000;
+const REF = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,159}$/;
+const REVISION = /^[A-Za-z0-9][A-Za-z0-9._:~-]{0,159}$/;
+const REASON = /^[a-z0-9][a-z0-9.-]{0,95}$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const ACTIONS = ["session.create", "session.send", "session.abort", "session.set-model", "session.set-thinking", "session.set-permission", "session.rename", "session.pin", "session.archive",
+  "session.unarchive", "session.fork", "session.acquire", "session.release"] as const;
+
+export type SessionAction = typeof ACTIONS[number];
+export type SessionCommandIdentity = { commandId: string; idempotencyKey: string; action: SessionAction; sessionRef: string | null; requestedAt: string };
+type JournalRecord = {
+  version: "piagent-session-command-journal-v1";
+  sequence: number;
+  recordedAt: string;
+  recordType: "intent" | "receipt";
+  commandId: string;
+  idempotencyKeyDigest: string;
+  actionDigest: string;
+  action: SessionAction;
+  sessionRef: string | null;
+  requestedAt: string;
+  receipt: Receipt | null;
+  previousDigest: string | null;
+  recordDigest: string;
+};
+
+type CommandBinding = { intent: JournalRecord; receipt: Receipt | null };
+
+function exactTimestamp(value: unknown): value is string {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value)
+    && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value;
+}
+function exactKeys(value: object, keys: string[]): boolean {
+  const found = Object.keys(value);
+  return found.length === keys.length && found.every((key) => keys.includes(key));
+}
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") return `{${Object.entries(value as Record<string, unknown>).sort(([left], [right]) => left.localeCompare(right))
+    .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(",")}}`;
+  return JSON.stringify(value);
+}
+function unsigned(record: JournalRecord): Omit<JournalRecord, "recordDigest"> {
+  const { recordDigest: _ignored, ...value } = record;
+  return value;
+}
+function validError(value: unknown): boolean {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value)
+    && exactKeys(value as object, ["code", "message"]) && REASON.test(String((value as any).code))
+    && typeof (value as any).message === "string" && (value as any).message.length >= 1 && (value as any).message.length <= 500
+    && !/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/.test((value as any).message));
+}
+
+export function validSessionReceipt(value: unknown): value is Receipt {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const receipt = value as Receipt;
+  if (!exactKeys(receipt, ["schemaVersion", "version", "messageType", "commandId", "idempotencyKeyDigest", "action", "phase",
+    "resultCode", "requestedAt", "settledAt", "sessionRef", "operationRef", "catalogRevisionAfter", "sessionRevisionAfter",
+    "deduplicated", "evidenceRef", "error"]) || receipt.schemaVersion !== 1 || receipt.version !== "piagent-session-receipt-v1"
+    || receipt.messageType !== "receipt" || !REF.test(receipt.commandId) || !DIGEST.test(receipt.idempotencyKeyDigest)
+    || !ACTIONS.includes(receipt.action) || !exactTimestamp(receipt.requestedAt) || !REVISION.test(receipt.catalogRevisionAfter)
+    || !(receipt.sessionRef === null || REF.test(receipt.sessionRef)) || !(receipt.operationRef === null || REF.test(receipt.operationRef))
+    || !(receipt.sessionRevisionAfter === null || REVISION.test(receipt.sessionRevisionAfter)) || typeof receipt.deduplicated !== "boolean") return false;
+  const settled = exactTimestamp(receipt.settledAt), evidence = typeof receipt.evidenceRef === "string" && REF.test(receipt.evidenceRef);
+  if (receipt.phase === "accepted") return receipt.resultCode === "accepted" && receipt.settledAt === null && receipt.evidenceRef === null && receipt.error === null;
+  if (receipt.phase === "settled") {
+    const results = ["created", "started", "queued", "steered", "aborted", "model-changed", "thinking-changed", "permission-changed", "renamed", "pinned", "unpinned", "archived", "unarchived",
+      "forked", "acquired", "released", "no-change"];
+    const actionResults: Partial<Record<SessionAction, string[]>> = {
+      "session.create": ["created", "started"],
+      "session.acquire": ["acquired", "no-change"], "session.release": ["released", "no-change"],
+      "session.send": ["started", "queued", "steered"], "session.abort": ["aborted", "no-change"],
+      "session.set-model": ["model-changed", "no-change"], "session.set-thinking": ["thinking-changed", "no-change"],
+      "session.set-permission": ["permission-changed", "no-change"], "session.rename": ["renamed", "no-change"],
+      "session.pin": ["pinned", "unpinned", "no-change"], "session.archive": ["archived", "no-change"],
+      "session.unarchive": ["unarchived", "no-change"], "session.fork": ["forked"]
+    };
+    return settled && evidence && receipt.error === null && results.includes(receipt.resultCode)
+      && (!actionResults[receipt.action] || actionResults[receipt.action]!.includes(receipt.resultCode))
+      && (receipt.action === "session.create" ? (receipt.resultCode === "started" ? receipt.operationRef !== null : receipt.operationRef === null)
+        : ["session.send", "session.abort"].includes(receipt.action) ? receipt.operationRef !== null : receipt.operationRef === null)
+      && (receipt.action !== "session.create" || ["created", "started"].includes(receipt.resultCode) && receipt.sessionRef !== null
+        && receipt.sessionRevisionAfter !== null)
+      && (receipt.action !== "session.fork" || receipt.resultCode === "forked" && receipt.sessionRef !== null
+        && receipt.sessionRevisionAfter !== null);
+  }
+  if (receipt.phase === "uncertain") return settled && receipt.resultCode === "effect-unknown" && validError(receipt.error)
+    && (receipt.evidenceRef === null || evidence);
+  return receipt.phase === "rejected" && settled && ["stale-revision", "owner-conflict", "recovery-required", "invalid-command", "expired", "unavailable"]
+    .includes(receipt.resultCode) && receipt.evidenceRef === null && validError(receipt.error);
+}
+
+export class SessionCommandStore {
+  readonly directory: string;
+  readonly file: string;
+  readonly #key: Buffer;
+
+  constructor(root: string, key: Buffer) {
+    this.directory = path.join(root, "commands");
+    this.file = path.join(this.directory, "admission.jsonl");
+    this.#key = key;
+    fs.mkdirSync(this.directory, { recursive: true, mode: 0o700 });
+    const stat = fs.lstatSync(this.directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()
+      || (typeof process.getuid === "function" && stat.uid !== process.getuid())) throw new Error("session-command-root-invalid");
+    fs.chmodSync(this.directory, 0o700);
+  }
+
+  #digest(namespace: string, value: unknown): string {
+    return `sha256:${createHmac("sha256", this.#key).update(namespace).update("\0").update(canonical(value)).digest("hex")}`;
+  }
+  idempotencyDigest(key: string): string { return this.#digest("idempotency", key); }
+  actionDigest(command: unknown): string { return this.#digest("action", command); }
+
+  #valid(record: unknown, index: number, previousDigest: string | null): record is JournalRecord {
+    if (!record || typeof record !== "object" || Array.isArray(record)) return false;
+    const value = record as JournalRecord;
+    if (!exactKeys(value, ["version", "sequence", "recordedAt", "recordType", "commandId", "idempotencyKeyDigest", "actionDigest",
+      "action", "sessionRef", "requestedAt", "receipt", "previousDigest", "recordDigest"]) || value.version !== "piagent-session-command-journal-v1"
+      || value.sequence !== index + 1 || !exactTimestamp(value.recordedAt) || !["intent", "receipt"].includes(value.recordType)
+      || !REF.test(value.commandId) || !DIGEST.test(value.idempotencyKeyDigest) || !DIGEST.test(value.actionDigest)
+      || !ACTIONS.includes(value.action) || !(value.sessionRef === null || REF.test(value.sessionRef)) || !exactTimestamp(value.requestedAt)
+      || value.previousDigest !== previousDigest || !DIGEST.test(value.recordDigest)) return false;
+    if (value.recordType === "intent" ? value.receipt !== null : !validSessionReceipt(value.receipt)) return false;
+    const createsSession = value.action === "session.create" || value.action === "session.fork";
+    const receiptSessionBound = !value.receipt ? true : !createsSession ? value.receipt.sessionRef === value.sessionRef
+      : value.receipt.phase === "settled" ? value.receipt.sessionRef !== null
+        : value.receipt.phase === "rejected" ? value.receipt.sessionRef === value.sessionRef : true;
+    if (value.receipt && (value.receipt.commandId !== value.commandId || value.receipt.idempotencyKeyDigest !== value.idempotencyKeyDigest
+      || value.receipt.action !== value.action || value.receipt.requestedAt !== value.requestedAt || !receiptSessionBound)) return false;
+    return value.recordDigest === this.#digest("record", unsigned(value));
+  }
+
+  #read(): JournalRecord[] {
+    let stat: fs.Stats;
+    try { stat = fs.lstatSync(this.file); } catch (error) {
+      if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
+      throw error;
+    }
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.size > FILE_LIMIT) throw new Error("session-command-file-invalid");
+    const descriptor = fs.openSync(this.file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+    try {
+      const opened = fs.fstatSync(descriptor);
+      if (opened.dev !== stat.dev || opened.ino !== stat.ino || opened.size !== stat.size) throw new Error("session-command-file-race");
+      const lines = fs.readFileSync(descriptor, "utf8").split("\n"); if (lines.at(-1) === "") lines.pop();
+      if (lines.length > ENTRY_LIMIT) throw new Error("session-command-entry-limit");
+      const records: JournalRecord[] = [];
+      for (const [index, line] of lines.entries()) {
+        if (!line || Buffer.byteLength(line) > RECORD_LIMIT) throw new Error("session-command-record-limit");
+        let value: unknown; try { value = JSON.parse(line); } catch { throw new Error("session-command-record-invalid"); }
+        if (!this.#valid(value, index, records.at(-1)?.recordDigest ?? null)) throw new Error("session-command-record-invalid");
+        records.push(value);
+      }
+      const byCommand = new Map<string, JournalRecord>(), byKey = new Map<string, JournalRecord>(), settled = new Set<string>();
+      for (const record of records) {
+        if (record.recordType === "intent") {
+          if (byCommand.has(record.commandId) || byKey.has(record.idempotencyKeyDigest)) throw new Error("session-command-binding-duplicate");
+          byCommand.set(record.commandId, record); byKey.set(record.idempotencyKeyDigest, record);
+        } else {
+          const intent = byCommand.get(record.commandId);
+          if (!intent || intent.idempotencyKeyDigest !== record.idempotencyKeyDigest || intent.actionDigest !== record.actionDigest
+            || settled.has(record.commandId)) {
+            throw new Error("session-command-chain-invalid");
+          }
+          settled.add(record.commandId);
+        }
+      }
+      return records;
+    } finally { fs.closeSync(descriptor); }
+  }
+
+  #append(value: Omit<JournalRecord, "version" | "sequence" | "recordedAt" | "previousDigest" | "recordDigest">, now = new Date()): JournalRecord {
+    if (!Number.isFinite(now.getTime())) throw new Error("session-command-time-invalid");
+    const records = this.#read(); if (records.length >= ENTRY_LIMIT) throw new Error("session-command-entry-limit");
+    const partial = { version: "piagent-session-command-journal-v1" as const, sequence: records.length + 1, recordedAt: now.toISOString(),
+      previousDigest: records.at(-1)?.recordDigest ?? null, ...value };
+    const record: JournalRecord = { ...partial, recordDigest: this.#digest("record", partial) };
+    const body = Buffer.from(`${JSON.stringify(record)}\n`); if (body.length > RECORD_LIMIT) throw new Error("session-command-record-limit");
+    let stat: fs.Stats | null = null; try { stat = fs.lstatSync(this.file); } catch { /* first record */ }
+    if (stat && (!stat.isFile() || stat.isSymbolicLink() || stat.size + body.length > FILE_LIMIT)) throw new Error("session-command-file-invalid");
+    const descriptor = fs.openSync(this.file, fs.constants.O_WRONLY | fs.constants.O_APPEND | fs.constants.O_CREAT
+      | (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+    try { fs.writeFileSync(descriptor, body); fs.fsyncSync(descriptor); } finally { fs.closeSync(descriptor); }
+    fs.chmodSync(this.file, 0o600); return record;
+  }
+
+  lookup(command: SessionCommandIdentity): { state: "none" | "pending" | "settled" | "conflict" | "unavailable"; receipt?: Receipt } {
+    try {
+      const records = this.#read(), keyDigest = this.idempotencyDigest(command.idempotencyKey), actionDigest = this.actionDigest(command);
+      const intent = records.find((record) => record.recordType === "intent"
+        && (record.commandId === command.commandId || record.idempotencyKeyDigest === keyDigest));
+      if (!intent) return { state: "none" };
+      if (intent.commandId !== command.commandId || intent.idempotencyKeyDigest !== keyDigest || intent.actionDigest !== actionDigest) return { state: "conflict" };
+      const receipt = records.find((record) => record.recordType === "receipt" && record.commandId === command.commandId)?.receipt ?? null;
+      return receipt ? { state: "settled", receipt: structuredClone(receipt) } : { state: "pending" };
+    } catch { return { state: "unavailable" }; }
+  }
+
+  admit(command: SessionCommandIdentity, now = new Date()): { idempotencyKeyDigest: string; actionDigest: string } {
+    const existing = this.lookup(command);
+    if (existing.state !== "none") throw new Error(`session-command-${existing.state}`);
+    const idempotencyKeyDigest = this.idempotencyDigest(command.idempotencyKey), actionDigest = this.actionDigest(command);
+    this.#append({ recordType: "intent", commandId: command.commandId, idempotencyKeyDigest, actionDigest, action: command.action,
+      sessionRef: command.sessionRef, requestedAt: command.requestedAt, receipt: null }, now);
+    return { idempotencyKeyDigest, actionDigest };
+  }
+
+  settle(command: SessionCommandIdentity, receipt: Receipt, now = new Date()): void {
+    if (!validSessionReceipt(receipt)) throw new Error("session-command-receipt-invalid");
+    const existing = this.lookup(command);
+    if (existing.state !== "pending") throw new Error(`session-command-${existing.state}`);
+    this.#append({ recordType: "receipt", commandId: command.commandId, idempotencyKeyDigest: this.idempotencyDigest(command.idempotencyKey),
+      actionDigest: this.actionDigest(command), action: command.action, sessionRef: command.sessionRef, requestedAt: command.requestedAt,
+      receipt: structuredClone(receipt) }, now);
+  }
+}