@mulmoclaude/core 0.20.2 → 0.22.0

package/assets/helps/error-recovery.md

@@ -304,28 +304,41 @@ shipped builders produce, and asserts `handlePermission` comes back over the MCP
 ### Symptoms
 
 - The `google` tool (or a `google.calendar.*` remote command) fails with **"Google account not linked on this host"**.
-- Errors mentioning **client_secret**: "no client_secret_*.json found" or "multiple client_secret_*.json files found".
+- **"Google sign-in service unreachable"** or **"Google sign-in service returned HTTP …"**.
+- **"multiple client_secret_*.json files found"**.
 - **"Google Calendar API: HTTP 403"** with a hint about enabling the API.
 - **"could not obtain a Google access token"** (grant revoked).
 
 ### Cause
 
 The `google` tool runs against a Google account linked **locally on this machine** — a refresh
-token stored at `~/.config/mulmo/google-token.json` (mode 600), obtained through a desktop
-OAuth (loopback + PKCE) consent using the client credentials in `~/.secrets/client_secret_*.json`.
-This is independent of claude.ai Google connectors. Each failure names its missing piece.
+token stored at `~/.config/mulmo/google-token.json` (mode 600), obtained through a browser
+consent (loopback + PKCE). This is independent of claude.ai Google connectors.
+
+Two ways the link can be minted, and the tool picks automatically:
+
+- **Default**: the user just clicks link and consents. The mulmoserver broker applies the OAuth
+  client secret for the token exchange / renewal (Google requires one); it stores nothing —
+  the tokens live only on this machine. **The user needs no Google Cloud setup.**
+- **Own client** (advanced / self-hosters): if `~/.secrets/client_secret_*.json` exists, the
+  whole flow stays on this machine and the broker is never contacted.
 
 ### Fix
 
-- **Not linked / grant revoked** — ask the user to link (or re-link) the account: Settings →
-  Plugins → Google → "Link Google account", or run `yarn google:auth` in the repo. Then retry the
-  original call. Do NOT try to create or edit the token file yourself.
-- **No client secret** — the user must download the OAuth *desktop-app* client JSON from the
-  Google Cloud Console (APIs & Services → Credentials) and place it in `~/.secrets/` keeping the
-  `client_secret_*.json` filename (chmod 600).
-- **Multiple client secrets** — ask the user to keep exactly one `client_secret_*.json` in
-  `~/.secrets/`; the stored refresh token pairs with one OAuth client, so duplicates are refused
-  rather than guessed at.
-- **HTTP 403 from a Google API** — the API is not enabled for the user's Cloud project. Ask them
-  to enable it in the Cloud Console (APIs & Services → Library — e.g. "Google Calendar API"),
-  then retry. No re-link needed.
+- **Not linked / grant revoked** — ask the user to link (or re-link) the account from this app's
+  settings, then retry. Do NOT tell them to create a Google Cloud project, and do NOT try to
+  create or edit the token file yourself.
+- **Sign-in service unreachable / HTTP error** — the broker is down or the network is blocked.
+  It is only needed to link and to renew an expired access token; ask the user to retry shortly.
+  (A user with their own `~/.secrets/client_secret_*.json` never depends on it.)
+- **Multiple client secrets** — the user has several `client_secret_*.json` in `~/.secrets/`;
+  a stored refresh token pairs with exactly one OAuth client, so the choice is refused rather
+  than guessed at. Ask them to keep one — or remove all of them to use the default flow.
+- **HTTP 403 from a Google API** — the API is not enabled for the Cloud project behind the
+  client in use. With their own client, ask them to enable that API in the Cloud Console
+  (APIs & Services → Library — the error names it: "Google Calendar API", "Google Tasks API",
+  or "Google Drive API"), then retry — no re-link needed. On the default (broker) flow this
+  should not happen; report it rather than sending the user to the Console.
+- **Drive shows nothing / "I can't find the user's file"** — not an error. The app holds the
+  `drive.file` scope, so it can only ever see files IT created; the user's wider Drive is
+  invisible by design. Say so plainly instead of implying an empty Drive.

package/dist/google/apiClient.d.ts

@@ -0,0 +1,18 @@
+export declare const GOOGLE_API_TIMEOUT_MS: number;
+export declare const DEFAULT_LIST_MAX_RESULTS = 10;
+export declare const MAX_LIST_RESULTS = 50;
+/** 403 usually means the API is not enabled for the user's Cloud project —
+ *  name the API so the agent's recovery guidance can be specific. */
+export declare const googleApiError: (apiLabel: string, status: number, body: string) => Error;
+export interface GoogleRequestInit {
+    method?: string;
+    body?: string;
+    /** Overrides the default JSON content type (multipart upload, …). */
+    contentType?: string;
+    /** Response is not JSON (Drive media download) — return the raw text. */
+    expectText?: boolean;
+}
+export declare function googleRequest(apiLabel: string, accessToken: string, url: string, init?: GoogleRequestInit): Promise<unknown>;
+export declare const stringField: (record: Record<string, unknown>, key: string) => string;
+export declare const asRecord: (value: unknown) => Record<string, unknown>;
+export declare const itemsOf: (value: unknown) => unknown[];

package/dist/google/broker.d.ts

@@ -0,0 +1,15 @@
+import { Credentials } from 'google-auth-library';
+/** `MULMO_GOOGLE_BROKER_URL` lets a fork / staging deploy point elsewhere
+ *  without a code change; unset means the shipped broker. */
+export declare const brokerBaseUrl: (override?: string | undefined) => string;
+export interface BrokerStartResponse {
+    authUrl: string;
+    state: string;
+}
+export declare function brokerStart(port: number, codeChallenge: string, baseUrl?: string): Promise<BrokerStartResponse>;
+export declare function brokerExchange(input: {
+    code: string;
+    state: string;
+    codeVerifier: string;
+}, baseUrl?: string): Promise<Credentials>;
+export declare function brokerRefresh(refreshToken: string, baseUrl?: string): Promise<Credentials>;

package/dist/google/calendar.d.ts

@@ -1,5 +1,3 @@
-export declare const DEFAULT_LIST_MAX_RESULTS = 10;
-export declare const MAX_LIST_RESULTS = 50;
 export interface CalendarEventInput {
     summary: string;
     startDateTime: string;
@@ -19,6 +17,8 @@ export interface CalendarEventSummary {
     status: string;
 }
 export declare const toEventSummary: (value: unknown) => CalendarEventSummary;
+/** Kept as a named export for the existing unit tests / callers; the shared
+ *  helper now carries the wording. */
 export declare const calendarApiError: (status: number, body: string) => Error;
 export declare function createCalendarEvent(accessToken: string, input: CalendarEventInput): Promise<CalendarEventSummary>;
 export declare function listCalendarEvents(accessToken: string, input?: ListEventsInput): Promise<CalendarEventSummary[]>;

package/dist/google/clientSecret.d.ts

@@ -2,9 +2,10 @@ export interface InstalledClientSecret {
     client_id: string;
     client_secret: string;
 }
-/** "ambiguous" (2+ files) is distinct from "missing" — the fixes differ
- *  (remove duplicates vs download credentials), so the UI must not conflate
- *  them. */
+/** `missing` is the ordinary case — the broker supplies the client, so no user
+ *  action is needed. `ambiguous` (2+ desktop clients) still needs a human:
+ *  a stored refresh token pairs with exactly one client_id, so picking for
+ *  them could silently break the link. */
 export type ClientSecretPresence = "found" | "missing" | "ambiguous";
 export declare function clientSecretPresence(home?: string): Promise<ClientSecretPresence>;
 export declare function findClientSecretPath(home?: string): Promise<string>;

package/dist/google/driveFile.d.ts

@@ -0,0 +1,31 @@
+export interface DriveFileSummary {
+    id: string;
+    name: string;
+    mimeType: string;
+    webViewLink: string;
+    modifiedTime: string;
+}
+export interface ListDriveFilesInput {
+    maxResults?: number;
+}
+export interface CreateDriveFileInput {
+    name: string;
+    content: string;
+    mimeType?: string;
+}
+export interface ReadDriveFileInput {
+    fileId: string;
+}
+export declare const toDriveFileSummary: (value: unknown) => DriveFileSummary;
+export declare const isTextMimeType: (mimeType: string) => boolean;
+export declare function listDriveFiles(accessToken: string, input?: ListDriveFilesInput): Promise<DriveFileSummary[]>;
+export declare const assertSafeMimeType: (mimeType: string) => string;
+export declare const buildMultipartBody: (metadata: Record<string, string>, content: string, mimeType: string, boundary: string) => string;
+/** A boundary that appears nowhere in the parts it delimits. */
+export declare const pickBoundary: (parts: string[], generate?: () => string) => string;
+export declare function createDriveFile(accessToken: string, input: CreateDriveFileInput): Promise<DriveFileSummary>;
+export declare function readDriveFile(accessToken: string, input: ReadDriveFileInput): Promise<{
+    file: DriveFileSummary;
+    content: string;
+}>;
+export declare function deleteDriveFile(accessToken: string, input: ReadDriveFileInput): Promise<void>;