mercury-agent 0.18.2 → 0.20.0

package/examples/extensions/gws/index.ts

@@ -15,6 +15,8 @@ type ConnectionAuthType =
   | "credentials-file"
   | "custom";
 
+type ConnectionStatus = "connected" | "needs-reauth" | "broken" | "unknown";
+
 type MercuryExt = {
   cli(opts: { name: string; install: string }): void;
   permission(opts: { defaultRoles: string[] }): void;
@@ -27,6 +29,7 @@ type MercuryExt = {
     authType: ConnectionAuthType;
     credentialEnvVar?: string;
     scopes?: string[];
+    statusCheck?: () => Promise<{ status: ConnectionStatus; detail?: string }>;
   }): void;
   on(
     event: "before_container",
@@ -34,6 +37,7 @@ type MercuryExt = {
       event: { spaceId: string; callerId: string },
       ctx: {
         db: { getExtState(e: string, k: string): string | null };
+        log: { warn(msg: string, extra?: unknown): void };
         hasCallerPermission(
           spaceId: string,
           callerId: string,
@@ -55,6 +59,67 @@ const gwsEnv = {
 /** Path where credentials are materialized inside the inner container's own /tmp. */
 const CREDENTIALS_FILE = "/tmp/gws-credentials.json";
 
+/**
+ * The string fields google-auth-library needs on an ADC "authorized user"
+ * document, beyond `type`. `type` is checked separately so its absence can be
+ * named on its own — it is the field operators actually hit.
+ */
+const REQUIRED_CREDENTIAL_FIELDS = [
+  "client_id",
+  "client_secret",
+  "refresh_token",
+] as const;
+
+/**
+ * Describe what is wrong with a candidate credential, or `undefined` when it is
+ * a usable ADC "authorized user" document.
+ *
+ * A parse check is not enough, which is what this guard exists to fix. Google's
+ * `/token` response is valid JSON carrying a working `refresh_token`, but has no
+ * top-level `type`, so it sails through `JSON.parse` and then fails on *every*
+ * `gws` invocation with "the file doesn't contain the field 'type'" — from
+ * inside a conversation, where no operator sees it. `{}` passed too. Read the
+ * guard by asking what happens when a field is missing, and make absence deny.
+ */
+function credentialProblem(raw: string): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return "is not valid JSON";
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return "is not a JSON object";
+  }
+  const doc = parsed as Record<string, unknown>;
+  if (doc.type === undefined) {
+    return 'is missing the "type" field (expected "authorized_user"; note that "token_type" is a different field and does not satisfy it)';
+  }
+  if (doc.type !== "authorized_user") {
+    return `has type ${JSON.stringify(doc.type)} (expected "authorized_user")`;
+  }
+  const missing = REQUIRED_CREDENTIAL_FIELDS.filter(
+    (field) => typeof doc[field] !== "string" || doc[field] === "",
+  );
+  if (missing.length > 0) {
+    return `is missing or has empty ${missing.join(", ")}`;
+  }
+  return undefined;
+}
+
+/** Appended to every rejection so the log names the fix, not just the fault. */
+const CREDENTIAL_RECOVERY =
+  'Expected {"type":"authorized_user","client_id":...,"client_secret":...,"refresh_token":...}. ' +
+  "Regenerate with: gws auth login && gws auth export --unmasked";
+
+/**
+ * Spaces whose permission denial has already been logged this process. Bounded
+ * by the number of spaces on the host, and deliberately not persisted: one
+ * reminder per restart is what makes a misconfiguration findable without
+ * turning the routine case into per-message noise.
+ */
+const permissionDenialLogged = new Set<string>();
+
 export default function (mercury: MercuryExt) {
   // The gws CLI can only take refresh-token credentials from a file, so someone
   // has to materialize GWS_CREDENTIALS_JSON before the first command runs. The
@@ -81,11 +146,12 @@ export default function (mercury: MercuryExt) {
         "'if [ -n \"$GWS_CREDENTIALS_JSON\" ]; then' " +
         `'  c="\${GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE:-${CREDENTIALS_FILE}}"' ` +
         "'  t=\"$c.$$\"' " +
-        "'  (umask 077; printf %s \"$GWS_CREDENTIALS_JSON\" > \"$t\")' " +
+        '\'  (umask 077; printf %s "$GWS_CREDENTIALS_JSON" > "$t")\' ' +
         // Credentials changed (rotation, or a different caller in a reused
         // container) invalidates the cached access token alongside them.
-        "'  cmp -s \"$t\" \"$c\" 2>/dev/null || rm -f \"${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json\"' " +
-        "'  mv -f \"$t\" \"$c\"' " +
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: shell parameter expansion inside a single-quoted sh fragment — a template literal here would be the bug
+        '\'  cmp -s "$t" "$c" 2>/dev/null || rm -f "${GOOGLE_WORKSPACE_CLI_CONFIG_DIR:-$HOME/.config/gws}/token_cache.json"\' ' +
+        '\'  mv -f "$t" "$c"\' ' +
         "'  GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE=\"$c\"; export GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE' " +
         "'fi' " +
         "'exec /usr/local/bin/gws-real \"$@\"' " +
@@ -112,21 +178,73 @@ export default function (mercury: MercuryExt) {
       "https://www.googleapis.com/auth/spreadsheets",
       "https://www.googleapis.com/auth/userinfo.email",
     ],
+    // Without this, the connection reports "connected" on presence alone, so a
+    // credential the CLI cannot use still shows green on the dashboard and the
+    // only symptom is a failed tool call mid-conversation.
+    //
+    // Shape only. Validity — is the refresh token still live? — cannot be
+    // answered here: this probe runs on demand, when someone opens the
+    // dashboard, and a dead credential's whole problem is that nobody looks.
+    // That question belongs to the daily refresh-token exchange in
+    // src/core/connection-health.ts, which alerts an operator out of band.
+    // If a rule is added below, mirror it in `readGoogleCredential` there.
+    statusCheck: async () => {
+      const raw = process.env[gwsEnv.env.credentials];
+      // Match the runtime's own presence default so an unconfigured connection
+      // reads the same with or without this probe.
+      if (!raw) {
+        return {
+          status: "unknown",
+          detail: `${gwsEnv.env.credentials} is not set`,
+        };
+      }
+      const problem = credentialProblem(raw);
+      if (problem) {
+        return {
+          status: "broken",
+          detail: `${gwsEnv.env.credentials} ${problem}`,
+        };
+      }
+      return { status: "connected" };
+    },
   });
 
   // Inner containers don't share the outer container's volume — they mount host
   // filesystem paths. So we can't write a credentials file from this hook and
   // have the inner container see it. Instead, pass the target path via env var
   // and let the skill materialize the file from GWS_CREDENTIALS_JSON at runtime.
-  mercury.on("before_container", async () => {
+  mercury.on("before_container", async (event, ctx) => {
     const raw = process.env[gwsEnv.env.credentials];
     if (!raw) return undefined;
 
-    try {
-      JSON.parse(raw);
-    } catch {
+    // GWS_CREDENTIALS_JSON is delivered by THIS hook, not by mercury.env(), and
+    // the two paths are not gated alike: a declared env var is injected only for
+    // a caller holding the extension's permission, while a hook's returned env
+    // is merged in `emitBeforeContainer` and pushed straight onto the container's
+    // `-e` list with no RBAC in between. So `mercury.permission()` above gates
+    // the *skill*, not this credential — without the check here the refresh
+    // token (gmail.modify, drive, calendar, documents, spreadsheets) reaches
+    // every caller in every space. The permission name is the extension name.
+    if (!ctx.hasCallerPermission(event.spaceId, event.callerId, "gws")) {
+      // Silence here is the confusing failure: the skill is present in the
+      // container, the credentials are not, and every Google call fails with
+      // an auth error that names nothing. One line per space per process —
+      // this branch is the normal case in every space that does not use gws,
+      // so logging per message would drown the log. No callerId: it is a
+      // phone number / LID, and the space is what an operator acts on.
+      if (!permissionDenialLogged.has(event.spaceId)) {
+        permissionDenialLogged.add(event.spaceId);
+        ctx.log.warn(
+          `[gws.before_container] credentials withheld for space ${event.spaceId}: caller lacks the "gws" permission. If Google Workspace is meant to work there, add "gws" to the caller's role with \`mrctl permissions set <role> ...\` from that space.`,
+        );
+      }
+      return undefined;
+    }
+
+    const problem = credentialProblem(raw);
+    if (problem) {
       console.error(
-        `[gws.before_container] ${gwsEnv.env.credentials} is not valid JSON — skipping`,
+        `[gws.before_container] ${gwsEnv.env.credentials} ${problem} — skipping. ${CREDENTIAL_RECOVERY}`,
       );
       return undefined;
     }

package/examples/extensions/longview/hook.ts

@@ -148,6 +148,18 @@ export function resolveThreshold(raw: string | null): number {
 const SUMMARY_BLOCK =
   /^\s*\[longview:summary\]\r?\n?([\s\S]*?)\r?\n?\[\/longview:summary\][^\S\r\n]*\r?\n?/;
 
+/**
+ * A block the author opened, filled with one paragraph, and forgot to close:
+ * opener, a non-empty first line, then a blank line.
+ *
+ * The paragraph boundary is the whole point — "opener to end of text" would
+ * make the entire reply the summary. The capture is forced to start on a
+ * non-newline character so that an opener followed *immediately* by a blank
+ * line cannot slide forward and claim the article's first paragraph instead.
+ */
+const UNTERMINATED_BLOCK =
+  /^\s*\[longview:summary\][^\S\r\n]*\r?\n([^\r\n][\s\S]*?)\r?\n[^\S\r\n]*\r?\n/;
+
 /** The opening marker on its own, used to recognise a truncated generation. */
 const OPENS_BLOCK = /^\s*\[longview:summary\]/;
 
@@ -177,6 +189,28 @@ export interface AuthorSummary {
   rest: string;
   /** True when the body was over the cap and had to be cut. */
   truncated: boolean;
+  /**
+   * True when the closing marker was missing and the first paragraph was taken
+   * as the summary. The caller logs it: the author's intent was honoured, but
+   * the reply was malformed and that has to be visible.
+   */
+  unterminated: boolean;
+}
+
+/** Cap the body and assemble the result — shared by both block shapes. */
+function toAuthorSummary(
+  body: string,
+  rest: string,
+  maxChars: number,
+  unterminated: boolean,
+): AuthorSummary {
+  const truncated = [...body].length > maxChars;
+  return {
+    summary: truncated ? cutAtWordBoundary(body, maxChars) : body,
+    rest,
+    truncated,
+    unterminated,
+  };
 }
 
 /**
@@ -186,25 +220,39 @@ export interface AuthorSummary {
  * editorial standard, so no second model call is needed and nothing has to be
  * re-derived from the finished page. Returns `undefined` when there is no
  * block, which is every reply from every space that does not ask for one.
+ *
+ * A block whose closer never arrived is still the author's intent, so the
+ * closed shape is tried first and the unterminated one second. Only a reply
+ * with no blank line after the opener — a generation cut off mid-block — is
+ * left to `stripStrayMarkers`.
  */
 export function extractAuthorSummary(
   reply: string,
   maxChars: number,
 ): AuthorSummary | undefined {
   const match = SUMMARY_BLOCK.exec(reply);
-  if (!match) return undefined;
+  if (!match) {
+    const open = UNTERMINATED_BLOCK.exec(reply);
+    const paragraph = (open?.[1] ?? "").trim();
+    // No paragraph means nothing to send; falling through leaves the existing
+    // stray-marker path in charge, exactly as before this branch existed.
+    if (!open || !paragraph) return undefined;
+    return toAuthorSummary(
+      paragraph,
+      // There is no closer anywhere in the reply (one would have matched
+      // `SUMMARY_BLOCK`), but a second opener further down still has to go.
+      reply.slice(open[0].length).replace(STRAY_MARKER, ""),
+      maxChars,
+      true,
+    );
+  }
 
   // An empty block is malformed output, but it is still a block: returning
   // `undefined` here would leave the markers in the text that gets published.
   // The hook falls back to generating a blurb from what is left.
   const body = (match[1] ?? "").trim();
 
-  const truncated = [...body].length > maxChars;
-  return {
-    summary: truncated ? cutAtWordBoundary(body, maxChars) : body,
-    rest: reply.slice(match[0].length),
-    truncated,
-  };
+  return toAuthorSummary(body, reply.slice(match[0].length), maxChars, false);
 }
 
 // ---------------------------------------------------------------------------
@@ -291,7 +339,24 @@ export async function handleAfterContainer(
       maxChars,
     });
   }
+  if (author?.unterminated) {
+    // Honoured, not silent: the summary was recovered, but a reply that never
+    // closed its block is malformed output the author has to be able to see.
+    log.warn(
+      "longview: summary block was never closed; took its first paragraph as the summary",
+      { spaceId },
+    );
+  }
   const body = author ? author.rest : stripStrayMarkers(reply);
+  if (!author && body !== reply) {
+    // An opener with no blank line after it — a generation cut off mid-block.
+    // The markers came off, but nothing was recoverable, so the whole reply
+    // (summary paragraph included) is what gets measured and published.
+    log.warn(
+      "longview: reply opened a summary block and never closed it; markers stripped",
+      { spaceId },
+    );
+  }
 
   // Count code points: `threshold_chars` should mean characters a reader sees,
   // and Hebrew and emoji are the normal case for this extension.

package/examples/extensions/longview/index.ts

@@ -49,6 +49,7 @@ import { renderRecentWidget } from "./widget.js";
 const SUMMARIZE_PROMPT_PATH = join(import.meta.dir, "prompts", "summarize.md");
 
 export default function (mercury: {
+  // biome-ignore lint/suspicious/noExplicitAny: hand-written structural stand-in for MercuryExt so the extension loads without the host's types
   on(event: string, handler: (event: any, ctx: any) => Promise<any>): void;
   config(
     key: string,
@@ -58,6 +59,7 @@ export default function (mercury: {
       validate?: (v: string) => boolean;
     },
   ): void;
+  // biome-ignore lint/suspicious/noExplicitAny: same structural stand-in
   widget(def: { label: string; render: (ctx: any) => string }): void;
   store: {
     get(key: string): string | null;

package/examples/extensions/morning/README.md

@@ -41,22 +41,23 @@ mrctl config set morning.environment sandbox      # or: production
 
 Only those two values are accepted. A typo is refused at set time.
 
-## Two things that will look like bugs
+## Why this connection is not marked `sensitive`
 
-**1. In a WhatsApp group, every turn is blocked until you enable sensitive
-connections.** This connection is declared `sensitive: true` because it can
-issue legally binding tax documents. In a group-linked space Mercury then
-refuses assistant turns unless the space opts in, and asks each caller to
-confirm:
+It issues legally binding tax documents, so `sensitive: true` looks right. It is
+deliberately omitted, because the runtime's sensitive guard is host-global and
+space-blind: one sensitive connection anywhere on the host puts *every*
+group-linked space behind a per-message confirmation, and the confirmation is
+consumed on each `yes`, so it repeats for every turn forever. A host with one
+accounting space and thirteen unrelated ones would pay that cost fourteen times
+over.
 
-```bash
-mrctl config set security.sensitive_connections_allowed true
-```
+Nothing load-bearing is lost. The credentials are `hostOnly` and reached only
+through the broker, so they never enter an agent container, and the verbs are
+`admin`-only. Restore the flag once the guard scopes per-space or per-extension.
 
-This is intended, not a fault. In a one-to-one conversation the guard does not
-apply.
+## One thing that will look like a bug
 
-**2. Issuing requires a preview first.** `document-create` refuses without an
+**Issuing requires a preview first.** `document-create` refuses without an
 `issueToken` returned by `document-preview` of the *same* document. The token is
 bound to the payload, the environment, the space and the caller, and works once.
 A retry after a successful create is refused rather than issuing twice.
@@ -93,7 +94,16 @@ mrctl capability morning <action> '<json>'
 ```
 
 `client-search`, `client-create`, `document-types`, `document-preview`,
-`document-create`, `document-search`, `document-links`.
+`document-create`, `document-search`, `document-links`, `expense-upload`,
+`expense-draft-search`.
+
+**`expense-upload` takes a path, never bytes.** The container names a file
+relative to its own space workspace (`inbox/receipt.pdf`); the host reads it and
+confines the path to `<spacesDir>/<spaceId>/`, resolving symlinks *before* the
+containment check — `inbox/` is written by a lower-trust boundary, so a symlink
+there pointing at the host's `.env` is the attack the guard exists for. A
+refused path returns one generic message and logs the detail host-side at WARN;
+telling the container why would make the guard a filesystem oracle.
 
 Full request shapes and the issue flow are in `skill/SKILL.md`; enums and the
 240-row error table are in `skill/references/`.
@@ -102,8 +112,9 @@ Full request shapes and the issue flow are in `skill/SKILL.md`; enums and the
 
 | Area | Why |
 |---|---|
-| Expenses, receipt upload | `POST /expenses` requires an `accountingClassification`, and the "Get Accounting Classifications" endpoint its schema references is absent from the 53 published paths. Also, an uploaded file always becomes a *draft* and there is no API to approve a draft. |
-| Webhooks (`payment/received`, `document/created`) | Extensions cannot register HTTP routes. Needs a core route or a polling job. |
+| Creating an expense from typed-in details (`POST /expenses`) | Requires an `accountingClassification`, and the "Get Accounting Classifications" endpoint its schema references is still absent from the published paths (re-verified 2026-09-06). Classifying inline would mean guessing a tax category on the user's behalf. Receipt **upload** sidesteps this entirely and is implemented — it creates a draft Morning parses itself, which a human approves in Morning's UI. |
+| Editing, closing or deleting an expense | Reading and creating drafts is the chore; mutating existing expenses is a larger trust decision. |
+| Webhooks (`payment/received`, `document/created`, `expense-draft/parsed`) | Extensions cannot register HTTP routes. This is why `expense-upload` cannot report whether a draft was ultimately parsed or declined — poll `expense-draft-search` instead. |
 | Payments API, credit-card tokens | Moving money is a larger trust decision than issuing a document. |
 | Partners API | For multi-business accountants; this is scoped to one business per key set. |
 

package/examples/extensions/morning/index.ts

@@ -12,6 +12,7 @@
  * without an accounting-classification source.
  */
 
+import { isAbsolute, join } from "node:path";
 import { runAction } from "./lib/morning.js";
 import { authErrorKey } from "./lib/token.js";
 
@@ -43,6 +44,9 @@ type ExtCtx = {
     listExtState(e: string): Array<{ key: string; value: string }>;
   };
   getConfig(spaceId: string, key: string): string | null;
+  /** Structural subset of `AppConfig` — only what this extension reads. */
+  config: { spacesDir: string };
+  log: { warn(message: string, meta?: Record<string, unknown>): void };
 };
 
 /** Structural match for `MercuryExtensionAPI` (avoid package subpath imports). */
@@ -131,12 +135,22 @@ export default function (mercury: MercuryExt) {
     // from the env var rather than from stored state makes the dashboard
     // correct before the first token is ever minted.
     credentialEnvVar: CLIENT_ID_VAR,
-    // This connection can issue tax documents. In a group-linked space the
-    // runtime then requires explicit admin enablement
-    // (security.sensitive_connections_allowed) plus per-caller confirmation —
-    // see src/core/runtime.ts. That operational cost is intended; the README
-    // says so, because the symptom otherwise reads as a broken extension.
-    sensitive: true,
+    // NOT `sensitive: true`, despite issuing tax documents — but no longer
+    // because the guard is broken. Both original objections are fixed as of
+    // 7bd050f: getActiveSensitiveConnectionName() now takes the caller's
+    // space and role and skips any connection that caller cannot reach, and a
+    // given confirmation is recorded in its own row so it sticks instead of
+    // re-asking on every message. Turning this on today would put admin
+    // callers in morning-permitted spaces behind a one-time confirmation, and
+    // nothing else — which is a defensible thing to want.
+    //
+    // It stays off until that is decided deliberately, because the
+    // load-bearing controls are elsewhere and already hold: the credentials
+    // are hostOnly and brokered (rung 4), so they never enter a container, and
+    // mercury.permission({defaultRoles:["admin"]}) keeps the verbs admin-only.
+    // The confirmation would add a prompt, not a boundary. Flipping this is a
+    // one-line change with a live-behaviour consequence, so make it on
+    // purpose.
     // Side-effect free and fast, per the ConnectionDef contract (5s timeout):
     // it reports from stored state and never mints a token or makes a request.
     statusCheck: async (ctx) => {
@@ -167,6 +181,15 @@ export default function (mercury: MercuryExt) {
       spaceId: req.spaceId,
       callerId: req.callerId,
       environment: ctx.getConfig(req.spaceId, ENVIRONMENT_KEY),
+      // `expense-upload` reads a file the container named, so it needs the
+      // workspace root to confine that path to the caller's own space.
+      // `resolveProjectPath` is not an exported subpath of the package; this
+      // mirrors it (src/config.ts) rather than widening the package API for
+      // two lines. Keep the two in step.
+      spacesDir: isAbsolute(ctx.config.spacesDir)
+        ? ctx.config.spacesDir
+        : join(process.cwd(), ctx.config.spacesDir),
+      logDenial: (message, detail) => ctx.log.warn(message, detail),
     });
   });
 

package/examples/extensions/morning/lib/hosts.ts

@@ -15,6 +15,14 @@
  *     credential sets. A production key cannot mint against sandbox.
  *  3. Sandbox's API host is a `greeninvoice.co.il` name while its token host is
  *     a `morning.dev` name. They do not share a domain; do not "tidy" them.
+ *
+ * A fourth, added 2026-09-06 and verified the same way: `/file-upload/v1/url`
+ * carries PATH-LEVEL `servers` in the spec that override the global ones, so it
+ * is not reachable under `apiBase` at all — hence `uploadBase`. That makes three
+ * distinct sandbox hosts (`api.sandbox.morning.dev`,
+ * `sandbox.d.greeninvoice.co.il`, `api.sandbox.d.greeninvoice.co.il`) which read
+ * like typos of one another and are not. `tests/morning-extension.test.ts`
+ * asserts all six as literals so a tidy-up cannot collapse them.
  */
 
 export const MORNING_EXT = "morning" as const;
@@ -27,16 +35,24 @@ export interface MorningHosts {
   readonly tokenUrl: string;
   /** API base, no trailing slash. Every non-token call is `${apiBase}/<path>`. */
   readonly apiBase: string;
+  /**
+   * Base for the expense file-upload endpoint only, no trailing slash. A
+   * different origin from `apiBase` and without the `/api/v1` prefix — see the
+   * fourth note above.
+   */
+  readonly uploadBase: string;
 }
 
 const HOSTS: Record<MorningEnvironment, MorningHosts> = {
   production: {
     tokenUrl: "https://api.morning.co/idp/v1/oauth/token",
     apiBase: "https://api.greeninvoice.co.il/api/v1",
+    uploadBase: "https://api.morning.co",
   },
   sandbox: {
     tokenUrl: "https://api.sandbox.morning.dev/idp/v1/oauth/token",
     apiBase: "https://sandbox.d.greeninvoice.co.il/api/v1",
+    uploadBase: "https://api.sandbox.d.greeninvoice.co.il",
   },
 };
 

package/examples/extensions/morning/lib/morning.ts

@@ -29,6 +29,7 @@ import {
   mintIssueToken,
 } from "./issue-token.js";
 import { getAccessToken, recordAuthError, type TokenStore } from "./token.js";
+import { expenseUpload as runExpenseUpload } from "./upload.js";
 
 export interface CapabilityResult {
   status?: number;
@@ -43,6 +44,14 @@ export interface ActionContext {
   spaceId: string;
   callerId: string;
   fetchImpl?: typeof fetch;
+  /**
+   * Root of all space workspaces, project-resolved by the caller. Only
+   * `expense-upload` needs it; absent means that verb refuses rather than
+   * guessing a root.
+   */
+  spacesDir?: string;
+  /** Host-side WARN channel for refusals that must not be detailed to the caller. */
+  logDenial?: (message: string, detail: Record<string, unknown>) => void;
 }
 
 type Body = Record<string, unknown>;
@@ -439,6 +448,73 @@ async function documentSearch(ctx: ActionContext, body: Body) {
   });
 }
 
+async function expenseDraftSearch(ctx: ActionContext, body: Body) {
+  const { page, pageSize } = paging(body);
+  return apiCall(ctx, "POST", "/expenses/drafts/search", {
+    ...pick(body, [
+      "fromDate",
+      "toDate",
+      "description",
+      "supplierId",
+      "supplierName",
+    ]),
+    page,
+    pageSize,
+  });
+}
+
+/**
+ * Upload a receipt as an expense draft.
+ *
+ * Two hops to two different hosts, so it cannot be expressed as one `apiCall`.
+ * The token PROVIDER is handed over rather than a token: the retry policy lives
+ * in `upload.ts`, which is the only place that knows step 1 is safe to repeat
+ * and step 2 is not.
+ */
+async function expenseUpload(ctx: ActionContext, body: Body) {
+  if (!ctx.spacesDir) {
+    return {
+      status: 503,
+      data: {
+        error:
+          "expense-upload is unavailable: the host did not supply a workspace root.",
+      },
+    };
+  }
+
+  return runExpenseUpload(
+    {
+      env: ctx.env,
+      spaceId: ctx.spaceId,
+      spacesDir: ctx.spacesDir,
+      ...(ctx.fetchImpl ? { fetchImpl: ctx.fetchImpl } : {}),
+      ...(ctx.logDenial ? { logDenial: ctx.logDenial } : {}),
+    },
+    body,
+    {
+      async getToken(forceRefresh: boolean) {
+        const result = await getAccessToken(ctx.db, ctx.env, {
+          forceRefresh,
+          ...(ctx.fetchImpl ? { fetchImpl: ctx.fetchImpl } : {}),
+        });
+        if (result.ok) return { ok: true as const, token: result.accessToken };
+        if (result.kind === "auth_failed") {
+          recordAuthError(ctx.db, ctx.env, result.message);
+        }
+        return {
+          ok: false as const,
+          result: {
+            status: result.kind === "not_configured" ? 503 : 502,
+            data: { error: result.message, kind: result.kind },
+          },
+        };
+      },
+      recordAuthError: (message: string) =>
+        recordAuthError(ctx.db, ctx.env, message),
+    },
+  );
+}
+
 async function documentLinks(ctx: ActionContext, body: Body) {
   const id = typeof body.id === "string" ? body.id.trim() : "";
   if (!id) return usage("document-links requires an id");
@@ -462,6 +538,8 @@ const ACTIONS: Record<
   "document-create": documentCreate,
   "document-search": documentSearch,
   "document-links": documentLinks,
+  "expense-upload": expenseUpload,
+  "expense-draft-search": expenseDraftSearch,
 };
 
 export const AVAILABLE_ACTIONS = Object.keys(ACTIONS);