work-ally 0.2.0-alpha.1

package/bridge/src/session-store-delivery.ts

@@ -0,0 +1,220 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendNdjson, nowIso, readJsonFile, writeJsonFile } from './utils.ts';
+import type { ConversationRef, InboundAcceptanceRecord, InboundReceipt, OutboundDeliveryRecord, SessionMeta } from './types.ts';
+
+export interface ReceiptClaimResult {
+  status: 'claimed' | 'duplicate_processing' | 'duplicate_completed' | 'duplicate_superseded';
+  receipt: InboundReceipt;
+}
+
+interface SeenInboundRecord {
+  messageId: string;
+  firstSeenAt: string;
+  lastSeenAt: string;
+}
+
+export interface DeliveryStoreDeps {
+  ensureSessionDirs(ref: ConversationRef): string;
+  resolveSessionDir(ref: ConversationRef): string;
+  eventsFile(ref: ConversationRef): string;
+  receiptFile(ref: ConversationRef, messageId: string): string;
+  seenInboundFile(ref: ConversationRef, messageId: string): string;
+  outboundDeliveryFile(ref: ConversationRef, sourceKey: string): string;
+  getSession(ref: ConversationRef): SessionMeta | null;
+  getInboundAcceptance(ref: ConversationRef, messageId: string): InboundAcceptanceRecord | null;
+  noteInboundObserved(ref: ConversationRef, messageId: string): void;
+}
+
+function terminalReceiptOutcomeFor(
+  inboundAcceptance: InboundAcceptanceRecord | null,
+): InboundReceipt['outcome'] | null {
+  if (!inboundAcceptance?.acceptedAt) {
+    return null;
+  }
+  if (inboundAcceptance.executionStatus === 'completed') {
+    return 'success';
+  }
+  if (
+    inboundAcceptance.executionStatus === 'failed'
+    || inboundAcceptance.executionStatus === 'interrupted'
+  ) {
+    return 'failed';
+  }
+  return null;
+}
+
+export function noteInboundReceipt(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+): ReceiptClaimResult {
+  deps.ensureSessionDirs(ref);
+  const file = deps.receiptFile(ref, messageId);
+  const seenFile = deps.seenInboundFile(ref, messageId);
+  const now = nowIso();
+  const existing = readJsonFile(file) as InboundReceipt | null;
+  if (existing) {
+    const receipt: InboundReceipt = {
+      ...existing,
+      updatedAt: existing.updatedAt || existing.createdAt || now,
+    };
+    return {
+      status: receipt.status === 'completed' ? 'duplicate_completed' : 'duplicate_processing',
+      receipt,
+    };
+  }
+
+  const seen = readJsonFile(seenFile) as SeenInboundRecord | null;
+  if (seen) {
+    writeJsonFile(seenFile, {
+      ...seen,
+      lastSeenAt: now,
+    });
+    const meta = deps.getSession(ref);
+    if (meta?.lastMessageId && meta.lastMessageId !== messageId) {
+      const latestAccepted = deps.getInboundAcceptance(ref, meta.lastMessageId);
+      const latestAcceptedAt = String(latestAccepted?.acceptedAt || '').trim();
+      if (latestAcceptedAt) {
+        const latestAcceptedTs = Date.parse(latestAcceptedAt);
+        const firstSeenTs = Date.parse(String(seen.firstSeenAt || ''));
+        if (Number.isFinite(latestAcceptedTs) && Number.isFinite(firstSeenTs) && latestAcceptedTs > firstSeenTs) {
+          const receipt = completeInboundReceipt(deps, ref, messageId);
+          return { status: 'duplicate_superseded', receipt };
+        }
+      }
+    }
+    const outcome = terminalReceiptOutcomeFor(deps.getInboundAcceptance(ref, messageId));
+    if (outcome) {
+      const receipt = completeInboundReceipt(deps, ref, messageId, outcome);
+      return { status: 'duplicate_completed', receipt };
+    }
+  } else {
+    writeJsonFile(seenFile, {
+      messageId,
+      firstSeenAt: now,
+      lastSeenAt: now,
+    } satisfies SeenInboundRecord);
+  }
+
+  const receipt: InboundReceipt = {
+    messageId,
+    status: 'processing',
+    createdAt: now,
+    updatedAt: now,
+  };
+  writeJsonFile(file, receipt);
+  deps.noteInboundObserved(ref, messageId);
+  return { status: 'claimed', receipt };
+}
+
+export function completeInboundReceipt(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+  outcome?: InboundReceipt['outcome'],
+): InboundReceipt {
+  deps.ensureSessionDirs(ref);
+  const file = deps.receiptFile(ref, messageId);
+  const now = nowIso();
+  const existing = readJsonFile(file) as InboundReceipt | null;
+  const receipt: InboundReceipt = existing
+    ? { ...existing, status: 'completed', updatedAt: now, outcome: outcome || existing.outcome }
+    : { messageId, status: 'completed', createdAt: now, updatedAt: now, outcome: outcome || undefined };
+  writeJsonFile(file, receipt);
+  return receipt;
+}
+
+export function clearInboundReceipt(deps: DeliveryStoreDeps, ref: ConversationRef, messageId: string): void {
+  const file = deps.receiptFile(ref, messageId);
+  if (!fs.existsSync(file)) {
+    return;
+  }
+  try {
+    fs.rmSync(file, { force: true });
+  } catch {
+    // noop
+  }
+}
+
+export function getInboundReceipt(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+): InboundReceipt | null {
+  return readJsonFile(deps.receiptFile(ref, messageId)) as InboundReceipt | null;
+}
+
+export function recordOutboundDelivery(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  record: Omit<OutboundDeliveryRecord, 'updatedAt'>,
+): OutboundDeliveryRecord {
+  deps.ensureSessionDirs(ref);
+  const file = deps.outboundDeliveryFile(ref, record.sourceKey);
+  const current = readJsonFile(file) as OutboundDeliveryRecord | null;
+  const updated: OutboundDeliveryRecord = {
+    ...record,
+    createdAt: current?.createdAt ?? record.createdAt,
+    updatedAt: nowIso(),
+    deliveredAt: current?.deliveredAt ?? record.deliveredAt ?? null,
+    status: current?.status === 'delivered' ? 'delivered' : record.status,
+  };
+  writeJsonFile(file, updated);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'outbound_delivery_recorded',
+    at: updated.updatedAt,
+    outbound_delivery: updated,
+  });
+  return updated;
+}
+
+export function markOutboundDelivered(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  sourceKey: string,
+): OutboundDeliveryRecord | null {
+  const file = deps.outboundDeliveryFile(ref, sourceKey);
+  const current = readJsonFile(file) as OutboundDeliveryRecord | null;
+  if (!current) {
+    return null;
+  }
+  const now = nowIso();
+  const updated: OutboundDeliveryRecord = {
+    ...current,
+    status: 'delivered',
+    updatedAt: now,
+    deliveredAt: current.deliveredAt || now,
+  };
+  writeJsonFile(file, updated);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'outbound_delivery_delivered',
+    at: now,
+    outbound_delivery: updated,
+  });
+  return updated;
+}
+
+export function getOutboundDelivery(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+  sourceKey: string,
+): OutboundDeliveryRecord | null {
+  return readJsonFile(deps.outboundDeliveryFile(ref, sourceKey)) as OutboundDeliveryRecord | null;
+}
+
+export function listPendingOutboundDeliveries(
+  deps: DeliveryStoreDeps,
+  ref: ConversationRef,
+): OutboundDeliveryRecord[] {
+  const dir = path.join(deps.resolveSessionDir(ref), 'outbound-delivery');
+  if (!fs.existsSync(dir)) {
+    return [];
+  }
+  return fs.readdirSync(dir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => readJsonFile(path.join(dir, entry)) as OutboundDeliveryRecord | null)
+    .filter((record): record is OutboundDeliveryRecord => Boolean(record))
+    .filter((record) => record.status === 'pending')
+    .sort((left, right) => String(left.createdAt).localeCompare(String(right.createdAt)));
+}

package/bridge/src/session-store-human-gate.ts

@@ -0,0 +1,380 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { appendNdjson, nowIso, readJsonFile, sanitizeSegment, writeJsonFile } from './utils.ts';
+import type { ApprovalRecord, ConversationRef, PendingUserInputRecord, SessionMeta, UserInputRequest } from './types.ts';
+
+interface HumanGateStoreDeps {
+  sessionsDir: string;
+  ensureSessionDirs(ref: ConversationRef): string;
+  ensureSession(ref: ConversationRef): SessionMeta;
+  getSession(ref: ConversationRef): SessionMeta | null;
+  normalizeMeta(ref: ConversationRef, current: SessionMeta | null, now?: string): SessionMeta;
+  metaFile(ref: ConversationRef): string;
+  eventsFile(ref: ConversationRef): string;
+  approvalFile(ref: ConversationRef, approvalId: string): string;
+  pendingUserInputFile(ref: ConversationRef, requestId: string | number): string;
+}
+
+function normalizeApprovalRecord(approval: ApprovalRecord | null, meta?: SessionMeta | null): ApprovalRecord | null {
+  if (!approval) {
+    return null;
+  }
+  if (typeof approval.visible === 'boolean') {
+    return approval;
+  }
+  return {
+    ...approval,
+    visible: approval.status === 'pending' && Boolean(meta?.pendingApprovalIds.includes(approval.approvalId)),
+  };
+}
+
+function normalizePendingUserInputRecord(
+  record: PendingUserInputRecord | null,
+  meta?: SessionMeta | null,
+): PendingUserInputRecord | null {
+  if (!record) {
+    return null;
+  }
+  if (typeof record.visible === 'boolean') {
+    return record;
+  }
+  return {
+    ...record,
+    visible: record.status === 'pending' && meta?.pendingUserInputRequestId === String(record.requestId),
+  };
+}
+
+export function recordApproval(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  approval: ApprovalRecord,
+  options: { visible?: boolean } = {},
+): void {
+  deps.ensureSessionDirs(ref);
+  const meta = deps.ensureSession(ref);
+  const record: ApprovalRecord = {
+    ...approval,
+    visible: options.visible !== false,
+  };
+  if (record.visible && !meta.pendingApprovalIds.includes(record.approvalId)) {
+    meta.pendingApprovalIds.push(record.approvalId);
+  }
+  meta.updatedAt = nowIso();
+  writeJsonFile(deps.metaFile(ref), meta);
+  writeJsonFile(deps.approvalFile(ref, record.approvalId), record);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'approval_requested',
+    at: nowIso(),
+    approval: record,
+  });
+}
+
+export function markApprovalVisible(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  approvalId: string,
+): ApprovalRecord | null {
+  const meta = deps.ensureSession(ref);
+  const approval = normalizeApprovalRecord(
+    readJsonFile(deps.approvalFile(ref, approvalId)) as ApprovalRecord | null,
+    meta,
+  );
+  if (!approval || approval.status !== 'pending') {
+    return approval;
+  }
+  approval.visible = true;
+  writeJsonFile(deps.approvalFile(ref, approvalId), approval);
+  if (!meta.pendingApprovalIds.includes(approvalId)) {
+    meta.pendingApprovalIds.push(approvalId);
+    meta.updatedAt = nowIso();
+    writeJsonFile(deps.metaFile(ref), meta);
+    appendNdjson(deps.eventsFile(ref), {
+      type: 'approval_visible',
+      at: meta.updatedAt,
+      approvalId,
+    });
+  }
+  return approval;
+}
+
+export function resolveApproval(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  approvalId: string,
+  status: ApprovalRecord['status'],
+): ApprovalRecord | null {
+  const approval = normalizeApprovalRecord(
+    readJsonFile(deps.approvalFile(ref, approvalId)) as ApprovalRecord | null,
+  );
+  if (!approval) {
+    return null;
+  }
+  approval.status = status;
+  approval.visible = false;
+  writeJsonFile(deps.approvalFile(ref, approvalId), approval);
+  const meta = deps.ensureSession(ref);
+  meta.pendingApprovalIds = meta.pendingApprovalIds.filter((item) => item !== approvalId);
+  meta.updatedAt = nowIso();
+  writeJsonFile(deps.metaFile(ref), meta);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'approval_resolved',
+    at: nowIso(),
+    approvalId,
+    status,
+  });
+  return approval;
+}
+
+export function notePendingUserInput(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  request: UserInputRequest,
+  options: { visible?: boolean } = {},
+): PendingUserInputRecord {
+  deps.ensureSessionDirs(ref);
+  const meta = deps.ensureSession(ref);
+  const record: PendingUserInputRecord = {
+    ...request,
+    createdAt: nowIso(),
+    status: 'pending',
+    visible: options.visible !== false,
+  };
+  if (record.visible) {
+    meta.pendingUserInputRequestId = String(request.requestId);
+  }
+  meta.updatedAt = nowIso();
+  writeJsonFile(deps.metaFile(ref), meta);
+  writeJsonFile(deps.pendingUserInputFile(ref, request.requestId), record);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'user_input_requested',
+    at: nowIso(),
+    request: record,
+  });
+  return record;
+}
+
+export function markPendingUserInputVisible(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  requestId: string | number,
+): PendingUserInputRecord | null {
+  const meta = deps.ensureSession(ref);
+  const record = normalizePendingUserInputRecord(
+    readJsonFile(deps.pendingUserInputFile(ref, requestId)) as PendingUserInputRecord | null,
+    meta,
+  );
+  if (!record) {
+    return null;
+  }
+  record.visible = true;
+  writeJsonFile(deps.pendingUserInputFile(ref, requestId), record);
+  meta.pendingUserInputRequestId = String(record.requestId);
+  meta.updatedAt = nowIso();
+  writeJsonFile(deps.metaFile(ref), meta);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'user_input_visible',
+    at: meta.updatedAt,
+    requestId: String(record.requestId),
+  });
+  return record;
+}
+
+export function getPendingUserInput(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+): PendingUserInputRecord | null {
+  const meta = deps.getSession(ref);
+  if (!meta?.pendingUserInputRequestId) {
+    return null;
+  }
+  return normalizePendingUserInputRecord(
+    readJsonFile(deps.pendingUserInputFile(ref, meta.pendingUserInputRequestId)) as PendingUserInputRecord | null,
+    meta,
+  );
+}
+
+export function findPendingUserInputByRequestId(
+  deps: HumanGateStoreDeps,
+  requestId: string | number,
+): { meta: SessionMeta; request: PendingUserInputRecord } | null {
+  const expected = String(requestId);
+  const entries = fs.readdirSync(deps.sessionsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = path.join(deps.sessionsDir, entry.name);
+    const meta = readJsonFile(path.join(sessionDir, 'meta.json')) as SessionMeta | null;
+    if (!meta) {
+      continue;
+    }
+    const userInputsDir = path.join(sessionDir, 'user-inputs');
+    if (!fs.existsSync(userInputsDir)) {
+      continue;
+    }
+    for (const inputEntry of fs.readdirSync(userInputsDir)) {
+      if (!inputEntry.endsWith('.json')) {
+        continue;
+      }
+      const request = readJsonFile(path.join(userInputsDir, inputEntry)) as PendingUserInputRecord | null;
+      const normalized = normalizePendingUserInputRecord(request, meta);
+      if (!normalized || String(normalized.requestId) !== expected) {
+        continue;
+      }
+      return {
+        meta: deps.normalizeMeta(meta.conversationRef, meta, meta.updatedAt || nowIso()),
+        request: normalized,
+      };
+    }
+  }
+  return null;
+}
+
+export function clearPendingUserInput(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  details?: { messageId?: string | null; answerPreview?: string | null; requestId?: string | number | null },
+): void {
+  const meta = deps.ensureSession(ref);
+  const requestId = details?.requestId !== undefined && details?.requestId !== null
+    ? String(details.requestId)
+    : meta.pendingUserInputRequestId;
+  if (details && 'messageId' in details) {
+    meta.lastMessageId = details.messageId || meta.lastMessageId;
+  }
+  if (requestId) {
+    const file = deps.pendingUserInputFile(ref, requestId);
+    if (fs.existsSync(file)) {
+      try {
+        fs.rmSync(file, { force: true });
+      } catch {
+        // noop
+      }
+    }
+  }
+  if (!requestId || meta.pendingUserInputRequestId === requestId) {
+    meta.pendingUserInputRequestId = null;
+  }
+  meta.updatedAt = nowIso();
+  writeJsonFile(deps.metaFile(ref), meta);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'user_input_resolved',
+    at: nowIso(),
+    requestId: requestId || null,
+    messageId: details?.messageId || null,
+    answerPreview: details?.answerPreview || null,
+  });
+}
+
+export function findApproval(
+  deps: HumanGateStoreDeps,
+  approvalId: string,
+): { meta: SessionMeta; approval: ApprovalRecord } | null {
+  const entries = fs.readdirSync(deps.sessionsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = path.join(deps.sessionsDir, entry.name);
+    const meta = readJsonFile(path.join(sessionDir, 'meta.json')) as SessionMeta | null;
+    const approval = normalizeApprovalRecord(
+      readJsonFile(path.join(sessionDir, 'approvals', `${sanitizeSegment(approvalId)}.json`)) as ApprovalRecord | null,
+      meta,
+    );
+    if (!approval) continue;
+    if (!meta) continue;
+    return { meta: deps.normalizeMeta(meta.conversationRef, meta, meta.updatedAt || nowIso()), approval };
+  }
+  return null;
+}
+
+export function findApprovalByRequestId(
+  deps: HumanGateStoreDeps,
+  requestId: string | number,
+): { meta: SessionMeta; approval: ApprovalRecord } | null {
+  const expected = String(requestId);
+  const entries = fs.readdirSync(deps.sessionsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const sessionDir = path.join(deps.sessionsDir, entry.name);
+    const approvalsDir = path.join(sessionDir, 'approvals');
+    if (!fs.existsSync(approvalsDir)) {
+      continue;
+    }
+    for (const approvalEntry of fs.readdirSync(approvalsDir)) {
+      if (!approvalEntry.endsWith('.json')) {
+        continue;
+      }
+      const meta = readJsonFile(path.join(sessionDir, 'meta.json')) as SessionMeta | null;
+      const approval = normalizeApprovalRecord(
+        readJsonFile(path.join(approvalsDir, approvalEntry)) as ApprovalRecord | null,
+        meta,
+      );
+      if (!approval || String(approval.requestId) !== expected) {
+        continue;
+      }
+      if (!meta) {
+        continue;
+      }
+      return { meta: deps.normalizeMeta(meta.conversationRef, meta, meta.updatedAt || nowIso()), approval };
+    }
+  }
+  return null;
+}
+
+export function getApproval(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  approvalId: string,
+): ApprovalRecord | null {
+  return normalizeApprovalRecord(
+    readJsonFile(deps.approvalFile(ref, approvalId)) as ApprovalRecord | null,
+    deps.getSession(ref),
+  );
+}
+
+export function listPendingApprovals(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+): ApprovalRecord[] {
+  const meta = deps.getSession(ref);
+  const approvalsDir = path.join(deps.ensureSessionDirs(ref), 'approvals');
+  if (!fs.existsSync(approvalsDir)) {
+    return [];
+  }
+  return fs.readdirSync(approvalsDir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => normalizeApprovalRecord(
+      readJsonFile(path.join(approvalsDir, entry)) as ApprovalRecord | null,
+      meta,
+    ))
+    .filter((approval): approval is ApprovalRecord => Boolean(approval) && approval.status === 'pending')
+    .sort((left, right) => String(left.createdAt || '').localeCompare(String(right.createdAt || '')));
+}
+
+export function listHiddenPendingApprovals(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  turnId?: string | null,
+): ApprovalRecord[] {
+  return listPendingApprovals(deps, ref)
+    .filter((approval) => !approval.visible)
+    .filter((approval) => !turnId || approval.turnId === turnId);
+}
+
+export function findHiddenPendingUserInput(
+  deps: HumanGateStoreDeps,
+  ref: ConversationRef,
+  turnId?: string | null,
+): PendingUserInputRecord | null {
+  const meta = deps.getSession(ref);
+  const userInputsDir = path.join(deps.ensureSessionDirs(ref), 'user-inputs');
+  if (!fs.existsSync(userInputsDir)) {
+    return null;
+  }
+  return fs.readdirSync(userInputsDir)
+    .filter((entry) => entry.endsWith('.json'))
+    .map((entry) => normalizePendingUserInputRecord(
+      readJsonFile(path.join(userInputsDir, entry)) as PendingUserInputRecord | null,
+      meta,
+    ))
+    .filter((record): record is PendingUserInputRecord => Boolean(record) && record.status === 'pending' && !record.visible)
+    .filter((record) => !turnId || record.turnId === turnId)
+    .sort((left, right) => String(left.createdAt || '').localeCompare(String(right.createdAt || '')))[0] || null;
+}

package/bridge/src/session-store-inbound-acceptance.ts

@@ -0,0 +1,66 @@
+import { appendNdjson, nowIso, readJsonFile, writeJsonFile } from './utils.ts';
+import type { ConversationRef, InboundAcceptanceRecord } from './types.ts';
+
+export interface InboundAcceptanceStoreDeps {
+  ensureSessionDirs(ref: ConversationRef): string;
+  eventsFile(ref: ConversationRef): string;
+  inboundAcceptanceFile(ref: ConversationRef, messageId: string): string;
+}
+
+function normalizeInboundAcceptance(
+  messageId: string,
+  current: InboundAcceptanceRecord | null,
+  seed: Partial<InboundAcceptanceRecord> = {},
+  now = nowIso(),
+): InboundAcceptanceRecord {
+  return {
+    messageId,
+    threadId: current?.threadId ?? seed.threadId ?? null,
+    turnId: current?.turnId ?? seed.turnId ?? null,
+    createdAt: current?.createdAt || now,
+    updatedAt: now,
+    acceptedAt: current?.acceptedAt ?? seed.acceptedAt ?? null,
+    executionStatus: current?.executionStatus || seed.executionStatus || 'received',
+  };
+}
+
+export function updateInboundAcceptance(
+  deps: InboundAcceptanceStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+  seed: Partial<InboundAcceptanceRecord> = {},
+  mutate?: (record: InboundAcceptanceRecord, now: string) => void,
+): InboundAcceptanceRecord {
+  deps.ensureSessionDirs(ref);
+  const file = deps.inboundAcceptanceFile(ref, messageId);
+  const current = readJsonFile(file) as InboundAcceptanceRecord | null;
+  const now = nowIso();
+  const record = normalizeInboundAcceptance(messageId, current, seed, now);
+  mutate?.(record, now);
+  record.updatedAt = now;
+  writeJsonFile(file, record);
+  appendNdjson(deps.eventsFile(ref), {
+    type: 'inbound_acceptance_updated',
+    at: now,
+    inbound: record,
+  });
+  return record;
+}
+
+export function noteInboundObserved(
+  deps: InboundAcceptanceStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+): InboundAcceptanceRecord {
+  return updateInboundAcceptance(deps, ref, messageId, {}, (record) => {
+    record.executionStatus = record.executionStatus || 'received';
+  });
+}
+
+export function getInboundAcceptance(
+  deps: InboundAcceptanceStoreDeps,
+  ref: ConversationRef,
+  messageId: string,
+): InboundAcceptanceRecord | null {
+  return readJsonFile(deps.inboundAcceptanceFile(ref, messageId)) as InboundAcceptanceRecord | null;
+}