@remnic/core 9.7.10 → 9.7.11

package/src/index.ts

@@ -387,6 +387,59 @@ export {
 } from "./access-http.js";
 export { EngramMcpServer } from "./access-mcp.js";
 
+// Remnic Relay — host-agnostic mission evidence and receipt contract.
+export {
+  RELAY_MISSION_DEFAULT_EVENT_LIMIT,
+  RELAY_MISSION_MAX_EVENT_LIMIT,
+  RELAY_MISSION_MAX_EVENTS,
+  RELAY_MISSION_MAX_FILE_BYTES,
+  RELAY_MISSION_MAX_LINE_BYTES,
+  RELAY_MISSION_SCHEMA_VERSION,
+  RelayEvidenceRefSchema,
+  RelayMissionEventInputSchema,
+  RelayMissionEventSchema,
+  RelayMissionPayloadSchema,
+  RelayMissionReadOptionsSchema,
+  RelayMissionStore,
+  RelayMissionStoreError,
+  compareRelayEvents,
+  reduceRelayMission,
+  relayMissionReceiptDigest,
+  type RelayAgentOutputSnapshot,
+  type RelayAgentSnapshot,
+  type RelayConflictSnapshot,
+  type RelayCorrectionSnapshot,
+  type RelayDecisionSnapshot,
+  type RelayEvidenceRef,
+  type RelayMissionAppendResult,
+  type RelayMissionEvent,
+  type RelayMissionEventInput,
+  type RelayMissionPayload,
+  type RelayMissionReadOptions,
+  type RelayMissionSnapshot,
+  type RelayMissionStatus,
+  type RelayMissionStoreErrorCode,
+  type RelayMissionStoreOptions,
+  type RelayPropagationSnapshot,
+  type RelayRecallSnapshot,
+  type RelayTestSnapshot,
+} from "./relay/mission.js";
+export {
+  RELAY_DEMO_MISSION_ID,
+  RELAY_DEMO_NAMESPACE,
+  createRelayMissionFixture,
+} from "./relay/mission-fixture.js";
+export {
+  appendRelayMissionEvent,
+  readRelayMission,
+  relayMissionAppendOperation,
+  relayMissionReadOperation,
+  type RelayMissionAppendAccessInput,
+  type RelayMissionAppendAccessOutput,
+  type RelayMissionReadAccessInput,
+  type RelayMissionReadAccessOutput,
+} from "./relay/mission-access.js";
+
 // agentAccessHttp.authToken SecretRef resolution (issue #757). Exposed so
 // host-specific bootstrap code (the OpenClaw plugin in `src/index.ts`, the
 // standalone server, the CLI) can resolve a SecretRef to a literal bearer

package/src/relay/mission-access.test.ts

@@ -0,0 +1,379 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { EngramAccessHttpServer } from "../access-http.js";
+import { EngramAccessInputError, type EngramAccessService } from "../access-service.js";
+import type { StorageManager } from "../storage.js";
+import { RELAY_DEMO_MISSION_ID, RELAY_DEMO_NAMESPACE, createRelayMissionFixture } from "./mission-fixture.js";
+import type { RelayMissionSnapshot } from "./mission.js";
+
+async function withTempRoot(run: (root: string) => Promise<void>): Promise<void> {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-relay-http-"));
+  try {
+    await run(root);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+}
+
+function fakeService(
+  root: string,
+  calls: Array<{ mode: "read" | "write"; namespace?: string; principal?: string }>
+): EngramAccessService {
+  const storage = { dir: root } as StorageManager;
+  return {
+    configRef: {
+      defaultNamespace: RELAY_DEMO_NAMESPACE,
+      namespacesEnabled: true,
+    },
+    getReadableStorageForNamespace: async (namespace?: string, principal?: string) => {
+      if (namespace === "forbidden") throw new EngramAccessInputError("namespace is not readable");
+      calls.push({ mode: "read", namespace, principal });
+      return { namespace: namespace ?? RELAY_DEMO_NAMESPACE, storage };
+    },
+    getWritableStorageForNamespace: async (namespace?: string, principal?: string) => {
+      if (namespace === "forbidden") throw new EngramAccessInputError("namespace is not writable");
+      calls.push({ mode: "write", namespace, principal });
+      return { namespace: namespace ?? RELAY_DEMO_NAMESPACE, storage };
+    },
+  } as unknown as EngramAccessService;
+}
+
+function authHeaders(token = "relay-token"): Record<string, string> {
+  return {
+    authorization: `Bearer ${token}`,
+    "content-type": "application/json",
+  };
+}
+
+test("HTTP fixture endpoint returns one complete, namespace-authorized Relay receipt", async () => {
+  await withTempRoot(async (root) => {
+    const calls: Array<{
+      mode: "read" | "write";
+      namespace?: string;
+      principal?: string;
+    }> = [];
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, calls),
+      port: 0,
+      authToken: "relay-token",
+      principal: "relay-operator",
+      adminConsoleEnabled: false,
+    });
+    const status = await server.start();
+    const base = `http://127.0.0.1:${status.port}/engram/v1/relay/missions/${RELAY_DEMO_MISSION_ID}`;
+    try {
+      const fixture = createRelayMissionFixture();
+      const blankNamespace = await fetch(`${base}/events`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ namespace: "", event: fixture[0] }),
+      });
+      assert.equal(blankNamespace.status, 400);
+
+      const flatBody = await fetch(`${base}/events`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify(fixture[0]),
+      });
+      assert.equal(flatBody.status, 400);
+
+      for (const input of fixture) {
+        const response = await fetch(`${base}/events`, {
+          method: "POST",
+          headers: authHeaders(),
+          body: JSON.stringify({ namespace: RELAY_DEMO_NAMESPACE, event: input }),
+        });
+        const responseBody = await response.text();
+        assert.equal(response.status, 201, responseBody);
+        assert.equal(
+          (JSON.parse(responseBody) as { event: { authenticatedPrincipal?: string } }).event.authenticatedPrincipal,
+          "relay-operator"
+        );
+      }
+
+      const replay = await fetch(`${base}/events`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ namespace: RELAY_DEMO_NAMESPACE, event: fixture[0] }),
+      });
+      assert.equal(replay.status, 200);
+      assert.equal(((await replay.json()) as { replayed: boolean }).replayed, true);
+
+      const response = await fetch(`${base}?namespace=${RELAY_DEMO_NAMESPACE}&limit=20`, {
+        headers: authHeaders(),
+      });
+      assert.equal(response.status, 200);
+      assert.equal(response.headers.get("cache-control"), "no-store");
+      const snapshot = (await response.json()) as RelayMissionSnapshot;
+      assert.equal(snapshot.receipt.complete, true);
+      assert.deepEqual(snapshot.receipt.activeDecisionIds, ["decision-refresh-after-expiry"]);
+      assert.deepEqual(snapshot.receipt.supersededDecisionIds, ["decision-new-token-every-request"]);
+      assert.equal(snapshot.agents.length, 3);
+      assert.equal(snapshot.tests.at(-1)?.status, "passed");
+      assert.ok(calls.every((call) => call.namespace === RELAY_DEMO_NAMESPACE));
+      assert.ok(calls.every((call) => call.principal === "relay-operator"));
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("HTTP Relay surface distinguishes empty, invalid, unauthorized, and backend-failed reads", async () => {
+  await withTempRoot(async (root) => {
+    const service = fakeService(root, []);
+    const server = new EngramAccessHttpServer({
+      service,
+      port: 0,
+      authTokenEntriesGetter: () => [
+        {
+          token: "read-token",
+          connector: "codex",
+          capabilities: {
+            version: 1,
+            ops: ["relay_mission_read"],
+            namespaces: [RELAY_DEMO_NAMESPACE],
+          },
+        },
+      ],
+      adminConsoleEnabled: false,
+    });
+    const status = await server.start();
+    const origin = `http://127.0.0.1:${status.port}`;
+    const emptyUrl = `${origin}/engram/v1/relay/missions/empty-mission?namespace=${RELAY_DEMO_NAMESPACE}`;
+    try {
+      const unauthenticated = await fetch(emptyUrl);
+      assert.equal(unauthenticated.status, 401);
+
+      const empty = await fetch(emptyUrl, { headers: authHeaders("read-token") });
+      assert.equal(empty.status, 200);
+      assert.deepEqual(await empty.json(), assertEmptyMissionShape());
+
+      const badLimit = await fetch(`${emptyUrl}&limit=501`, {
+        headers: authHeaders("read-token"),
+      });
+      assert.equal(badLimit.status, 400);
+
+      const blankNamespace = await fetch(`${origin}/engram/v1/relay/missions/empty-mission?namespace=`, {
+        headers: authHeaders("read-token"),
+      });
+      assert.equal(blankNamespace.status, 400);
+
+      const badSince = await fetch(`${emptyUrl}&since=${encodeURIComponent("2026-01-01T00:00:00+99:99")}`, {
+        headers: authHeaders("read-token"),
+      });
+      assert.equal(badSince.status, 400);
+
+      const traversal = await fetch(
+        `${origin}/engram/v1/relay/missions/%2E%2Eproduction?namespace=${RELAY_DEMO_NAMESPACE}`,
+        {
+          headers: authHeaders("read-token"),
+        }
+      );
+      assert.equal(traversal.status, 400);
+
+      const wrongNamespace = await fetch(`${origin}/engram/v1/relay/missions/empty-mission?namespace=forbidden`, {
+        headers: authHeaders("read-token"),
+      });
+      assert.equal(wrongNamespace.status, 403);
+
+      const deniedWrite = await fetch(`${origin}/engram/v1/relay/missions/${RELAY_DEMO_MISSION_ID}/events`, {
+        method: "POST",
+        headers: authHeaders("read-token"),
+        body: JSON.stringify({
+          namespace: RELAY_DEMO_NAMESPACE,
+          event: createRelayMissionFixture()[0],
+        }),
+      });
+      assert.equal(deniedWrite.status, 403);
+    } finally {
+      await server.stop();
+    }
+  });
+
+  await withTempRoot(async (root) => {
+    const missingRoot = path.join(root, "missing-storage-root");
+    const server = new EngramAccessHttpServer({
+      service: fakeService(missingRoot, []),
+      port: 0,
+      authToken: "relay-token",
+      adminConsoleEnabled: false,
+    });
+    const status = await server.start();
+    try {
+      const response = await fetch(`http://127.0.0.1:${status.port}/engram/v1/relay/missions/backend-failure`, {
+        headers: authHeaders(),
+      });
+      assert.equal(response.status, 500);
+      assert.equal(((await response.json()) as { code: string }).code, "relay_unsafe_path");
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("HTTP Relay write quota is charged only for a real append, never an idempotent replay", async () => {
+  await withTempRoot(async (root) => {
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, []),
+      port: 0,
+      authToken: "relay-token",
+      adminConsoleEnabled: false,
+      writeRateLimitMaxRequests: 1,
+      writeRateLimitWindowMs: 60_000,
+    });
+    const status = await server.start();
+    const url = `http://127.0.0.1:${status.port}/engram/v1/relay/missions/${RELAY_DEMO_MISSION_ID}/events`;
+    const fixture = createRelayMissionFixture();
+    try {
+      const first = await fetch(url, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ event: fixture[0] }),
+      });
+      assert.equal(first.status, 201);
+
+      const replay = await fetch(url, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ event: fixture[0] }),
+      });
+      assert.equal(replay.status, 200);
+      assert.equal(((await replay.json()) as { replayed: boolean }).replayed, true);
+
+      const secondEvent = await fetch(url, {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ event: fixture[1] }),
+      });
+      assert.equal(secondEvent.status, 429);
+      assert.equal(((await secondEvent.json()) as { code: string }).code, "write_rate_limited");
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("HTTP Relay reserves global write quota across concurrent mission appends", async () => {
+  await withTempRoot(async (root) => {
+    const server = new EngramAccessHttpServer({
+      service: fakeService(root, []),
+      port: 0,
+      authToken: "relay-token",
+      adminConsoleEnabled: false,
+      writeRateLimitMaxRequests: 1,
+      writeRateLimitWindowMs: 60_000,
+    });
+    const status = await server.start();
+    const missionIds = ["concurrent-mission-a", "concurrent-mission-b"];
+    const startEvent = createRelayMissionFixture()[0];
+    assert.ok(startEvent);
+    const urls = missionIds.map(
+      (missionId) => `http://127.0.0.1:${status.port}/engram/v1/relay/missions/${missionId}/events`
+    );
+    try {
+      const responses = await Promise.all(
+        urls.map((url) =>
+          fetch(url, {
+            method: "POST",
+            headers: authHeaders(),
+            body: JSON.stringify({ event: startEvent }),
+          })
+        )
+      );
+      assert.deepEqual(
+        responses.map((response) => response.status).sort((a, b) => a - b),
+        [201, 429]
+      );
+
+      const winnerIndex = responses.findIndex((response) => response.status === 201);
+      assert.notEqual(winnerIndex, -1);
+      const replay = await fetch(urls[winnerIndex] ?? "", {
+        method: "POST",
+        headers: authHeaders(),
+        body: JSON.stringify({ event: startEvent }),
+      });
+      assert.equal(replay.status, 200);
+      assert.equal(((await replay.json()) as { replayed: boolean }).replayed, true);
+    } finally {
+      await server.stop();
+    }
+  });
+});
+
+test("Relay write quota releases the exact reservation when timestamps collide", () => {
+  const server = new EngramAccessHttpServer({
+    service: {} as EngramAccessService,
+    port: 0,
+    authToken: "relay-token",
+    adminConsoleEnabled: false,
+  });
+  const internals = server as unknown as {
+    writeRequestSlots: Array<{ readonly recordedAt: number }>;
+    reserveWriteRateLimitSlot: () => () => void;
+  };
+  const originalNow = Date.now;
+  try {
+    Date.now = () => 1_754_000_000_000;
+    const releaseCommitted = internals.reserveWriteRateLimitSlot();
+    const committedSlot = internals.writeRequestSlots[0];
+    const releaseFailed = internals.reserveWriteRateLimitSlot();
+    const failedSlot = internals.writeRequestSlots[1];
+    assert.ok(committedSlot);
+    assert.ok(failedSlot);
+    assert.notEqual(committedSlot, failedSlot);
+
+    releaseFailed();
+    assert.deepEqual(internals.writeRequestSlots, [committedSlot]);
+
+    releaseCommitted();
+    assert.deepEqual(internals.writeRequestSlots, []);
+  } finally {
+    Date.now = originalNow;
+  }
+});
+
+function assertEmptyMissionShape(): RelayMissionSnapshot {
+  return {
+    schemaVersion: "1",
+    missionId: "empty-mission",
+    namespace: RELAY_DEMO_NAMESPACE,
+    found: false,
+    readHealth: "empty",
+    status: "not_started",
+    mission: {
+      title: null,
+      objective: null,
+      runMode: null,
+      startedAt: null,
+      completedAt: null,
+    },
+    agents: [],
+    decisions: [],
+    conflicts: [],
+    corrections: [],
+    tests: [],
+    propagation: [],
+    outcome: null,
+    receipt: {
+      complete: false,
+      missingEvidence: [],
+      activeDecisionIds: [],
+      supersededDecisionIds: [],
+      coldStartVerified: false,
+      passingOutcomeVerified: false,
+    },
+    bounds: {
+      totalEvents: 0,
+      returnedEvents: 0,
+      corruptLines: 0,
+      truncated: false,
+      since: null,
+      until: null,
+    },
+    events: [],
+  };
+}

package/src/relay/mission-access.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+
+import { type OperationContext, defineOperation } from "../access-boundary.js";
+import type { EngramAccessService } from "../access-service.js";
+import {
+  RELAY_MISSION_MAX_EVENT_LIMIT,
+  RelayIsoDateTimeSchema,
+  type RelayMissionAppendResult,
+  type RelayMissionEventInput,
+  RelayMissionEventInputSchema,
+  RelayMissionIdSchema,
+  type RelayMissionReadOptions,
+  RelayMissionReadOptionsSchema,
+  type RelayMissionSnapshot,
+  RelayMissionStore,
+} from "./mission.js";
+
+const namespaceSchema = z.string().trim().min(1).max(128).nullable().optional();
+
+const RelayMissionAppendAccessSchema = z
+  .object({
+    missionId: RelayMissionIdSchema,
+    namespace: namespaceSchema,
+    event: RelayMissionEventInputSchema,
+  })
+  .strict();
+
+const optionalLimitSchema = z.preprocess((value) => {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string" && /^(?:0|[1-9]\d*)$/.test(value)) return Number(value);
+  return value;
+}, z.number().int().min(1).max(RELAY_MISSION_MAX_EVENT_LIMIT).optional());
+
+const RelayMissionReadAccessSchema = z
+  .object({
+    missionId: RelayMissionIdSchema,
+    namespace: namespaceSchema,
+    since: RelayIsoDateTimeSchema.optional(),
+    until: RelayIsoDateTimeSchema.optional(),
+    limit: optionalLimitSchema,
+  })
+  .strict()
+  .refine(
+    (value) =>
+      value.since === undefined || value.until === undefined || Date.parse(value.since) < Date.parse(value.until),
+    { message: "since must be earlier than until", path: ["until"] }
+  );
+
+export interface RelayMissionAppendAccessInput {
+  missionId: string;
+  namespace?: string | null;
+  event: RelayMissionEventInput;
+}
+
+export interface RelayMissionReadAccessInput extends RelayMissionReadOptions {
+  missionId: string;
+  namespace?: string | null;
+}
+
+export interface RelayMissionAppendAccessOutput {
+  result: RelayMissionAppendResult;
+}
+
+export interface RelayMissionReadAccessOutput {
+  result: RelayMissionSnapshot;
+}
+
+/**
+ * Shared service contract for transports that need to append Relay evidence.
+ * Namespace resolution stays in the existing access service so the append
+ * inherits the same tenancy and principal rules as every memory write.
+ */
+export async function appendRelayMissionEvent(
+  service: EngramAccessService,
+  input: RelayMissionAppendAccessInput,
+  authenticatedPrincipal?: string,
+  beforeAppend?: () => void | Promise<void>
+): Promise<RelayMissionAppendResult> {
+  const resolved = await service.getWritableStorageForNamespace(input.namespace ?? undefined, authenticatedPrincipal);
+  const store = new RelayMissionStore({
+    rootDir: resolved.storage.dir,
+    namespace: resolved.namespace,
+  });
+  return store.append(input.missionId, input.event, { authenticatedPrincipal, beforeAppend });
+}
+
+/** Namespace-authorized, bounded Relay snapshot read shared by HTTP and UI. */
+export async function readRelayMission(
+  service: EngramAccessService,
+  input: RelayMissionReadAccessInput,
+  authenticatedPrincipal?: string
+): Promise<RelayMissionSnapshot> {
+  const resolved = await service.getReadableStorageForNamespace(input.namespace ?? undefined, authenticatedPrincipal);
+  const store = new RelayMissionStore({
+    rootDir: resolved.storage.dir,
+    namespace: resolved.namespace,
+  });
+  const options = RelayMissionReadOptionsSchema.parse({
+    ...(input.since === undefined ? {} : { since: input.since }),
+    ...(input.until === undefined ? {} : { until: input.until }),
+    ...(input.limit === undefined ? {} : { limit: input.limit }),
+  });
+  return store.read(input.missionId, options);
+}
+
+export const relayMissionAppendOperation = defineOperation<
+  RelayMissionAppendAccessInput,
+  RelayMissionAppendAccessOutput
+>({
+  name: "relay_mission_append",
+  description: "Append one evidence-backed event to an isolated Relay mission.",
+  schema: RelayMissionAppendAccessSchema as z.ZodType<RelayMissionAppendAccessInput>,
+  handler: async (input, ctx: OperationContext) => ({
+    result: await appendRelayMissionEvent(ctx.service, input, ctx.authenticatedPrincipal, ctx.hooks?.enforceWriteQuota),
+  }),
+});
+
+export const relayMissionReadOperation = defineOperation<RelayMissionReadAccessInput, RelayMissionReadAccessOutput>({
+  name: "relay_mission_read",
+  description: "Read one bounded, browser-ready Relay mission receipt.",
+  schema: RelayMissionReadAccessSchema as z.ZodType<RelayMissionReadAccessInput>,
+  handler: async (input, ctx: OperationContext) => ({
+    result: await readRelayMission(ctx.service, input, ctx.authenticatedPrincipal),
+  }),
+});