@open-everywhere/core 0.1.0

package/agent/tools/permission_fit_report.ts

@@ -0,0 +1,190 @@
+// Permission homeostasis, the surfacing half: are this domain's grants still the right size, in both directions, read from the audit log. 🔴 It PROPOSES; it never actuates and it never gates. No config is written, no grant changes, no live verdict moves, and nothing is blocked or delayed by running it or by not running it — the only actuator is a reviewed config PR, and merge is the privilege gate.
+// Its whole output vocabulary is grants and counts with NO principal anywhere, which is what lets an UNATTENDED routine run the tightening scan. The scope gate is domain grain and only domain grain: resolving the caller's channel to a memory domain IS the gate, and it holds on a fire because there is no principal to require. `explain_permission` is the prospective, per-verb sibling; this one is retrospective and per-grant.
+
+import { defineTool } from "eve/tools";
+import { never } from "eve/tools/approval";
+import { z } from "zod";
+import { bundleConnectorNames } from "../access/bundle.js";
+import { getConfig } from "../access/config.js";
+import { resolveAccessFor } from "../access/request.js";
+import { resolveSkillDomainDetailed } from "../skills/domain-skills.js";
+import { reportDomainRefusalMessage } from "../spend/reporting.js";
+import { resolvePartition } from "../memory/partition.js";
+import { domainForChannel } from "../memory/domain.js";
+import { readAudit, type AuditEntry } from "../audit/audit.js";
+import { auditToolAction } from "../audit/tool-action.js";
+import {
+  MIN_TIGHTEN_OBSERVATIONS,
+  MIN_TIGHTEN_WINDOW_DAYS,
+  makeWindow,
+  permissionEvidence,
+  type DeclaredGrants,
+  type EvidenceRow,
+} from "../access/permission-evidence.js";
+import { proposePermissionChanges, renderPermissionProposals } from "../access/permission-proposal.js";
+import type { BindableContext } from "../identity/binding.js";
+import { getGitHubApp } from "../scm/provider.js";
+import { repoCapabilityRows, renderRepoCapabilityRows, repoOwner } from "../scm/capability-fit.js";
+
+/**
+ * The audit actions the two loops read. Narrow reads beat one unfiltered sweep: the store filters `action` server-side, so the process never holds rows it has no question for.
+ * `egress.denied` is the only TIER-CONDITIONAL one — those rows exist only where the proxy is ours — and reading an action that is always empty on one tier is what stops the egress section meaning two different things depending on where it runs. The two non-refusal actions are the ARRIVAL side of the empty-room refusal, without which the loop cannot see its own proposal being actioned.
+ */
+const EVIDENCE_ACTIONS = [
+  "aws.exec",
+  "aws.refused",
+  "connector.op",
+  "connector.refused",
+  "connector.unattended_lift",
+  "routine.permission_granted",
+  "approval.chain",
+  "egress.denied",
+] as const;
+
+/**
+ * Per-action row cap: generous enough that a busy month fits, bounded enough that a pathological window cannot pull an unbounded result set into a lambda.
+ * Truncation is REPORTED, never silent — a truncated window UNDER-counts usage, which biases the tightening loop toward proposing a cut on a grant that was in fact busy, and that is exactly the error a reader must be told about.
+ */
+const ROW_CAP = 4000;
+
+/** How many distinct repo OWNERS this report will read installation permissions for (OPE-1024).
+ *  One live GitHub call each, so the cap keeps a wide grant from turning a report into a fan-out.
+ *  Owners past the cap are simply absent from the join and report as "unreported". */
+const MAX_INSTALLATION_PROBES = 10;
+
+export default defineTool({
+  description:
+    "Report whether this domain's PERMISSION GRANTS still fit the work — in both directions, from the audit log. Widening: unattended runs that keep hitting refusals (an AWS allow-list refusal, an approval card nobody could answer, a host the egress firewall keeps blocking, a connector this scope was never granted). Tightening: grants nothing exercised in the window, and allow-lists far wider than what was actually run. Returns evidence counts plus concrete, reviewable config-change proposals. It proposes only: nothing is granted, revoked, gated or delayed by this — every proposal is a pull request a human merges. Use when asked \"do we still need all this access?\", \"why does this routine keep getting refused?\", or on a schedule as a standing permission review. For \"would tool X be allowed here right now?\" use explain_permission instead.",
+  inputSchema: z.object({
+    days: z.number().int().min(1).max(90).optional().describe(`Window length in days (default 30). Tightening proposals need at least ${MIN_TIGHTEN_WINDOW_DAYS} days; shorter windows report widening evidence only.`),
+    direction: z.enum(["both", "widen", "tighten"]).optional().describe("Which loop to report. Default \"both\"."),
+  }),
+  outputSchema: z.object({
+    domain: z.string(),
+    window: z.object({ since: z.string(), until: z.string(), days: z.number() }),
+    rowsConsidered: z.number(),
+    truncated: z.boolean().describe("A per-action row cap was hit — usage is UNDER-counted, so treat any tightening proposal as unproven and re-run over a shorter window."),
+    grantsExamined: z.number(),
+    proposals: z.array(
+      z.object({
+        id: z.string(),
+        direction: z.enum(["widen", "tighten"]),
+        subject: z.string(),
+        summary: z.string(),
+        evidence: z.array(z.string()),
+        diff: z.string().optional().describe("The proposed config change, rendered. Absent when the actuator is not a config-file diff — `remedy` then says what it is."),
+        remedy: z.string().optional(),
+      }),
+    ),
+    repoCapabilities: z
+      .array(z.object({ repo: z.string(), capability: z.string(), declared: z.boolean(), installationSupports: z.enum(["yes", "no", "unreported"]) }))
+      .describe("Per (repo, named capability set): whether this domain's binding already opted in, and whether the App installation can honour it. Proposal input — nothing here grants anything."),
+    report: z.string().describe("The whole thing as readable text — post this."),
+  }),
+  approval: never(),
+  async execute(input, ctx) {
+    const bindable = ctx as BindableContext;
+    const partition = resolvePartition(bindable);
+    const resolved = resolveSkillDomainDetailed(bindable);
+    if (resolved.domain === null) throw new Error(reportDomainRefusalMessage(resolved.reason));
+    const domain = resolved.domain;
+
+    const days = input.days ?? 30;
+    const window = makeWindow(days, new Date());
+
+    // `EffectiveAccess` reports the RESOLVED grant set but not which binding won — the resolver dedupes a grant across bundles and keeps no provenance — so the declaring bundle is recovered by name lookup over the loaded config.
+    // Where several bundles declare the same grant, the proposal names all of them and the reviewer picks.
+    const access = resolveAccessFor(bindable);
+    const effectiveArns = new Set(access.awsRoles.map((r) => r.roleArn));
+    const effectiveConnectors = new Set(access.connectors);
+    const bundles = getConfig().loadBundles();
+    const grants: DeclaredGrants[] = bundles
+      .map((b) => ({
+        bundle: b.name,
+        awsRoles: (b.awsRoles ?? [])
+          .filter((r) => effectiveArns.has(r.roleArn))
+          .map((r) => ({ roleArn: r.roleArn, allow: r.allow })),
+        // Slugs, not grants: the evidence join is "which connector did this bundle declare that
+        // this scope actually holds", and a contentOrigin declaration (OPE-339) says nothing about USE.
+        connectors: bundleConnectorNames(b).filter((c) => effectiveConnectors.has(c)),
+      }))
+      .filter((g) => g.awsRoles.length > 0 || g.connectors.length > 0);
+
+    // The evidence rows: org-scoped by the store, then domain-scoped in process.
+    const domains = getConfig().loadDomains();
+    const inThisDomain = (row: AuditEntry): boolean => {
+      const detailDomain = row.detail?.domain;
+      if (typeof detailDomain === "string" && detailDomain.length > 0) return detailDomain === domain;
+      if (row.surface === undefined) return false;
+      return domainForChannel(`${row.platform}/${row.workspace}/${row.surface}`, domains)?.name === domain;
+    };
+
+    let truncated = false;
+    const rows: EvidenceRow[] = [];
+    for (const action of EVIDENCE_ACTIONS) {
+      const page = await readAudit({ org: partition.org, action, since: window.since, limit: ROW_CAP });
+      if (page.length >= ROW_CAP) truncated = true;
+      for (const row of page) if (inThisDomain(row)) rows.push({ ts: row.ts, action: row.action, detail: row.detail });
+    }
+
+    // The one implementation point for "can the App installation honour an expansion?". There is no deploy gate and no boot check by design — the mint-time 403 and its audit row are the always-on backstop for drift, and answering here keeps the question inside a concrete config-change ask.
+    // Fail-soft throughout: an owner that cannot be read reports "unreported", never a refusal, and this section never gates the rest of the report.
+    const app = getGitHubApp();
+    const owners = [...new Set(access.repos.map(repoOwner).filter((o) => o !== ""))].slice(0, MAX_INSTALLATION_PROBES);
+    const grantedByOwner: Record<string, Readonly<Record<string, string>> | undefined> = {};
+    const installationIdByOwner: Record<string, string | undefined> = {};
+    for (const owner of owners) {
+      grantedByOwner[owner] = app ? await app.installationPermissions(owner).catch(() => undefined) : undefined;
+      installationIdByOwner[owner] = app?.installationFor(owner);
+    }
+    const capabilityRows = repoCapabilityRows(access.repos, access.repoCapabilities, grantedByOwner);
+
+    const evidence = permissionEvidence(rows, grants, window);
+    const proposals = proposePermissionChanges(evidence, input.direction ?? "both");
+    let report = renderPermissionProposals(evidence, proposals);
+    report += `\n\n## GitHub repo capability sets\n${renderRepoCapabilityRows(capabilityRows, installationIdByOwner).join("\n")}`;
+    if (truncated) {
+      report = `⚠ Row cap (${ROW_CAP}/action) hit — usage is UNDER-counted in this window, so tightening proposals are unproven. Re-run with a shorter \`days\`.\n\n${report}`;
+    }
+    if (!truncated && evidence.activity.awsExec < MIN_TIGHTEN_OBSERVATIONS && evidence.usage.some((u) => u.kind === "aws-role")) {
+      report += `\n\n(AWS grants were not evaluated for tightening: ${evidence.activity.awsExec} execution(s) in the window is under the ${MIN_TIGHTEN_OBSERVATIONS}-row floor — an unused grant is only evidence when something else was used.)`;
+    }
+
+    // A permission review is itself an action worth a row. Counts and the window only — the row carries no proposal text, because the proposals are reproducible from the evidence and the audit log is not a place to park prose.
+    // `explain_permission` writes NO row for the opposite and equally deliberate reason: it is a what-if, and this is a review that happened.
+    await auditToolAction(bindable, "permission.fit_report", {
+      domain,
+      days,
+      direction: input.direction ?? "both",
+      rowsConsidered: evidence.rowsConsidered,
+      grantsExamined: evidence.usage.length,
+      widen: proposals.filter((p) => p.direction === "widen").length,
+      tighten: proposals.filter((p) => p.direction === "tighten").length,
+      ...(truncated ? { truncated: true } : {}),
+    });
+
+    return {
+      domain,
+      window: { since: window.since, until: window.until, days: window.days },
+      rowsConsidered: evidence.rowsConsidered,
+      truncated,
+      grantsExamined: evidence.usage.length,
+      repoCapabilities: capabilityRows.map((r) => ({
+        repo: r.repo,
+        capability: r.capability,
+        declared: r.declared,
+        installationSupports: (!r.fit.reported ? "unreported" : r.fit.ok ? "yes" : "no") as "yes" | "no" | "unreported",
+      })),
+      proposals: proposals.map((p) => ({
+        id: p.id,
+        direction: p.direction,
+        subject: p.subject,
+        summary: p.summary,
+        evidence: [...p.evidence],
+        ...(p.diff !== undefined ? { diff: p.diff.text } : {}),
+        ...(p.remedy !== undefined ? { remedy: p.remedy } : {}),
+      })),
+      report,
+    };
+  },
+});

package/agent/tools/post_file.ts

@@ -0,0 +1,416 @@
+// post_file delivers workspace FILES into the current surface's active conversation, dispatching on the bound platform: Slack, Discord and Notion post for real, anything else fails loud.
+// The only source shape is a sandbox-relative path, confined to the workspace root, and the post target always comes off the SurfaceBinding — never off tool input. There is deliberately no URL arm.
+
+import { defineTool } from "eve/tools";
+import { windowGated } from "../access/window-gated.js";
+import type { Approval } from "eve/tools/approval";
+import { z } from "zod";
+import { bindFrom, type BindableContext } from "../identity/binding.js";
+import { bridgeSlackReadCall } from "../channels/slack-bridge.js";
+import { surfaceMessageOps } from "../channels/surface-message-ops.js";
+import { auditToolAction } from "../audit/tool-action.js";
+import { hostHtmlArtifact, resolveBlobHosting } from "../blob/hosting.js";
+import { confineToWorkspacePath } from "./describe_image.js";
+import { postOnce, outboundKey } from "../operational/post-once.js";
+import { withDuplicateApprovalGuard } from "../access/approval-dedupe.js";
+import { surfaceContextFromAuth } from "../access/connector-scope.js";
+import { unattendedOf } from "../access/request.js";
+import { initiatorBoundResponsePolicy } from "../approvals/eve-response-policy.js";
+import type { SessionAuth } from "eve/context";
+
+const EXT_CONTENT_TYPES: Readonly<Record<string, string>> = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  pdf: "application/pdf",
+  txt: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  json: "application/json",
+  html: "text/html",
+  htm: "text/html",
+  xml: "application/xml",
+  zip: "application/zip",
+  mp4: "video/mp4",
+  webm: "video/webm",
+  mp3: "audio/mpeg",
+  wav: "audio/wav",
+};
+
+/** Infer a MIME type from a filename's extension; application/octet-stream when unknown. */
+export function inferContentType(filename: string): string {
+  const dot = filename.lastIndexOf(".");
+  if (dot < 0 || dot === filename.length - 1) return "application/octet-stream";
+  const ext = filename.slice(dot + 1).toLowerCase();
+  return EXT_CONTENT_TYPES[ext] ?? "application/octet-stream";
+}
+
+function isHtmlArtifact(contentType: string): boolean {
+  return contentType === "text/html";
+}
+
+/** The subset of the eve sandbox handle this tool needs (mirrors describe_image.ts). */
+interface SandboxHandle {
+  resolvePath(p: string): string;
+  readBinaryFile(a: { path: string }): PromiseLike<Uint8Array> | Uint8Array;
+}
+
+// The same 10 MB per-file ceiling describe_image.ts's sandbox-path arm uses — one guard constant across the tool surface rather than a bespoke number per tool.
+const MAX_FILE_BYTES = 10 * 1024 * 1024; // 10 MB per file
+
+async function resolveBytes(path: string, ctx: BindableContext): Promise<Uint8Array> {
+  const sandboxCtx = ctx as unknown as { getSandbox?: () => Promise<SandboxHandle> };
+  if (typeof sandboxCtx.getSandbox !== "function") {
+    throw new Error("post_file: no workspace is bound to this seat — a file can only be posted from a session with a sandbox.");
+  }
+  let sb: SandboxHandle;
+  try {
+    sb = await sandboxCtx.getSandbox();
+  } catch (err) {
+    throw new Error(`post_file: could not open the workspace to read "${path}" — ${err instanceof Error ? err.message : String(err)}.`);
+  }
+  const confined = confineToWorkspacePath(sb, path);
+  let bytes: Uint8Array;
+  try {
+    bytes = new Uint8Array(await Promise.resolve(sb.readBinaryFile({ path: confined })));
+  } catch (err) {
+    throw new Error(`post_file: could not read the workspace file at "${path}" — ${err instanceof Error ? err.message : String(err)}.`);
+  }
+  if (bytes.byteLength > MAX_FILE_BYTES) {
+    throw new Error(`post_file: "${path}" is too large (${bytes.byteLength} bytes; max ${MAX_FILE_BYTES}).`);
+  }
+  return bytes;
+}
+
+/** One fully-resolved file ready to hand to a surface poster. */
+interface ResolvedFile {
+  readonly bytes: Uint8Array;
+  readonly filename: string;
+  readonly contentType: string;
+  readonly caption?: string;
+}
+
+// Returns the posted message's `ts` when chat.postMessage names one, and undefined on any response shape that does not — never an invented id.
+async function postTextToSlack(ctx: BindableContext, text: string): Promise<string | undefined> {
+  const binding = bindFrom(ctx);
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  if (!channelId) {
+    throw new Error("post_file: couldn't resolve this Slack channel's id — try again from a real channel or DM.");
+  }
+  const body: Record<string, string> = { channel: channelId, text };
+  if (binding.threadTs) body.thread_ts = binding.threadTs;
+  const res = await bridgeSlackReadCall("chat.postMessage", body);
+  return typeof res.ts === "string" ? res.ts : undefined;
+}
+
+// Resolves the target channel off the binding and hands the text to the registered Discord transport, so core carries no vendor host literal.
+async function postTextToDiscord(ctx: BindableContext, text: string): Promise<string | undefined> {
+  const ops = surfaceMessageOps("discord");
+  if (!ops) {
+    throw new Error("post_file: Discord message transport is not registered — the @open-everywhere/provider-discord bundle isn't wired.");
+  }
+  const binding = bindFrom(ctx);
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  if (!channelId) {
+    throw new Error("post_file: couldn't resolve this Discord channel's id — try again from a real channel or DM.");
+  }
+  return await ops.postText(channelId, text);
+}
+
+async function postLinkToSurface(
+  ctx: BindableContext,
+  platform: string,
+  urls: readonly string[],
+  comment: string | undefined,
+): Promise<string | undefined> {
+  const text = [comment, ...urls].filter((s): s is string => Boolean(s)).join("\n");
+  if (platform === "slack") return await postTextToSlack(ctx, text);
+  if (platform === "discord") return await postTextToDiscord(ctx, text);
+  return await postTextToNotion(ctx, text);
+}
+
+// Slack's three-step external upload: getUploadURLExternal per file, PUT the bytes, then one completeUploadExternal that posts them all as a single message in the thread.
+// That last response carries only the uploaded files, never the message `ts` the upload lands under, so this returns undefined rather than a guess.
+async function postFilesToSlack(ctx: BindableContext, files: readonly ResolvedFile[], comment: string | undefined): Promise<string | undefined> {
+  const binding = bindFrom(ctx);
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  if (!channelId) {
+    throw new Error("post_file: couldn't resolve this Slack channel's id — try again from a real channel or DM.");
+  }
+  const uploaded: Array<{ id: string; title: string }> = [];
+  for (const file of files) {
+    // HTML may reach here: the attach fallback (the org has not opted in to Blob) uploads the raw `.html` bytes on purpose. The hosted path never does.
+    const res = await bridgeSlackReadCall("files.getUploadURLExternal", { filename: file.filename, length: file.bytes.byteLength });
+    const uploadUrl = typeof res.upload_url === "string" ? res.upload_url : undefined;
+    const fileId = typeof res.file_id === "string" ? res.file_id : undefined;
+    if (!uploadUrl || !fileId) {
+      throw new Error("post_file: Slack files.getUploadURLExternal did not return an upload URL / file id.");
+    }
+    const put = await fetch(uploadUrl, {
+      method: "POST",
+      headers: { "content-type": file.contentType },
+      body: file.bytes,
+    });
+    if (!put.ok) throw new Error(`post_file: uploading "${file.filename}" to Slack failed (HTTP ${put.status}).`);
+    uploaded.push({ id: fileId, title: file.caption ?? file.filename });
+  }
+  const complete: Record<string, string> = {
+    files: JSON.stringify(uploaded),
+    channel_id: channelId,
+  };
+  if (binding.threadTs) complete.thread_ts = binding.threadTs;
+  if (comment) complete.initial_comment = comment;
+  await bridgeSlackReadCall("files.completeUploadExternal", complete);
+  return undefined; // see the function header — Slack's own response never names the message ts.
+}
+
+// The multipart create-message lives in the provider-discord bundle; this resolves the target channel off the binding and hands over the resolved bytes.
+async function postFilesToDiscord(ctx: BindableContext, files: readonly ResolvedFile[], comment: string | undefined): Promise<string | undefined> {
+  const ops = surfaceMessageOps("discord");
+  if (!ops) {
+    throw new Error("post_file: Discord message transport is not registered — the @open-everywhere/provider-discord bundle isn't wired.");
+  }
+  // `postFiles` is an OPTIONAL op on a surface transport, so this checks the op's own presence rather than assuming it from the registry lookup above.
+  if (!ops.postFiles) {
+    throw new Error("post_file: Discord message transport has no file-upload op registered.");
+  }
+  const binding = bindFrom(ctx);
+  const channelId = typeof binding.target?.channelId === "string" ? binding.target.channelId : undefined;
+  if (!channelId) {
+    throw new Error("post_file: couldn't resolve this Discord channel's id — try again from a real channel or DM.");
+  }
+  return await ops.postFiles(channelId, files, comment);
+}
+
+// Notion's binding does NOT set `target.channelId` — a Notion turn's `target` is the reply address, a different grain from the stop registry's conversation key.
+// That key rides `binding.anchorChannelId`, which is what the Notion transport expects as its `channelId`; reading `target.channelId` here would always resolve undefined.
+function notionPageChannelId(ctx: BindableContext): string {
+  const binding = bindFrom(ctx);
+  const channelId = typeof binding.anchorChannelId === "string" && binding.anchorChannelId.length > 0 ? binding.anchorChannelId : undefined;
+  if (!channelId) {
+    throw new Error("post_file: couldn't resolve this Notion page's address — try again from a real page comment.");
+  }
+  return channelId;
+}
+
+async function postFilesToNotion(ctx: BindableContext, files: readonly ResolvedFile[], comment: string | undefined): Promise<string | undefined> {
+  const ops = surfaceMessageOps("notion");
+  if (!ops) {
+    throw new Error("post_file: Notion message transport is not registered — the @open-everywhere/provider-notion bundle isn't wired.");
+  }
+  if (!ops.postFiles) {
+    throw new Error("post_file: Notion message transport has no file-upload op registered.");
+  }
+  return await ops.postFiles(notionPageChannelId(ctx), files, comment);
+}
+
+async function postTextToNotion(ctx: BindableContext, text: string): Promise<string | undefined> {
+  const ops = surfaceMessageOps("notion");
+  if (!ops) {
+    throw new Error("post_file: Notion message transport is not registered — the @open-everywhere/provider-notion bundle isn't wired.");
+  }
+  return await ops.postText(notionPageChannelId(ctx), text);
+}
+
+const MAX_FILES = 10;
+
+// Notion's own per-comment attachment cap, COPIED rather than imported — core never depends on a provider package, only the reverse.
+// Checked up front in execute() so a Notion turn fails loud on file count before a single byte is resolved.
+const NOTION_MAX_POST_FILE_ATTACHMENTS = 3;
+
+const inputSchema = z.object({
+  files: z
+    .array(
+      z.object({
+        source: z
+          .object({ path: z.string().min(1) })
+          .describe("A file path in THIS session's workspace/sandbox (e.g. a bash-written artifact or an agent-browser screenshot). Read via the bound sandbox; confined to the workspace root; fails closed on a seat with no sandbox."),
+        filename: z.string().min(1).describe("The name the file is posted under (its extension drives contentType inference)."),
+        contentType: z.string().min(1).optional().describe("MIME type; inferred from the filename when omitted."),
+        caption: z.string().min(1).optional().describe("Optional per-file caption/title."),
+      }),
+    )
+    .min(1)
+    .max(MAX_FILES)
+    .describe("One or more files to post (max 10), each up to 10 MB."),
+  comment: z.string().min(1).optional().describe("Optional text posted alongside the files."),
+});
+type PostFileInput = z.infer<typeof inputSchema>;
+
+function inputFileIsHtml(f: PostFileInput["files"][number]): boolean {
+  return isHtmlArtifact(f.contentType ?? inferContentType(f.filename));
+}
+
+// An unattended publish is REFUSED, never parked: eve suspends the run on an approval card and nobody is there to click it on a routine fire. There is no lift arm because no standing-permission row names this tool.
+// Fail-soft on an unreadable bag: a surface that will not resolve answers "attended", so the card is still raised — standing down grants nothing.
+const UNATTENDED_PUBLISH_REFUSAL =
+  "post_file: publishing an HTML artifact to a public URL needs approval, and nobody is attending this run. " +
+  "An unattended run cannot wait on an approval card, and no standing permission covers this tool. " +
+  "Ask a person to publish it, or post the file without Blob hosting so it attaches instead. Nothing was published.";
+
+/**
+ * Attendedness is derived through `unattendedOf` and nothing else — the spelling `lint:principal-gate` rule 5 pins. Reading `binding.principalId` here would answer "a human is present" for every fire.
+ * An ApprovalContext is not bindable as it stands, so `surfaceContextFromAuth` resolves one; every unreadable input fails soft to "attended".
+ */
+async function publishIsUnattended(auth: unknown): Promise<boolean> {
+  if (auth === undefined || auth === null) return false;
+  const ctx = await surfaceContextFromAuth(auth as SessionAuth).catch(() => null);
+  if (ctx === null) return false;
+  try {
+    return unattendedOf(ctx);
+  } catch {
+    return false; // an unbindable surface — stand down, and the card still stands
+  }
+}
+
+// Input-aware: user approval only when the input carries an HTML artifact AND the org has opted in to Blob hosting — exactly the calls that will publish. `resolveBlobHosting` is fail-closed, so an unconfigured org stays ungated.
+// The attendedness read runs LAST, on the publish arm only, so an ungated call pays for no resolve and gains no new way to fail.
+const approvalPolicy: Approval<PostFileInput> = async (approvalCtx) => {
+  const files = approvalCtx.toolInput?.files ?? [];
+  const willPublish = resolveBlobHosting().enabled && files.some(inputFileIsHtml);
+  if (!willPublish) return "not-applicable";
+  if (await publishIsUnattended(approvalCtx.session?.auth)) {
+    return { type: "denied", reason: UNATTENDED_PUBLISH_REFUSAL };
+  }
+  return "user-approval";
+};
+
+// The HTML sentence states THIS org's real Blob-hosting state. A conditional sentence made the model guess the branch, and gpt-6-luna renamed a page to `.txt` to dodge a publish that could not happen (OPE-2075).
+function htmlPagesSentence(hostingEnabled: boolean): string {
+  return hostingEnabled
+    ? "HTML pages: this org has opted in to Blob hosting, so an HTML page is published to a public URL. " +
+        "Each publish needs user approval."
+    : "HTML pages: this org has not opted in to Blob hosting. An HTML page is attached as a downloadable " +
+        "file, exactly like any other file. Nothing is ever published or made public. Keep the real " +
+        "filename and extension (`page.html`, `text/html`). Do not rename it to `.txt`.";
+}
+
+/** The full `post_file` description for an org with Blob hosting on or off. Exported for the test. */
+export function postFileDescription(hostingEnabled: boolean): string {
+  return (
+    "Post one or more FILES/artifacts (screenshots, images, docs, data) to the current conversation " +
+    "on this surface — the delivery channel for things a text reply can't carry. Give each file a " +
+    "`source: { path }` — a file in THIS session's workspace/sandbox (e.g. a bash-written artifact, " +
+    "or an agent-browser screenshot) — and a `filename`; `contentType` is inferred from the filename " +
+    "if omitted. Each file is capped at 10 MB. Add an optional `comment` to post alongside the files, " +
+    "and a per-file `caption`. Works on Slack, Discord and Notion today (Notion accepts at most 3 " +
+    "files per post — a comment's own vendor cap); on other surfaces it returns a clear " +
+    "'not supported here' error so you can fall back to a text reply. " +
+    htmlPagesSentence(hostingEnabled)
+  );
+}
+
+export default windowGated("post_file", defineTool({
+  // Read once at module load: the tool module loads after the app config is registered, and the reviewed config does not change at runtime.
+  description: postFileDescription(resolveBlobHosting().enabled),
+  inputSchema,
+  outputSchema: z.object({ posted: z.boolean(), count: z.number(), platform: z.string(), urls: z.array(z.string()).optional() }),
+  // Since eve 0.47.3 deleted the follow-up park, the withDuplicateApprovalGuard wrap is the ONLY thing closing a duplicate card, and only for a byte-identical re-proposal — a publish of different files still raises its own.
+  // The response policy binds the click to the session initiator; it can refuse a responder but never deny the request, and a `cancel` click bypasses it entirely.
+  approval: { request: withDuplicateApprovalGuard(approvalPolicy), response: initiatorBoundResponsePolicy<PostFileInput>() },
+  async execute(input, ctx) {
+    const platform = bindFrom(ctx as BindableContext).platform;
+    if (platform !== "slack" && platform !== "discord" && platform !== "notion") {
+      throw new Error(
+        `post_file: file posting is not supported on "${platform}" yet (supported: Slack, Discord, Notion). ` +
+          "Reply with text, or share a link to an already-hosted file instead.",
+      );
+    }
+    if (platform === "notion" && input.files.length > NOTION_MAX_POST_FILE_ATTACHMENTS) {
+      // Fail loud before any bytes are resolved or uploaded; the schema's own MAX_FILES is a cross-surface ceiling, not a Notion-specific one.
+      throw new Error(
+        `post_file: Notion accepts at most ${NOTION_MAX_POST_FILE_ATTACHMENTS} files per post; got ${input.files.length}. Split them across multiple posts.`,
+      );
+    }
+
+    // Resolve every source to bytes + a content type up front, so a bad source fails BEFORE we
+    // start posting (no half-posted batch).
+    const resolved: ResolvedFile[] = [];
+    for (const f of input.files) {
+      const contentType = f.contentType ?? inferContentType(f.filename);
+      const bytes = await resolveBytes(f.source.path, ctx as BindableContext);
+      resolved.push({ bytes, filename: f.filename, contentType, caption: f.caption });
+    }
+
+    const hosting = resolveBlobHosting();
+    const toAttach: ResolvedFile[] = [];
+    const hostedUrls: string[] = [];
+    for (const file of resolved) {
+      if (isHtmlArtifact(file.contentType) && hosting.enabled) {
+        // Opted in → publish. Fail LOUD on a write/validation error — never silently fall back
+        // to attach, which would hide a Blob misconfig behind a working-looking download.
+        hostedUrls.push(await hostHtmlArtifact(file, { publicPrefix: hosting.publicPrefix }));
+      } else {
+        toAttach.push(file);
+      }
+    }
+
+    // This execute is one eve step, so an interrupt after a post lands but before the step completes re-runs it on resume. postOnce keys on eve's replayed `callId` plus the content; attach and link posts take SEPARATE keys, because a crash between them must not suppress the second.
+    // The Blob publish is deliberately not wrapped (it is approval-gated), and postOnce fails open, so a dedupe-store outage still posts.
+    const binding = bindFrom(ctx as BindableContext);
+    // Notion's post-back address is `anchorChannelId` rather than `target.channelId`. This is dedupe-key material only, so an absent value makes the key coarser, never incorrect.
+    const channelId =
+      typeof binding.target?.channelId === "string"
+        ? binding.target.channelId
+        : typeof binding.anchorChannelId === "string"
+          ? binding.anchorChannelId
+          : undefined;
+    const callId = typeof (ctx as { callId?: unknown }).callId === "string" ? (ctx as { callId: string }).callId : undefined;
+
+    // `attachId` is the delivered message id, present only when the surface's own response names one — Discord and Notion do, Slack's completeUploadExternal does not.
+    let attachId: string | undefined;
+    if (toAttach.length > 0) {
+      attachId = await postOnce({
+        org: binding.org,
+        key: outboundKey({
+          surface: platform,
+          channel: channelId,
+          threadTs: binding.threadTs,
+          action: `${platform}.post_file.attach`,
+          stableId: callId,
+          payload: `${input.comment ?? ""}\x00${toAttach.map((f) => `${f.filename}:${f.contentType}:${f.bytes.byteLength}`).join(",")}`,
+        }),
+        run: async () => {
+          if (platform === "slack") return await postFilesToSlack(ctx as BindableContext, toAttach, input.comment);
+          if (platform === "discord") return await postFilesToDiscord(ctx as BindableContext, toAttach, input.comment);
+          return await postFilesToNotion(ctx as BindableContext, toAttach, input.comment);
+        },
+      });
+    }
+    // Post the hosted URL(s) as a text message. If there were ALSO attachments, the comment
+    // already rode with them, so don't repeat it on the link message. `linkId` is this message's
+    // own id (OPE-932) — both surfaces' text-post response names one.
+    let linkId: string | undefined;
+    if (hostedUrls.length > 0) {
+      linkId = await postOnce({
+        org: binding.org,
+        key: outboundKey({
+          surface: platform,
+          channel: channelId,
+          threadTs: binding.threadTs,
+          action: `${platform}.post_file.link`,
+          stableId: callId,
+          payload: `${toAttach.length > 0 ? "" : (input.comment ?? "")}\x00${hostedUrls.join(",")}`,
+        }),
+        run: () => postLinkToSurface(ctx as BindableContext, platform, hostedUrls, toAttach.length > 0 ? undefined : input.comment),
+      });
+    }
+
+    // Audit AFTER a successful post: what went where and how many were hosted versus attached, never the bytes, the token or the URL.
+    // A batch that posts both an attach message and a hosted-link message keeps only the attach id — one row cannot attest two independent posts, and the attach message is the one a driver polls for.
+    const deliveredId = attachId ?? linkId;
+    await auditToolAction(ctx, `${platform}.post_file`, {
+      count: resolved.length,
+      filenames: resolved.map((f) => f.filename),
+      hasComment: Boolean(input.comment),
+      hosted: hostedUrls.length,
+      attached: toAttach.length,
+      ...(deliveredId ? { id: deliveredId } : {}),
+    });
+    return { posted: true, count: resolved.length, platform, ...(hostedUrls.length > 0 ? { urls: hostedUrls } : {}) };
+  },
+}));