@open-everywhere/core 0.1.0

package/agent/channels/read-spool.ts

@@ -0,0 +1,131 @@
+// read-spool — what a read verb does when the page it fetched is too big to put in front of a conversational model. Under {@link SEAT_READ_INLINE_CAP} nothing happens and the rendered body is byte-identical; over it the page is trimmed, the FULL page is written to this session's sandbox, and the result carries a note naming the file and the moves that are open.
+// It keeps the LEADING messages, not the newest: a read page renders oldest-first and the newest end is what the wake envelope already put in front of the model, so the head is the half the seat cannot otherwise see. Fail-soft but loud — a sandbox that will not spin does not fail the read, and the note says the rest is readable nowhere rather than implying the model saw more than it did.
+
+import { hashResultBody } from "../access/loop-breaker.js";
+import type { BindableContext } from "../identity/binding.js";
+import type { ChannelReadOutput, ReadOutputLine } from "./channel-read.js";
+
+/**
+ * The inline ceiling, in characters of rendered message body. A whole default channel page fits under it in ordinary chat, so the common recovery read spools nothing and pays no sandbox latency.
+ * A page that exceeds it is, by construction, a page a router seat should be narrowing or delegating rather than reading whole.
+ */
+export const SEAT_READ_INLINE_CAP = 12_000;
+
+/** Where in the sandbox a spooled page lands. Anchored under /workspace like the memory tiers. */
+const READ_SPOOL_DIR = "reads";
+
+/** What a trimmed read tells the model about the part it did not show. `path` is absent when the
+ *  spool could not be written — the note then says so rather than pointing at nothing. */
+export interface ReadSpool {
+  readonly path?: string;
+  /** How many messages the model can actually see inline. */
+  readonly shown: number;
+  /** How many the fetch returned. */
+  readonly total: number;
+}
+
+/** The rendered cost of one message line, matching `renderChannelBody`'s `[author] text` plus the
+ *  joining newline. Exact rather than approximate so the cap means what it says. */
+function lineCost(m: ReadOutputLine): number {
+  return m.author.length + m.text.length + 4; // "[" + "] " + "\n"
+}
+
+/**
+ * Trim a page to the inline cap, oldest first. PURE — it returns the leading messages that fit.
+ * A SINGLE message longer than the whole cap is kept with its text clamped, because returning nothing would be a worse answer; `clamped` says so, and the caller spools on it exactly as it spools on a dropped message.
+ */
+export function trimToInlineCap(messages: readonly ReadOutputLine[], cap: number = SEAT_READ_INLINE_CAP): { shown: ReadOutputLine[]; clamped: boolean } {
+  const shown: ReadOutputLine[] = [];
+  let budget = cap;
+  for (const m of messages) {
+    const cost = lineCost(m);
+    if (cost <= budget) {
+      shown.push(m);
+      budget -= cost;
+      continue;
+    }
+    if (shown.length === 0) {
+      // The first message alone busts the cap: keep its head rather than showing nothing.
+      const room = Math.max(0, cap - (m.author.length + 4));
+      shown.push({ ...m, text: m.text.slice(0, room) });
+      return { shown, clamped: true };
+    }
+    break;
+  }
+  return { shown, clamped: false };
+}
+
+/**
+ * A path-safe slice of a channel key. The key is OPAQUE, so it is sanitised rather than parsed.
+ * The allowed set excludes `.` as well as `/`: keeping dots would let a key of `../../etc/passwd` survive as the literal substring `..`, a traversal waiting for the next reader of this path to join it differently.
+ */
+function safeKeySegment(key: string): string {
+  return key.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+}
+
+/** The sandbox path a spooled page lands on. PURE and content-addressed: the hash of the full body makes two different reads land on two files, and a re-read of the same page land on the same one. */
+export function spoolPathFor(kind: "channel" | "thread", channelKey: string, body: string): string {
+  return `${READ_SPOOL_DIR}/${kind}-${safeKeySegment(channelKey)}-${hashResultBody(body).replace(":", "-")}.txt`;
+}
+
+/** The note appended after a trimmed body. PURE. Teaches the two moves that are open, in the order
+ *  a router should try them: narrow the read, or hand the file to a worker. */
+export function spoolNote(kind: "channel" | "thread", spool: ReadSpool): string {
+  const unit = kind === "channel" ? "messages" : "replies";
+  const head = `\n\n[oversize: this page held ${spool.total} ${unit} and only the OLDEST ${spool.shown} are shown above.`;
+  if (spool.path === undefined) {
+    return (
+      `${head} The rest could not be written to a file here, so it is not readable anywhere. ` +
+      `Call again with a smaller \`limit\` or a narrower target, or delegate a worker to read the rest.]`
+    );
+  }
+  return (
+    `${head} The FULL page is written to \`${spool.path}\` in this session's workspace. ` +
+    `A worker you delegate shares this workspace and can read that file. ` +
+    `Or call again with a smaller \`limit\` to see less of it here.]`
+  );
+}
+
+/** The narrow slice of an eve tool context this module uses. Declared locally for the same reason
+ *  hooks/memory.ts declares its own: `BindableContext` does not carry `getSandbox`. */
+interface SandboxCapableContext {
+  getSandbox?: () => Promise<{ writeTextFile: (input: { path: string; content: string }) => Promise<unknown> }>;
+}
+
+/**
+ * Write the full rendered page into this session's sandbox and return its path, or `undefined` when it could not be written.
+ * NEVER throws — a spool failure degrades the note, never the read.
+ */
+async function writeSpool(ctx: BindableContext, path: string, body: string): Promise<string | undefined> {
+  try {
+    const getSandbox = (ctx as unknown as SandboxCapableContext).getSandbox;
+    if (typeof getSandbox !== "function") return undefined;
+    const sandbox = await getSandbox();
+    await sandbox.writeTextFile({ path, content: body });
+    return path;
+  } catch (err) {
+    console.log(`[open-everywhere:read-spool] could not spool an oversize read to ${path}: ${err instanceof Error ? err.message : String(err)}`);
+    return undefined;
+  }
+}
+
+/**
+ * APPLY the cap to one read result — the single seam both generic read verbs call, so a channel read and a thread read can never disagree about what oversize means.
+ * `renderFull` is a THUNK on purpose: it runs only on the oversize path, so the overwhelmingly common under-cap read never renders its body twice and returns the SAME object. The caller owns the render because importing it here would close a module cycle.
+ */
+export async function capReadForInline<T extends ChannelReadOutput>(
+  ctx: BindableContext,
+  out: T,
+  kind: "channel" | "thread",
+  /** The OPAQUE CHANNEL KEY the model addressed (OPE-746), NOT `out.channel` — that still carries the
+   *  platform's raw container id at this point, and the spool path is model-visible. */
+  channelKey: string,
+  renderFull: () => string,
+  cap: number = SEAT_READ_INLINE_CAP,
+): Promise<T> {
+  const { shown, clamped } = trimToInlineCap(out.messages, cap);
+  if (!clamped && shown.length === out.messages.length) return out;
+  const fullBody = renderFull();
+  const path = await writeSpool(ctx, spoolPathFor(kind, channelKey, fullBody), fullBody);
+  return { ...out, messages: shown, spool: { ...(path === undefined ? {} : { path }), shown: shown.length, total: out.messages.length } };
+}

package/agent/channels/reply-edit.ts

@@ -0,0 +1,208 @@
+// reply-edit — the cross-surface EDIT spine for the `edit_reply` tool: rewrite the text of a message THIS deployment already posted, in place. TWO FENCES, neither trusting the model: the LOCUS is host-resolved from the session binding or the frozen wake origin, so an edit can never reach outside the conversation the turn already holds, and the MESSAGE ID the model authors must be in the own-post ledger at that locus and inside the edit window, or the call is REFUSED and AUDITED before any byte leaves.
+// `reply`'s done/declined marks, its answered refusal and the freshness gate deliberately do NOT carry over, because an edit posts nothing and adds no message to the room. There is no pending-delegation FRAME to carry either: OPE-1516 deleted it, so the host writes nothing on a post made while a worker still owes the answer, and there is no host line an edit could remove. What carries over instead is the INSTRUCTION — BOTH `tools/edit_reply.ts` variants tell the model, on exactly the turns where a worker this turn dispatched has not reported, that its edited text must not present that worker's answer. The hazard is the same one the frame guarded (an edit turns a hand-off note into a fabricated final answer) and the mechanism is now the model's own words, which is what OPE-1516 traded for.
+// 🔴 BOTH VARIANTS, NEVER THE UNIFIED ONE ALONE (OPE-1575). A standing channel-root seat on a per-surface deployment both delegates and mounts `baseEditReplyEntry`, so an edit door that instructed only the unified seat left that seat able to edit its own hand-off note into a fabricated final answer. `channels/turn-delivery.ts` carries the full enumeration of the doors beside the sentence itself.
+
+import { appendAudit } from "../audit/audit.js";
+import { swallowRoomOp } from "./egress-spoof.js";
+import { postArm } from "./post-arms.js";
+import { isOwnPost, type OwnPostLedgerDeps } from "./own-post-ledger.js";
+import { markNotApplied, platformFailureClass, platformFailureStatus, type PlatformFailureClass } from "./platform-failure.js";
+import { truncateMemoryCitationPaths } from "./turn-delivery.js";
+import { applyReplyProvenance, auditReplyProvenance } from "./reply-provenance.js";
+import { auditWithheldMemoryClaim, guardMemoryClaims } from "./memory-claim-guard.js";
+import { auditWithheldApprovalClaim, guardApprovalClaims } from "./approval-claim-guard.js";
+import { auditWithheldRequestClaim, guardRequestClaims } from "./request-claim-guard.js";
+import type { ReplyAudit } from "./reply-post.js";
+
+/**
+ * WHERE an edit lands. Host-resolved in every field.
+ * `channelId` is the conversation the message sits in — a Slack channel, a Discord channel (a Discord thread IS its own channel), a Teams conversation, a Linear issue. `serviceUrl` is Teams-only and the arm re-validates it against the trusted-host allowlist; `organizationId` is Linear-only, and absent means the primary credential chain.
+ */
+export interface EditLocus {
+  readonly platform: string;
+  readonly channelId: string;
+  readonly serviceUrl?: string;
+  readonly organizationId?: string;
+}
+
+/** `detail.reason` on a `reply.edit.refused` row — the model named a message this deployment's reply
+ *  spine did not post at this locus (or posted outside the edit window). ONE greppable string shared
+ *  by the emitter, the refusal copy and the test. */
+export const EDIT_NOT_OWN_REFUSAL_REASON = "not-own-post";
+
+/** `detail.reason` — this surface has no edit primitive wired (no `editMessage` on its post arm). */
+export const EDIT_NO_ARM_REFUSAL_REASON = "no-edit-arm";
+
+/**
+ * `detail.reason` — the host allowed the edit and the PLATFORM rejected it. Every outcome of the verb leaves exactly one row, so the trail carries no silent hole.
+ * The row is a REFUSAL, not an edit, because no message changed: `not-own-post` and `no-edit-arm` are host verdicts decided before any byte leaves, `platform-error` is the vendor's answer after the call. `detail.status` is the platform's HTTP status, a number and never a response body.
+ */
+export const EDIT_PLATFORM_ERROR_REASON = "platform-error";
+
+/**
+ * The EDIT verb's half of the terminal-failure rule (channels/turn-terminal-actions.ts); the classifier itself lives in channels/platform-failure.ts.
+ * DEFINITIVE: the platform proves nothing changed, so the turn stays open and a fresh `reply` is the remedy. AMBIGUOUS: the edit may have applied, so the verb is terminal — a repeat EDIT is safe because an edit is idempotent, and a fresh post is the loss direction.
+ */
+
+/**
+ * What the model reads when an edit fails AMBIGUOUSLY: the platform did not answer, so the edit may or may not be in the room.
+ * It must not steer to a new `reply` — if the edit did land, a fresh post puts the correction in the room twice.
+ */
+export function ambiguousEditNote(platform: string): string {
+  const where = platform && platform.length > 0 ? platform : "the surface";
+  return (
+    `The edit was sent but ${where} did not confirm it, so the message may or may not have changed. ` +
+    "Do NOT post a new reply about it — if the edit did land, a fresh post says the same thing twice. " +
+    "Call `edit_reply` again with the same message id if the correction matters; repeating an edit is safe."
+  );
+}
+
+/**
+ * The model-facing copy for a refused edit. It names NO other message and no other conversation: a refusal must not become a probe that tells the model which ids exist.
+ * The recovery is a repost that EXPLAINS ITSELF, so the room is never left with a stale line and a corrected sibling and no way to tell which is current. The `no-edit-arm` copy names the surface deliberately — the tool mounts everywhere and refuses here rather than vanishing, so a model can tell "this surface cannot edit" from "editing does not exist".
+ */
+export function editRefusalMessage(reason: string, platform?: string): string {
+  if (reason === EDIT_NO_ARM_REFUSAL_REASON) {
+    const where = platform && platform.length > 0 ? platform : "this surface";
+    return (
+      `edit_reply can't edit a message on ${where} — that surface has no API for editing the agent's own posts, so nothing here can be edited. ` +
+      `Post a new \`reply\` with the correction instead, and say in it that it replaces the earlier message and that ${where} cannot edit a posted message. ` +
+      "Otherwise the room is left with two versions and no way to tell which one is current."
+    );
+  }
+  return (
+    "edit_reply refused: that message id is not one of your own recent posts in this conversation. " +
+    "You can only edit a message YOU posted here with `reply`, and only for a few hours after posting. " +
+    "Post a new `reply` with the correction instead, and say in it that it replaces the earlier message and that the original could not be edited. " +
+    "Otherwise the room is left with two versions and no way to tell which one is current."
+  );
+}
+
+/** Write the `reply.edit.refused` row — best-effort, never throws, taint-clean (reason + route + ids,
+ *  never the message text and never the model-supplied id, which is attacker-influencable input). */
+export async function auditReplyEditRefused(
+  audit: ReplyAudit | undefined,
+  reason: string,
+  status?: number,
+  failure?: PlatformFailureClass,
+): Promise<void> {
+  if (!audit) return;
+  await appendAudit({
+    org: audit.org,
+    platform: audit.platform,
+    workspace: audit.workspace,
+    surface: audit.surface,
+    principalId: audit.principalId,
+    action: "reply.edit.refused",
+    detail: {
+      reason,
+      route: audit.route,
+      ...(status !== undefined ? { status } : {}),
+      // OPE-802 — the CLASS the host acted on, on the platform-error row only. An operator counting
+      // ambiguous failures is counting the turns that were allowed to end without a correction.
+      ...(failure !== undefined ? { failure } : {}),
+      ...(audit.wakeId ? { wakeId: audit.wakeId.slice(0, 200) } : {}),
+      ...(audit.sessionId ? { sessionId: audit.sessionId } : {}),
+    },
+  }).catch(() => undefined);
+}
+
+/** Write the canonical `reply.edit` row — the same attribution discipline as `reply.post`
+ *  (channels/reply-post.ts `auditReplyPost`): org/workspace/surface/principal from the caller's
+ *  {@link ReplyAudit}, and a taint-clean detail of id / platform / chars / route.
+ *  🔴 The `platform` COLUMN follows that discipline too: it names the SURFACE the edit landed on —
+ *  the `platform` ARGUMENT — never the route that carried it, so "how many messages did this
+ *  deployment rewrite on Linear" is one platform-filtered count over both `reply.post` and this row.
+ *  `reply.edit.refused` above is told no surface, because nothing landed, so it keeps the turn's own
+ *  partition like every other host-verdict row on this plane. */
+async function auditReplyEdit(audit: ReplyAudit | undefined, id: string, platform: string, chars: number): Promise<void> {
+  if (!audit) return;
+  await appendAudit({
+    org: audit.org,
+    platform,
+    workspace: audit.workspace,
+    surface: audit.surface,
+    principalId: audit.principalId,
+    action: "reply.edit",
+    detail: {
+      id,
+      platform,
+      chars,
+      route: audit.route,
+      ...(audit.creatorId ? { creatorId: audit.creatorId } : {}),
+      ...(audit.wakeId ? { wakeId: audit.wakeId } : {}),
+      ...(audit.sessionId ? { sessionId: audit.sessionId } : {}),
+    },
+  }).catch(() => undefined);
+}
+
+/**
+ * Rewrite `messageId` at `locus` to `text`. Returns nothing — an edit produces no new id.
+ * ORDER IS LOAD-BEARING: arm check, then OWNERSHIP, then dispatch, then audit. The ownership read happens before any byte leaves, the success row is written after the platform confirms, and every refusal is audited here and then thrown as a plain, token-free Error carrying {@link editRefusalMessage}'s copy.
+ */
+export async function editPostedMessage(
+  locus: EditLocus,
+  messageId: string,
+  text: string,
+  audit: ReplyAudit,
+  ledgerDeps: OwnPostLedgerDeps = {},
+): Promise<void> {
+  // OPE-916: an edit can carry the same memory-citation leak a post can (the model's own text,
+  // rewritten in place) — same truncation, same reason, applied before any fence or dispatch.
+  // OPE-1608: and the same connector footer, for a plainer reason — an edit REPLACES the body, so a
+  // door that skipped it would strip the footer off the reply that earned it and make the whole
+  // feature read as a rendering glitch. The footer is re-derived from the turn's ledger rather than
+  // parsed back out of the old text, so an edit made after further reads names those reads too.
+  // The cost of re-deriving, stated: the ledger is TURN-stamped, so an edit on a LATER turn reads
+  // empty and drops the footer the original post earned. That is the module's stated safe direction —
+  // it under-reports rather than asserting a source it cannot see — not a case anyone has fixed.
+  const claimGuard = guardMemoryClaims(truncateMemoryCitationPaths(text), audit);
+  // OPE-1876: and the no-approval claim, on the same body, at the same choke point — a door that
+  // struck one and posted the other would read as a rendering glitch.
+  const approvalGuard = guardApprovalClaims(claimGuard.body, audit);
+  // OPE-2022: and the propose claim, on the same body, at the same choke point. A seat may not say
+  // it submitted a request the host never saw the propose plane make.
+  const requestGuard = guardRequestClaims(approvalGuard.body, audit);
+  const provenance = applyReplyProvenance(requestGuard.body, audit);
+  text = provenance.body;
+  const arm = postArm(locus.platform);
+  // Both host verdicts are DEFINITIVE by construction (OPE-802): they are decided before any byte
+  // leaves, so nothing changed at the platform and a fresh `reply` is the right remedy — which is
+  // what the refusal copy already tells the model.
+  if (!arm?.editMessage) {
+    await auditReplyEditRefused(audit, EDIT_NO_ARM_REFUSAL_REASON);
+    throw markNotApplied(new Error(editRefusalMessage(EDIT_NO_ARM_REFUSAL_REASON, locus.platform)));
+  }
+  if (!(await isOwnPost(audit.org, locus, messageId, ledgerDeps))) {
+    await auditReplyEditRefused(audit, EDIT_NOT_OWN_REFUSAL_REASON);
+    throw markNotApplied(new Error(editRefusalMessage(EDIT_NOT_OWN_REFUSAL_REASON)));
+  }
+  // LOCAL EVAL SPOOF — the shared exit (channels/egress-spoof.ts), the same seam the two post spines take.
+  // Placed AFTER the fences so a spoofed run still exercises the real refusal logic, and BEFORE the arm so no transport is reached with real credentials.
+  if (swallowRoomOp(`a ${locus.platform} edit (${text.length}c)`)) {
+    await auditReplyEdit(audit, messageId, locus.platform, text.length);
+    // The spoofed run writes the same pair of rows as a real one — an eval that scores from the log
+    // must not see a shape the deployed path never produces.
+    await auditReplyProvenance(audit, messageId, locus.platform, provenance.reads, provenance.shown);
+    await auditWithheldMemoryClaim(audit, locus.platform, claimGuard.withheld);
+    await auditWithheldApprovalClaim(audit, locus.platform, approvalGuard.withheld, approvalGuard.cause);
+    await auditWithheldRequestClaim(audit, locus.platform, requestGuard.withheld);
+    return;
+  }
+  // A PLATFORM REJECTION IS AUDITED TOO, so the trail has no silent hole: every call that reaches the transport leaves one row.
+  // The original error is re-thrown unchanged, so the model still reads the arm's own token-free copy.
+  try {
+    await arm.editMessage(locus, messageId, text);
+  } catch (err) {
+    await auditReplyEditRefused(audit, EDIT_PLATFORM_ERROR_REASON, platformFailureStatus(err), platformFailureClass(err));
+    throw err;
+  }
+  await auditReplyEdit(audit, messageId, locus.platform, text.length);
+  // OPE-1608: an edit re-states what the message drew on, so it writes its own provenance row. The
+  // rows are append-only and keyed by message id, so a reply edited twice leaves three rows that
+  // read in order — which is the record of a footer that CHANGED, not a duplicate.
+  await auditReplyProvenance(audit, messageId, locus.platform, provenance.reads, provenance.shown);
+  await auditWithheldMemoryClaim(audit, locus.platform, claimGuard.withheld);
+  await auditWithheldApprovalClaim(audit, locus.platform, approvalGuard.withheld, approvalGuard.cause);
+  await auditWithheldRequestClaim(audit, locus.platform, requestGuard.withheld);
+}