borgmcp 1.1.14 → 2.0.1

package/dist/auth.d.ts

@@ -1,103 +0,0 @@
-/**
- * Google OAuth 2.0 Authorization Code Flow with PKCE
- * For Desktop/CLI applications
- *
- * Flow:
- * 1. Generate PKCE code_verifier and code_challenge
- * 2. Start local HTTP server for callback
- * 3. Open browser to Google authorization URL
- * 4. User authorizes in browser
- * 5. Receive authorization code via localhost callback
- * 6. Exchange code for tokens
- * 7. Store tokens securely in OS keychain
- */
-import { type DeviceAuthConfig, type DeviceAuthDeps } from './device-auth.js';
-/**
- * Refresh-token-revoked / expired — the user must re-run `borg setup`
- * to recover. Anchored on Google's canonical signal: HTTP 400 + JSON
- * body `{"error": "invalid_grant", ...}` from the OAuth token
- * endpoint. Callers should `clearTokens()` on this class only —
- * preserving keychain state on the transient class.
- *
- * Constructor stores parsed `error` + `error_description` fields
- * only — never the request body (which contains the refresh_token)
- * or the raw response body verbatim (per drone-8 SR axis b on
- * token-material non-leakage in error messages).
- */
-export declare class RefreshTokenInvalidError extends Error {
-    readonly errorCode: string;
-    readonly errorDescription?: string | undefined;
-    constructor(errorCode: string, errorDescription?: string | undefined);
-}
-/**
- * Transient failure of the refresh path — network failure, Google
- * 5xx, malformed response, non-`invalid_grant` 4xx, etc. The
- * refresh_token in keychain is presumed still valid; callers MUST
- * NOT `clearTokens()` on this class.
- *
- * The pre-gh#34 implementation classified all refresh failures
- * uniformly and called `clearTokens()` unconditionally; a single
- * transient blip would destroy the durable session. This typed
- * class is the discrimination axis.
- */
-export declare class RefreshTransientError extends Error {
-    constructor(message: string);
-}
-/**
- * Decide whether to use the no-browser device-grant flow. An explicit
- * `--no-browser`/`--device` (surfaced as opts.noBrowser) wins; otherwise
- * auto-detect via isNoBrowserEnv (SSH session, container, headless Linux).
- */
-export declare function shouldUseDeviceFlow(opts?: {
-    noBrowser?: boolean;
-}): boolean;
-/**
- * Assemble the device-grant OAuth config from the environment. Enforces the
- * gh#557 ESCALATION-1 gate: a "TVs & Limited Input devices" client id must be
- * available (baked-in once the operator creates it, or via GOOGLE_DEVICE_CLIENT_ID).
- * Without one we fail with an actionable error instead of hitting Google with
- * the Desktop client, which rejects /device/code as invalid_client.
- */
-export declare function buildDeviceAuthConfig(env?: NodeJS.ProcessEnv): DeviceAuthConfig;
-/**
- * The RFC 8628 device-grant flow (no browser). Prints a verification URL +
- * user_code for the human to open on ANY device, polls Google until they
- * authorize, then stores tokens in the selected backend. Network deps are
- * injectable for tests; the device-poll state machine itself lives in
- * device-auth.ts (fully unit-tested).
- */
-export declare function authenticateWithDeviceFlow(deps?: DeviceAuthDeps, env?: NodeJS.ProcessEnv): Promise<void>;
-/**
- * Perform the complete OAuth flow, choosing the browser/loopback flow or the
- * no-browser device-grant flow based on the environment (gh#557). Stores
- * tokens in the selected backend on success.
- *
- * @param opts.noBrowser  force the device flow (`--no-browser`/`--device`);
- *                        when omitted, the environment is auto-detected.
- */
-export declare function authenticateWithGoogle(opts?: {
-    noBrowser?: boolean;
-}): Promise<void>;
-/**
- * Refresh the stored id_token, redeeming the refresh_token against the
- * OAuth client that ISSUED it (gh#691).
- *
- * A refresh_token can only be redeemed by its issuing client. The browser
- * flow issues tokens under the web client (GOOGLE_CLIENT_ID); the device
- * flow (`borg setup --no-browser`, gh#557) issues them under the device
- * client (buildDeviceAuthConfig). We don't persist which flow minted the
- * stored token, so try the web client first, then the device client.
- *
- * Before this fix the refresh hard-coded the web client, so every
- * device-flow user's silent refresh failed at id_token expiry — forcing a
- * full re-auth (which revokes the working refresh_token to force fresh
- * consent) on the next command. That was the friction in gh#691.
- *
- * Keychain safety: clear-on-revocation (RefreshTokenInvalidError, which
- * callers gate `clearTokens()` on) is surfaced ONLY when BOTH clients
- * reject the token with invalid_grant. Any inconclusive/transient outcome
- * on either attempt preserves the keychain for retry — a wrong-client
- * invalid_grant must not be mistaken for a genuine revocation.
- */
-export declare function refreshIdToken(refreshToken: string): Promise<void>;
-//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -1,39 +0,0 @@
-import{createServer as k}from"http";import{URL as w}from"url";import g from"crypto";import P from"open";import{storeIdToken as d,storeRefreshToken as f,getRefreshToken as p,isUsingKeychainBackend as O,migrateToFileBackendWithTokens as I}from"./config.js";import{cerr as t}from"./console-prefix.js";import{isNoBrowserEnv as A}from"./auth-env.js";import{requestDeviceCode as x,pollForDeviceToken as G}from"./device-auth.js";class L extends Error{errorCode;errorDescription;constructor(r,n){super(n?`Refresh token invalid (${r}): ${n}`:`Refresh token invalid (${r})`),this.errorCode=r,this.errorDescription=n,this.name="RefreshTokenInvalidError"}}class l extends Error{constructor(r){super(r),this.name="RefreshTransientError"}}const m="675073910799-41pbe12rfhqemidh64h09s4q3e0udpgp.apps.googleusercontent.com",_="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",S="675073910799-6qmi73v5106dj1v0l22j2qnkh5r3e8fq.apps.googleusercontent.com",$="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",N="https://accounts.google.com/o/oauth2/v2/auth",T="https://oauth2.googleapis.com/token",D="https://oauth2.googleapis.com/revoke",y=["openid","email","profile"],re=8e3,ne=9e3,E=300*1e3,v=E/6e4;function U(){const e=g.randomBytes(32).toString("base64url"),r=g.createHash("sha256").update(e).digest("base64url");return{verifier:e,challenge:r}}async function B(){return new Promise((e,r)=>{const n=k();n.listen(0,()=>{const o=n.address();if(o&&typeof o=="object"){const i=o.port;n.close(()=>e(i))}else n.close(()=>r(new Error("Failed to get assigned port")))}),n.on("error",r)})}async function F(){const e=await B(),r=new Promise((n,o)=>{const i=k((s,c)=>{const a=new w(s.url,`http://localhost:${e}`);if(a.pathname==="/callback"){const h=a.searchParams.get("code"),u=a.searchParams.get("error");if(u){c.writeHead(400,{"Content-Type":"text/html"}),c.end(`
-            <html>
-              <body>
-                <h1>\u25FC Authentication Failed</h1>
-                <p>Error: ${u}</p>
-                <p>You can close this window.</p>
-              </body>
-            </html>
-          `),i.close(),o(new Error(`OAuth error: ${u}`));return}if(h){c.writeHead(200,{"Content-Type":"text/html"}),c.end(`
-            <html>
-              <body>
-                <h1>\u25FC Authentication Successful!</h1>
-                <p>You can close this window and return to your terminal.</p>
-              </body>
-            </html>
-          `),i.close(),n(h);return}c.writeHead(400,{"Content-Type":"text/html"}),c.end(`
-          <html>
-            <body>
-              <h1>\u25FC Invalid Request</h1>
-              <p>Missing authorization code.</p>
-            </body>
-          </html>
-        `),i.close(),o(new Error("Missing authorization code"))}});i.listen(e,()=>{t(`Callback server listening on http://localhost:${e}`)}),setTimeout(()=>{i.close(),o(new Error(`Authentication timed out after ${v} minutes \u2014 no authorization received from the browser. Re-run \`borg setup\` and complete the Google sign-in in the page that opens.`))},E).unref()});return{port:e,codePromise:r}}async function M(e,r,n){const o=`http://localhost:${n}/callback`,i=await fetch(T,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({client_id:m,client_secret:_,code:e,code_verifier:r,grant_type:"authorization_code",redirect_uri:o})});if(!i.ok){const s=await i.text();throw new Error(`Failed to exchange code for tokens: ${s}`)}return await i.json()}async function b(e){try{await fetch(D,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:`token=${encodeURIComponent(e)}`})}catch{}}async function K(){t(`
-\u25FC Borg MCP Authentication`),t(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-`);const e=await p();e&&(t("Revoking previous refresh_token to force fresh consent..."),await b(e)),t("Generating PKCE challenge...");const r=U();t("Starting local callback server...");const{port:n,codePromise:o}=await F(),i=`http://localhost:${n}/callback`,s=new w(N);s.searchParams.set("client_id",m),s.searchParams.set("redirect_uri",i),s.searchParams.set("response_type","code"),s.searchParams.set("scope",y.join(" ")),s.searchParams.set("code_challenge",r.challenge),s.searchParams.set("code_challenge_method","S256"),s.searchParams.set("access_type","offline"),s.searchParams.set("prompt","consent select_account"),t(`
-\u{1F4F1} Opening browser for authorization...`),t("If browser does not open, visit:"),t(`${s.toString()}
-`);try{await P(s.toString())}catch(u){t(`Could not open a browser automatically: ${u?.message??"unknown"}`),t("Continue by opening the URL above manually.")}t(`Waiting for you to finish signing in (up to ${v} minutes)... this terminal continues automatically once you approve.`);const c=await o;t("Exchanging authorization code for tokens...");const a=await M(c,r.verifier,n),h=Date.now()+a.expires_in*1e3;await d(a.id_token,h),a.refresh_token?await f(a.refresh_token):(t(`
-\u26A0  No refresh_token returned by Google.`),t("   Your session will expire after ~1 hour and require"),t("   re-running `borg setup`. To enable auto-refresh:"),t("   1. Visit https://myaccount.google.com/permissions"),t('   2. Find "Borg MCP" and click "Remove access"'),t("   3. Re-run `borg setup`"),t(`   (Google will then issue a fresh refresh_token.)
-`)),t(`
-\u25FC Authentication successful!
-`)}function q(e){return e?.noBrowser??A()}function C(e=process.env){const r=e.GOOGLE_DEVICE_CLIENT_ID?.trim(),n=e.GOOGLE_DEVICE_CLIENT_SECRET?.trim()||void 0;let o,i;if(r?(o=r,i=n):(o=S,i=$||void 0),!o)throw new Error('No-browser (device-grant) auth needs a Google "TVs & Limited Input devices" OAuth client. Set GOOGLE_DEVICE_CLIENT_ID in the environment, or run `borg setup` on a machine with a browser. See docs/REMOTE_TERMINAL_AUTH.md.');return{clientId:o,clientSecret:i,scopes:y}}function H(e){return new Promise(r=>setTimeout(r,e))}async function V(e={fetch,sleep:H},r=process.env){t(`
-\u25FC Borg MCP Authentication (no-browser mode)`),t(`\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501
-`);const n=C(r),o=await p();o&&(t("Revoking previous refresh_token to force fresh consent..."),await b(o));const i=await x(n,e);t("To authorize Borg MCP on this machine:"),t(`  1. On any device with a browser, open:  ${i.verification_url}`),t(`  2. Enter this code:  ${i.user_code}
-`),t("Waiting for authorization (this page can be open on your phone or laptop)...");const s=await G(i,n,e),c=Date.now()+s.expires_in*1e3;await d(s.id_token,c),s.refresh_token?await f(s.refresh_token):(t(`
-\u26A0  No refresh_token returned by Google.`),t("   Your session will expire after ~1 hour and require re-running"),t("   `borg setup`. Re-consent at https://myaccount.google.com/permissions"),t(`   (remove "Borg MCP") then re-run setup to restore automatic token refresh.
-`)),t(`
-\u25FC Authentication successful!
-`)}async function oe(e){return q(e)?V():K()}async function R(e,r,n){const o={client_id:r,refresh_token:e,grant_type:"refresh_token"};n&&(o.client_secret=n);let i;try{i=await fetch(T,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams(o)})}catch(a){return{ok:!1,kind:"transient",error:new l(`Network failure during token refresh: ${a?.message??"unknown"}`)}}if(!i.ok){let a=null;try{a=await i.json()}catch{return{ok:!1,kind:"transient",error:new l(`Token refresh failed with HTTP ${i.status} (non-JSON body)`)}}return i.status===400&&a?.error==="invalid_grant"?{ok:!1,kind:"invalid",error:new L("invalid_grant",a.error_description)}:{ok:!1,kind:"transient",error:new l(`Token refresh failed with HTTP ${i.status}${a?.error?` (${a.error})`:""}`)}}let s;try{s=await i.json()}catch(a){return{ok:!1,kind:"transient",error:new l(`Token refresh response unparseable: ${a?.message??"unknown"}`)}}if(!s.id_token||typeof s.expires_in!="number")return{ok:!1,kind:"transient",error:new l("Token refresh response missing id_token or expires_in")};const c=Date.now()+s.expires_in*1e3;try{if(s.refresh_token){const a=await p();await f(s.refresh_token);try{await d(s.id_token,c)}catch(h){if(a)try{await f(a)}catch{}throw h}}else await d(s.id_token,c);return{ok:!0}}catch(a){return await z(s,c)?{ok:!0}:{ok:!1,kind:"transient",persistFailed:!0,error:new l(`Token refresh succeeded but saving it to the credential store failed (the keychain may be locked, or a background process can't write it): ${a?.message??"unknown"}`)}}}async function z(e,r){if(!e.id_token)return!1;let n=!1;try{if(!await O())return!1;const o=e.refresh_token??await p();if(!o)return!1;n=await I({idToken:e.id_token,expiresAt:r,refreshToken:o})}catch{return!1}return n?(W(),!0):!1}function W(){t(`
-\u26A0  Keychain write failed \u2014 migrated this session to the encrypted-file token store (~/.borg/credentials).`),t("   This is an AVAILABILITY fallback, NOT equivalent to the OS keychain."),t("   The file backend is obfuscation-grade: its key is derived from"),t("   hostname+username+platform (non-secret), so it is WEAKER at-rest than"),t("   the keychain \u2014 same-machine/root access can re-derive it and decrypt."),t("   To restore keychain storage, fix keychain write access and re-run `borg setup`.\n")}async function ie(e){const r=await R(e,m,_);if(r.ok)return;if(r.kind==="transient"&&r.persistFailed)throw r.error;const n=C(),o=await R(e,n.clientId,n.clientSecret);if(!o.ok)throw r.kind==="invalid"&&o.kind==="invalid"?o.error:r.kind==="transient"?r.error:o.error}export{L as RefreshTokenInvalidError,l as RefreshTransientError,V as authenticateWithDeviceFlow,oe as authenticateWithGoogle,C as buildDeviceAuthConfig,ie as refreshIdToken,q as shouldUseDeviceFlow};

package/dist/device-auth.d.ts

@@ -1,75 +0,0 @@
-/**
- * gh#557 — Google OAuth 2.0 Device Authorization Grant (RFC 8628).
- *
- * The no-browser counterpart to the loopback flow in auth.ts. Instead of
- * opening a browser and listening on localhost, the device flow:
- *   1. asks Google for a device_code + a short human-typable user_code,
- *   2. prints a verification URL + the user_code for the human to open on
- *      ANY device (their phone, a laptop with a browser), and
- *   3. polls Google's token endpoint until the human authorizes (or the
- *      code expires / is denied).
- *
- * This module is decoupled from the live Google client: `fetch`, `sleep`,
- * and `now` are injected, and the client_id / client_secret / endpoints
- * come from the caller. The live device flow needs a Google OAuth client
- * of type "TVs & Limited Input devices" (a separate GOOGLE_DEVICE_CLIENT_ID
- * — Desktop/loopback clients reject /device/code with invalid_client); the
- * wiring layer supplies those credentials. Everything here is unit-tested
- * against a mocked Google.
- */
-/**
- * Failure of the device-grant flow. `code` is Google's OAuth error code
- * where one exists (`access_denied`, `expired_token`, `invalid_client`,
- * `slow_down`, `authorization_pending`) or a synthetic code for
- * transport/shape failures (`device_code_request_failed`,
- * `device_token_request_failed`, `malformed_token_response`).
- *
- * Token material is never placed in the message — only Google's error
- * code + description, mirroring RefreshTokenInvalidError's discipline.
- */
-export declare class DeviceAuthError extends Error {
-    readonly code: string;
-    constructor(code: string, message?: string);
-}
-export interface DeviceAuthConfig {
-    clientId: string;
-    /** Limited-Input clients are issued a secret; included in the token poll. */
-    clientSecret?: string;
-    scopes: string[];
-    /** Overridable for tests; defaults to Google's production endpoints. */
-    deviceCodeUrl?: string;
-    tokenUrl?: string;
-}
-export interface DeviceAuthDeps {
-    fetch: typeof fetch;
-    sleep: (ms: number) => Promise<void>;
-    /** Monotonic-ish clock for the local expiry deadline; defaults to Date.now. */
-    now?: () => number;
-}
-export interface DeviceCodeResponse {
-    device_code: string;
-    user_code: string;
-    /** Google returns `verification_url` (not the RFC's `verification_uri`). */
-    verification_url: string;
-    expires_in: number;
-    interval: number;
-}
-export interface DeviceTokenResult {
-    id_token: string;
-    refresh_token?: string;
-    expires_in: number;
-}
-/**
- * Step 1 — request a device_code + user_code from Google.
- */
-export declare function requestDeviceCode(config: DeviceAuthConfig, deps: DeviceAuthDeps): Promise<DeviceCodeResponse>;
-/**
- * Step 2 — poll Google's token endpoint until the user authorizes the
- * device_code, honoring the RFC 8628 poll semantics.
- *
- * Sleeps `interval` BEFORE each poll (never hammers immediately). A local
- * deadline derived from `expires_in` bounds the loop so a code the user
- * abandons can't poll forever even if Google never returns expired_token.
- */
-export declare function pollForDeviceToken(deviceCode: DeviceCodeResponse, config: DeviceAuthConfig, deps: DeviceAuthDeps): Promise<DeviceTokenResult>;
-//# sourceMappingURL=device-auth.d.ts.map

package/dist/device-auth.js

@@ -1 +0,0 @@
-const u="https://oauth2.googleapis.com/device/code",p="https://oauth2.googleapis.com/token",w="urn:ietf:params:oauth:grant-type:device_code",h=5,f=5;class n extends Error{code;constructor(o,i){super(i??o),this.code=o,this.name="DeviceAuthError"}}async function v(t,o){const i=t.deviceCodeUrl??u;let c;try{c=await o.fetch(i,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({client_id:t.clientId,scope:t.scopes.join(" ")})})}catch(s){throw new n("device_code_request_failed",`Could not reach Google device endpoint: ${s?.message??"unknown"}`)}if(!c.ok){const s=await l(c);throw new n(s??"device_code_request_failed",`Device-code request failed (HTTP ${c.status}${s?`, ${s}`:""})`)}let e;try{e=await c.json()}catch{throw new n("malformed_token_response","Device-code response was not JSON")}if(!e.device_code||!e.user_code||!e.verification_url)throw new n("malformed_token_response","Device-code response missing device_code/user_code/verification_url");return{device_code:e.device_code,user_code:e.user_code,verification_url:e.verification_url,expires_in:typeof e.expires_in=="number"?e.expires_in:1800,interval:typeof e.interval=="number"?e.interval:5}}async function E(t,o,i){const c=o.tokenUrl??p,e=i.now??Date.now,s=e()+t.expires_in*1e3;let _=t.interval>0?t.interval:5;for(;;){if(e()>=s)throw new n("expired_token","Device code expired before the authorization was completed");await i.sleep(_*1e3);let a;try{a=await i.fetch(c,{method:"POST",headers:{"Content-Type":"application/x-www-form-urlencoded"},body:new URLSearchParams({client_id:o.clientId,...o.clientSecret?{client_secret:o.clientSecret}:{},device_code:t.device_code,grant_type:w})})}catch(r){throw new n("device_token_request_failed",`Could not reach Google token endpoint: ${r?.message??"unknown"}`)}if(a.ok){let r;try{r=await a.json()}catch{throw new n("malformed_token_response","Token response was not JSON")}if(!r.id_token||typeof r.expires_in!="number")throw new n("malformed_token_response","Token response missing id_token or expires_in");return{id_token:r.id_token,refresh_token:r.refresh_token,expires_in:r.expires_in}}const d=await l(a);switch(d){case"authorization_pending":continue;case"slow_down":_+=5;continue;case"access_denied":throw new n("access_denied","Authorization was denied by the user");case"expired_token":throw new n("expired_token","Device code expired before authorization");default:throw new n(d??"device_token_request_failed",`Device token poll failed (HTTP ${a.status}${d?`, ${d}`:""})`)}}}async function l(t){try{const o=await t.json();return typeof o?.error=="string"?o.error:null}catch{return null}}export{n as DeviceAuthError,E as pollForDeviceToken,v as requestDeviceCode};

package/dist/drone-address.d.ts

@@ -1,26 +0,0 @@
-/**
- * gh#371 two-layer drone addressing — the shared short-uuid render helper.
- *
- * Lives in its own neutral module so BOTH the roster renderer
- * (roster-render.ts) and the read-log renderer (regen-format.ts
- * formatLogEntryMarkdown) import the SAME helper — one canonical token, no
- * cross-surface divergence (gh#371 decision-3). A drone's live LABEL renumbers
- * when cube membership changes (e.g. eighteen-of-28 → eighteen-of-30, which
- * bounced this cluster's own dispatches); the short-uuid is the STABLE address.
- */
-/**
- * The stable short-uuid: the first 8 hex of the drone_id (UUID). It is, by
- * construction, a valid `startsWith` prefix of the full drone_id, so the
- * worker resolver (resolveDirectRecipientIds, gh#371 S1) matches it
- * cube-scoped. Lowercased to match the resolver's `/^[0-9a-f]{8,}$/i` guard.
- */
-export declare function shortDroneId(droneId: string): string;
-/**
- * The clearly-LABELED address token shown beside a drone on the roster and on
- * each read-log entry (gh#371 finding-2): `` `id:3336cde1` ``. Backticked so it
- * renders monospace — visually distinct from the plain `[entry_id: …]` bracket
- * that sits beside it in read-log, so a weak model never confuses which token
- * to `borg_ack` with (entry_id) versus address a dispatch to (`id:` short-uuid).
- */
-export declare function formatDroneAddressToken(droneId: string): string;
-//# sourceMappingURL=drone-address.d.ts.map

package/dist/drone-address.js

@@ -1 +0,0 @@
-function e(r){return r.slice(0,8).toLowerCase()}function o(r){return`\`id:${e(r)}\``}export{o as formatDroneAddressToken,e as shortDroneId};

package/dist/get-started.d.ts

@@ -1,20 +0,0 @@
-/**
- * Fresh-vs-configured rule. "Configured" = the user has completed `borg setup`,
- * signalled by the PRESENCE of a stored credential. Inputs are existence
- * booleans only — the caller null-checks the token accessors and never decodes,
- * logs, or prints the token value (SR gh#817 constraint).
- *
- * Refresh-token presence is the durable signal: it survives id_token expiry, so
- * a configured user whose id_token has lapsed is NOT mistaken for fresh (which
- * would wrongly suppress their normal launch). The id_token presence is the
- * fallback for the rare case where Google returned no refresh_token and the
- * id_token is still valid.
- */
-export declare function shouldShowGetStarted(hasRefreshToken: boolean, hasIdToken: boolean): boolean;
-/**
- * The user-visible get-started text. Carries ZERO auth material (no tokens, no
- * PII) — it is pure onboarding guidance. When no agent CLI is detected, lead
- * with the install-an-agent-CLI step (mirrors the B1 banner intent).
- */
-export declare function composeGetStarted(hasAgentCli: boolean): string;
-//# sourceMappingURL=get-started.d.ts.map

package/dist/get-started.js

@@ -1,2 +0,0 @@
-function n(o,e){return!o&&!e}function r(o){const e=["","Welcome to Borg MCP \u2014 multi-agent coordination for your AI coding agent.","","You're not set up yet. To get started:",""];let t=1;return o||(e.push(`  ${t}. Install an agent CLI first:`,"       Claude Code: https://claude.ai/download","       Codex:       https://developers.openai.com/codex"),t++),e.push(`  ${t}. borg setup${" ".repeat(Math.max(1,8))}\u2014 sign in with Google`),t++,e.push(`  ${t}. cd into your project, then: borg assimilate \u2014 join/create a cube`,"","Then `borg` launches your agent in that cube. Run `borg --help` for more.",""),e.join(`
-`)}export{r as composeGetStarted,n as shouldShowGetStarted};

package/dist/health-beat.d.ts

@@ -1,134 +0,0 @@
-/**
- * gh#541 WU-2 — client health beat (the Part B "receipt watermark" producer).
- *
- * The MCP-client child process emits a periodic + event-driven health BEAT to
- * the server's `POST /api/drone/health` (WU-1). The beat reports:
- *   - `last_event_at`        — when this client last RECEIVED an inbound cube
- *                              event (the wake-path RECEIPT evidence). This is
- *                              produced BELOW the agent classifier (WU-0 proved
- *                              child-process HTTP is independent of the agent
- *                              tool-call path), so it stays fresh even during a
- *                              classifier outage and even when the agent /loop
- *                              never wakes — which is exactly what lets the
- *                              watchdog (WU-3) tell DEAF (Monitor down) apart
- *                              from POST-BLOCKED.
- *   - `sse_connected`        — the SSE wire state.
- *   - `inbox_monitor_armed`  — whether a tail-Monitor is watching the inbox.
- *
- * The beat carries NO token material in the body (auth is the X-Drone-Session
- * header, same as every other drone endpoint). It is strictly BEST-EFFORT: a
- * failed POST is swallowed and must never crash the SSE stream.
- *
- * Side-effecting deps (fetch, token, cube/status/monitor probes, clock) are
- * injected so the producer is unit-tested without real network/keychain/pgrep.
- */
-/** The cube context needed to address + auth a beat (subset of ActiveCube). */
-export interface HealthBeatActive {
-    cubeId: string;
-    droneId: string;
-    sessionToken: string;
-    apiUrl: string;
-}
-export interface HealthPayload {
-    sse_connected: boolean;
-    inbox_monitor_armed: boolean;
-    /**
-     * gh#633: transport-AGNOSTIC wake-path-armed signal. The client computes it
-     * from its OWN runtime wake mechanism — claude=tail-F inbox Monitor health,
-     * codex=app-server bridge liveness — so the HOP-2 wake-path-deaf classifier
-     * reads one boolean without branching on (mis-recordable) agent_kind. For a
-     * claude drone this equals inbox_monitor_armed; for codex it reflects the
-     * bridge (which has no tail-F Monitor by design).
-     */
-    wake_armed: boolean;
-    /**
-     * gh#634: the drone's agent_kind from LIVE runtime detection
-     * (resolveSessionAgentKind). Assimilation captures agent_kind only at join,
-     * so a relaunch of an existing seat needs this always-running child to
-     * refresh the recorded value through recordDroneHealth's COALESCE update.
-     */
-    agent_kind: 'claude' | 'codex' | 'opencode';
-    /**
-     * gh#408: live runtime hostname. Assimilate captures hostname only at first
-     * join; the beat carries the relaunched process's current machine name so
-     * the server can self-heal the recorded display value.
-     */
-    hostname: string | null;
-    /**
-     * gh#646: installed borgmcp client version from getPackageVersion().
-     * Stored separately from liveness so a relaunched/upgraded drone can refresh
-     * its recorded version without re-assimilating.
-     */
-    version: string;
-    last_event_at: string | null;
-}
-/** Record that an inbound cube event was just received (the receipt evidence). */
-export declare function recordEventReceipt(now?: Date): void;
-export declare function getLastEventReceivedAt(): Date | null;
-export declare function getCachedMonitorHealthy(): boolean | null;
-/** Cached transport-agnostic wake-armed (gh#633), for cheap per-event beats. */
-export declare function getCachedWakeArmed(): boolean | null;
-/**
- * Reset module state. TEST-ONLY — the beat state is a process singleton in
- * normal operation; nothing in production code should call this.
- * @internal
- */
-export declare function __resetHealthBeatStateForTest(): void;
-/**
- * Build the beat payload from the current receipt watermark + the supplied
- * wire/monitor state.
- *
- * `inbox_monitor_armed` maps the tri-state monitor probe to the boolean the
- * server schema requires: ONLY a POSITIVELY-broken probe (`false`) reports
- * `false`; both healthy (`true`) and unknown (`null`) report `true`. This
- * mirrors `shouldShowWakePathWarning` (which fires only on `=== false`) and is
- * the design's false-deaf-avoidance posture — an undeterminable probe must not
- * masquerade as a dead Monitor.
- */
-export declare function buildHealthPayload(sseConnected: boolean, inboxMonitorHealthy: boolean | null, wakeArmed: boolean | null, agentKind: 'claude' | 'codex' | 'opencode', hostname: string | null, version: string): HealthPayload;
-export interface BeatTransport {
-    fetchImpl: typeof fetch;
-    getToken: () => Promise<string>;
-}
-/**
- * Best-effort POST of a beat. Swallows ALL errors (token fetch, network,
- * non-2xx) — a beat that can't be delivered must never propagate into the
- * stream loop. Body carries NO token material; auth is via headers.
- */
-export declare function postHealthBeat(active: HealthBeatActive, payload: HealthPayload, deps: BeatTransport): Promise<void>;
-/** Build the current payload and post it (best-effort). */
-export declare function emitHealthBeat(active: HealthBeatActive, opts: {
-    sseConnected: boolean;
-    inboxMonitorHealthy: boolean | null;
-    wakeArmed: boolean | null;
-    agentKind: 'claude' | 'codex' | 'opencode';
-    hostname: string | null;
-    version: string;
-} & BeatTransport): Promise<void>;
-export interface HealthBeatTickDeps extends BeatTransport {
-    getActiveCube: () => Promise<HealthBeatActive | null>;
-    getStreamConnected: () => boolean;
-    getInboxPath: (active: HealthBeatActive) => string | null;
-    checkMonitor: (inboxPath: string | null) => boolean | null;
-    isCodexRemoteWake: () => boolean;
-    probeBridgeArmed: (active: HealthBeatActive) => Promise<boolean | null>;
-    probeOpenCodeDrone?: (active: HealthBeatActive) => Promise<boolean | null>;
-    resolveAgentKind: () => 'claude' | 'codex' | 'opencode';
-    resolveHostname: () => string | null;
-    resolveVersion: () => string;
-}
-/**
- * One tick of the periodic beat: resolve the active cube, probe the live
- * wire + Monitor state, cache the monitor result (so cheap per-event beats can
- * reuse it without re-spawning pgrep), and emit the beat. No active cube → no
- * beat. Best-effort: never throws.
- */
-export declare function runHealthBeatOnce(deps: HealthBeatTickDeps): Promise<void>;
-/** Default periodic cadence for the health beat. */
-export declare const HEALTH_BEAT_INTERVAL_MS = 60000;
-/**
- * Start the periodic beat. Fire-and-forget; the timer is `unref`'d so it never
- * keeps the process alive on its own. Returns the timer handle (tests clear it).
- */
-export declare function startHealthBeatTick(deps: HealthBeatTickDeps, intervalMs?: number): NodeJS.Timeout;
-//# sourceMappingURL=health-beat.d.ts.map

package/dist/health-beat.js

@@ -1 +0,0 @@
-let r=null,i=null,l=null;function g(e=new Date){r=e}function v(){return r}function y(){return i}function k(){return l}function A(){r=null,i=null,l=null}function d(e,t,n,o,a,c){return{sse_connected:e,inbox_monitor_armed:t!==!1,wake_armed:n!==!1,agent_kind:o,hostname:a,version:c,last_event_at:r?r.toISOString():null}}async function f(e,t,n){try{const o=await n.getToken();await n.fetchImpl(`${e.apiUrl}/api/drone/health`,{method:"POST",headers:{Authorization:`Bearer ${o}`,"X-Drone-Session":e.sessionToken,"Content-Type":"application/json"},body:JSON.stringify(t)})}catch{}}async function m(e,t){const n=d(t.sseConnected,t.inboxMonitorHealthy,t.wakeArmed,t.agentKind,t.hostname,t.version);await f(e,n,t)}async function h(e){try{const t=await e.getActiveCube();if(!t)return;const n=e.getStreamConnected(),o=e.checkMonitor(e.getInboxPath(t));i=o;const a=e.resolveAgentKind(),c=a==="opencode"?await e.probeOpenCodeDrone?.(t)??null:a==="codex"?e.isCodexRemoteWake()?await e.probeBridgeArmed(t):!1:o;l=c;const s=e.resolveHostname(),u=e.resolveVersion();await m(t,{sseConnected:n,inboxMonitorHealthy:o,wakeArmed:c,agentKind:a,hostname:s,version:u,fetchImpl:e.fetchImpl,getToken:e.getToken})}catch{}}const x=6e4;function H(e,t=x){h(e);const n=setInterval(()=>{h(e)},t);return n.unref?.(),n}export{x as HEALTH_BEAT_INTERVAL_MS,A as __resetHealthBeatStateForTest,d as buildHealthPayload,m as emitHealthBeat,y as getCachedMonitorHealthy,k as getCachedWakeArmed,v as getLastEventReceivedAt,f as postHealthBeat,g as recordEventReceipt,h as runHealthBeatOnce,H as startHealthBeatTick};

package/dist/role-section.d.ts

@@ -1,110 +0,0 @@
-/**
- * Role-text section parsing + granular section patching (gh#473 PR1).
- *
- * Platform-dependency-free, same shape as `message-taxonomy.ts`: pure
- * string logic so the worker DB layer AND unit tests can both import it
- * without dragging in Cloudflare / Neon types.
- *
- * ## Why not markdown `##` headings
- *
- * Real role `detailed_description` text (see `client/src/templates.ts`)
- * does NOT use `##` headings. It is structured as:
- *
- *   - a PREAMBLE — free prose before the first label line
- *     (e.g. "You implement changes to the codebase…");
- *   - one or more SECTIONS, each headed by a PLAIN-LABEL LINE — a line
- *     that is a short label terminated by a single trailing colon and
- *     nothing else (e.g. `Workflow:`, `Project conventions:`,
- *     `Your job:`, `Log conventions you use:`);
- *   - TRAILING inlined `${ESCALATION_DISCIPLINE}` / `${...}` constant
- *     text woven onto the end of the field. That text uses `**bold:**`
- *     markdown emphasis, NOT bare label lines, so it is NOT a section
- *     boundary — it falls into the last label section as literal text.
- *
- * A parser that splits on `##` finds ZERO sections in real role text.
- * The label-line delimiter below matches the ACTUAL structure.
- *
- * ## Byte-identical round-trip invariant
- *
- * `serializeSections(parseRoleSections(text)) === text` for ANY input.
- * The parser does not trim, normalize newlines, or otherwise rewrite
- * bytes — each section's `body` retains the exact slice (including its
- * heading line and the newline that terminates it) so concatenation
- * reproduces the original field verbatim. The single named-fragment
- * mutation is therefore the ONLY byte-level change a patch makes.
- */
-/** What kind of label heads a section. */
-export type RoleSectionKind = 'preamble' | 'label';
-export interface RoleSection {
-    /**
-     * The section's label WITHOUT the trailing colon, trimmed
-     * (e.g. "Workflow", "Project conventions"). `null` for the preamble
-     * (the pre-first-label span). Used as the addressing key for patches.
-     */
-    heading: string | null;
-    kind: RoleSectionKind;
-    /**
-     * The EXACT source slice for this section, including its heading line
-     * (for label sections) and every byte through to (but not including)
-     * the next section's heading line. Concatenating every section's
-     * `body` in order reproduces the original text byte-for-byte.
-     */
-    body: string;
-}
-export type RoleSectionPatchOp = {
-    action: 'replace';
-    heading: string;
-    body: string;
-} | {
-    action: 'insert';
-    heading: string;
-    body: string;
-    after?: string | null;
-} | {
-    action: 'delete';
-    heading: string;
-};
-/**
- * Test whether a single line is a plain-label section heading.
- *
- * Rules (deliberately narrow to avoid false positives against prose
- * that merely contains a colon):
- *   - no leading whitespace (label lines start at column 0);
- *   - the line ends with exactly one `:`;
- *   - the text before the colon is non-empty, contains no other `:`,
- *     and is "short" (≤ 60 chars) — long colon-terminated prose lines
- *     are not labels;
- *   - the label is not a markdown emphasis run (does not start with
- *     `*`, `-`, `#`, `>` or backtick) — those are list/markdown lines,
- *     not plain labels (the woven `**Dense communication discipline:**`
- *     constant headings must NOT be treated as section boundaries).
- */
-export declare function isLabelLine(line: string): boolean;
-/**
- * Parse role `detailed_description` text into ordered sections.
- *
- * The result always round-trips byte-identical through
- * `serializeSections`. An empty string yields a single empty preamble
- * section so callers always have a stable shape to address.
- */
-export declare function parseRoleSections(text: string): RoleSection[];
-/** Concatenate sections back into the original field text. */
-export declare function serializeSections(sections: RoleSection[]): string;
-/**
- * Apply a single section-level patch to role text, returning the new
- * full field text. Every other byte is preserved.
- *
- *   - replace: overwrite the matched section's body with a re-rendered
- *     `<heading>:\n<body>` block. The heading match is case-insensitive
- *     on the label; the re-rendered heading uses the supplied casing.
- *   - insert: add a new label section. Placed after the section named by
- *     `after` (case-insensitive), or appended at the end when `after` is
- *     omitted/null. Rejects if a section with the same heading already
- *     exists (use replace instead).
- *   - delete: drop the matched section entirely.
- *
- * Throws when the target section is missing (replace/delete) or already
- * present (insert), or when `after` does not resolve.
- */
-export declare function patchRoleSectionText(text: string, op: RoleSectionPatchOp): string;
-//# sourceMappingURL=role-section.d.ts.map

package/dist/role-section.js

@@ -1,8 +0,0 @@
-function b(t){if(/^\s/.test(t)||!t.endsWith(":"))return!1;const e=t.slice(0,-1);return!(e.length===0||e.length>60||e.includes(":")||/^[*\-#>`]/.test(e))}function w(t){const e=[],n=t.split(`
-`),l=i=>i<n.length-1?n[i]+`
-`:n[i];let f=null,s="preamble",d="",a=!1;const r=()=>{e.push({heading:f,kind:s,body:d})};for(let i=0;i<n.length;i++){const u=n[i];b(u)?(r(),f=u.slice(0,-1).trim(),s="label",d=l(i),a=!0):(d+=l(i),a=!0)}return(a||e.length===0)&&r(),e}function c(t){return t.map(e=>e.body).join("")}function o(t){return t.trim().toLowerCase()}function h(t,e){const n=`${t.trim()}:
-`;if(e==="")return n;const l=e.endsWith(`
-`)?e:e+`
-`;return n+l}function g(t,e){if(e<0||e>=t.length)return;const n=t[e];n.body!==""&&!n.body.endsWith(`
-`)&&(t[e]={...n,body:n.body+`
-`})}function y(t,e){const n=w(t),l=o(e.heading);if(e.action==="replace"){const r=n.findIndex(i=>i.kind==="label"&&i.heading!=null&&o(i.heading)===l);if(r===-1)throw new Error(`Role section "${e.heading}" not found. Use action="insert" to add it.`);return n[r]={heading:e.heading.trim(),kind:"label",body:h(e.heading,e.body)},c(n)}if(e.action==="delete"){const r=n.findIndex(i=>i.kind==="label"&&i.heading!=null&&o(i.heading)===l);if(r===-1)throw new Error(`Role section "${e.heading}" not found.`);return n.splice(r,1),c(n)}if(n.some(r=>r.kind==="label"&&r.heading!=null&&o(r.heading)===l))throw new Error(`Role section "${e.heading}" already exists. Use action="replace" to overwrite it.`);const s={heading:e.heading.trim(),kind:"label",body:h(e.heading,e.body)};if(e.after==null)return g(n,n.length-1),n.push(s),c(n);const d=o(e.after),a=n.findIndex(r=>r.kind==="label"&&r.heading!=null&&o(r.heading)===d);if(a===-1)throw new Error(`Cannot insert after section "${e.after}" \u2014 it does not exist.`);return g(n,a),n.splice(a+1,0,s),c(n)}export{b as isLabelLine,w as parseRoleSections,y as patchRoleSectionText,c as serializeSections};

package/dist/setup-action.d.ts

@@ -1,20 +0,0 @@
-/**
- * gh#794 (CR 9f302b15): the `borg setup` auth-step decision, extracted as a
- * PURE, side-effect-free mapping so the SR#3 contract is unit-pinned WITHOUT
- * importing setup.ts (which runs `main()` at module load) or mocking the
- * monolithic runSetup. `tsc` proves setup.ts's switch COMPILES; the unit test
- * over this helper proves it MAPS correctly — a future mis-edit (e.g. a
- * 'transient' wrongly skipping → an SR#3 break) fails the mapping test instead
- * of silently passing every probeSession test.
- *
- *   - 'valid'     → 'skip'   (short-circuit OAuth; session is usable)
- *   - 'dead'      → 'reauth' (full re-auth — NEVER short-circuit past a dead
- *                             token, the exact failure #794 fixes)
- *   - 'transient' → 'retry'  (network blip — don't re-auth, don't destroy)
- *
- * Type-only import of SessionState → zero runtime coupling to remote-client.
- */
-import type { SessionState } from './remote-client.js';
-export type SetupAuthAction = 'skip' | 'reauth' | 'retry';
-export declare function setupActionForSession(state: SessionState): SetupAuthAction;
-//# sourceMappingURL=setup-action.d.ts.map

package/dist/setup-action.js

@@ -1 +0,0 @@
-function t(e){switch(e){case"valid":return"skip";case"transient":return"retry";default:return"reauth"}}export{t as setupActionForSession};

package/dist/stale-version-check.d.ts

@@ -1,40 +0,0 @@
-/**
- * Sprint 7 (b) — stale-binary defensive hardening (gh#148 close-out).
- *
- * drone-3's v0.8.0 case (cube log 2026-05-18T10:35Z) ran for months
- * without warning that v0.8.10 had shipped the gh#71 carve-out for
- * own-drone heartbeat-pings. The silent-stale-binary failure mode
- * costs cube collective time to diagnose because the gap between
- * "installed version" and "latest published" is invisible to the
- * operator.
- *
- * This module surfaces that gap at borg launch time via a stderr
- * warning. Network check against npmjs.org registry is async +
- * timeout-gated so a slow registry doesn't block the operator. Fails
- * silently on any error (network failure, registry change,
- * prerelease version, etc.) — defense-in-depth, never a blocker.
- */
-export interface VersionCheckResult {
-    stale: boolean;
-    message: string | null;
-}
-/**
- * Pure compare: given an installed version string and a latest version
- * string, decide whether to warn. Both strings are expected in semver
- * `MAJOR.MINOR.PATCH` form (no prerelease, no build metadata).
- *
- * Returns `{stale: true, message}` when installed is at least
- * MINOR_VERSIONS_BEHIND_THRESHOLD minor versions behind latest on the
- * same major. Defaults conservatively — unparseable input, prerelease
- * tags, or anything weird returns `stale: false` so we never
- * false-positive on edge cases.
- */
-export declare function compareVersionsForStaleness(installed: string, latest: string): VersionCheckResult;
-/**
- * Fetch the latest published borgmcp version from the npm registry.
- * Returns the version string on success, `null` on any failure
- * (timeout, network error, registry change, malformed response).
- * Never throws — caller treats null as "skip the warning."
- */
-export declare function fetchLatestBorgmcpVersion(): Promise<string | null>;
-//# sourceMappingURL=stale-version-check.d.ts.map

package/dist/stale-version-check.js

@@ -1 +0,0 @@
-const a="https://registry.npmjs.org/borgmcp/latest",i=2e3,c=1;function u(t,e){const r=o(t),n=o(e);if(!r||!n)return{stale:!1,message:null};if(r.major!==n.major)return{stale:!1,message:null};const s=n.minor-r.minor;return s<1?{stale:!1,message:null}:{stale:!0,message:`\u26A0 borgmcp ${t} is behind latest ${e} \u2014 npm install -g borgmcp@latest`}}function o(t){if(typeof t!="string"||t.length===0)return null;const e=/^(\d+)\.(\d+)\.(\d+)$/.exec(t);return e?{major:parseInt(e[1],10),minor:parseInt(e[2],10),patch:parseInt(e[3],10)}:null}async function m(){const t=new AbortController,e=setTimeout(()=>t.abort(),2e3);try{const r=await fetch(a,{signal:t.signal,headers:{Accept:"application/json"}});if(!r.ok)return null;const n=await r.json();return typeof n.version!="string"||n.version.length===0?null:n.version}catch{return null}finally{clearTimeout(e)}}export{u as compareVersionsForStaleness,m as fetchLatestBorgmcpVersion};