@mnemom/mnemom 0.14.6 → 0.15.0

package/dist/lib/oauth.js

@@ -0,0 +1,450 @@
+/**
+ * OAuth 2.1 client for the Mnemom Authorization Server.
+ *
+ * `mnemom login` authenticates against the Mnemom OAuth AS (the same AS that
+ * fronts the MCP control plane) instead of doing a raw Supabase session login.
+ * This yields SCOPED access tokens (`mcp:read` / `mcp:write`) — not the full
+ * Supabase god-token — so a leaked CLI credential can only do what the CLI was
+ * granted, and grants are independently revocable server-side (MNE-805/806).
+ *
+ * Two interactive flows, both standards-based:
+ *   - Authorization Code + PKCE with a loopback redirect (the `wrangler login`
+ *     pattern): open the browser to /authorize, catch the redirect on a
+ *     localhost listener, exchange code+verifier at /token.
+ *   - RFC 8628 Device Authorization Grant (`--no-browser` / headless): POST
+ *     /device_authorization, print the user_code + verification_uri, poll
+ *     /token honoring `authorization_pending` and `slow_down`.
+ *
+ * Everything is driven off RFC 8414 discovery
+ * (/.well-known/oauth-authorization-server) — endpoint paths are NOT hardcoded.
+ * The public client_id is obtained via RFC 7591 Dynamic Client Registration and
+ * cached, so there is no client secret to embed (the AS advertises
+ * token_endpoint_auth_method "none" — public clients only).
+ */
+import * as http from "node:http";
+import * as crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { getApiUrl } from "./config.js";
+// The scopes the CLI requests. The AS currently advertises mcp:read + mcp:write
+// (scopes_supported in discovery); we request both so a single login covers the
+// full command surface. If discovery ever narrows what's available we intersect
+// against scopes_supported before asking, so we never request an unknown scope.
+const REQUESTED_SCOPES = ["mcp:read", "mcp:write"];
+const CLIENT_NAME = "Mnemom CLI";
+const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+// Loopback login waits at most this long for the browser round-trip before
+// giving up and freeing the port.
+const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
+let cachedMetadata = null;
+/**
+ * Fetch (and process-cache) the AS metadata document. We resolve it relative to
+ * the active API base URL so staging/local point at their own AS.
+ */
+export async function discover() {
+    if (cachedMetadata)
+        return cachedMetadata;
+    const url = `${getApiUrl()}/.well-known/oauth-authorization-server`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+        throw new Error(`Could not load OAuth metadata from ${url} (HTTP ${res.status}). ` + `Is the API reachable?`);
+    }
+    const meta = (await res.json());
+    if (!meta.authorization_endpoint || !meta.token_endpoint) {
+        throw new Error("OAuth metadata is missing authorization_endpoint/token_endpoint.");
+    }
+    cachedMetadata = meta;
+    return meta;
+}
+/** Reset the process-level discovery cache (used by tests). */
+export function _resetDiscoveryCache() {
+    cachedMetadata = null;
+}
+/** Intersect our requested scopes with what the AS advertises. */
+function negotiateScopes(meta) {
+    const supported = meta.scopes_supported;
+    const scopes = supported && supported.length > 0
+        ? REQUESTED_SCOPES.filter((s) => supported.includes(s))
+        : REQUESTED_SCOPES;
+    // If nothing intersects (misconfigured AS), fall back to asking for what the
+    // AS says it supports rather than sending an empty scope.
+    return (scopes.length > 0 ? scopes : (supported ?? REQUESTED_SCOPES)).join(" ");
+}
+// ============================================================================
+// Dynamic Client Registration (RFC 7591)
+// ============================================================================
+/**
+ * Register a public client for the CLI and return its client_id. The AS issues
+ * public clients (token_endpoint_auth_method "none"), so there is no secret to
+ * persist. The caller is responsible for caching the returned id.
+ */
+export async function registerClient(redirectUris) {
+    const meta = await discover();
+    if (!meta.registration_endpoint) {
+        throw new Error("This Authorization Server does not support dynamic client registration; " +
+            "no public CLI client_id is available.");
+    }
+    const res = await fetch(meta.registration_endpoint, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Accept: "application/json" },
+        body: JSON.stringify({
+            client_name: CLIENT_NAME,
+            redirect_uris: redirectUris,
+            grant_types: ["authorization_code", "refresh_token", DEVICE_CODE_GRANT],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Client registration failed (HTTP ${res.status}): ${await safeBody(res)}`);
+    }
+    const data = (await res.json());
+    if (!data.client_id) {
+        throw new Error("Client registration response did not include a client_id.");
+    }
+    return data.client_id;
+}
+/**
+ * Generate a PKCE verifier/challenge pair. The verifier is a high-entropy
+ * URL-safe string (RFC 7636 §4.1: 43–128 chars from the unreserved set); the
+ * challenge is BASE64URL(SHA256(verifier)) for the S256 method (the only method
+ * the AS advertises, and the only one allowed under OAuth 2.1).
+ */
+export function generatePkce() {
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge, method: "S256" };
+}
+function base64url(buf) {
+    return buf.toString("base64url");
+}
+function tokensFromResponse(data) {
+    const now = Math.floor(Date.now() / 1000);
+    const expiresIn = typeof data.expires_in === "number" ? data.expires_in : 3600;
+    return {
+        accessToken: data.access_token,
+        tokenType: data.token_type ?? "Bearer",
+        refreshToken: data.refresh_token,
+        scope: data.scope,
+        expiresAt: now + expiresIn,
+    };
+}
+/**
+ * Run the interactive authorization-code + PKCE login. Returns the issued
+ * scoped tokens plus the client_id that was used (so the caller can persist it
+ * for refresh). `openUrl` is injectable so tests can drive the flow without
+ * spawning a real browser.
+ */
+export async function loginWithLoopback(openUrl = openBrowser) {
+    const meta = await discover();
+    const pkce = generatePkce();
+    const state = crypto.randomBytes(16).toString("hex");
+    const { port, codePromise, close } = await startLoopbackServer(state);
+    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    // Register a client bound to the exact loopback redirect URI. OAuth 2.1
+    // requires exact redirect_uri matching, and the loopback port is ephemeral,
+    // so we register per-login (cheap, public client, no secret).
+    const clientId = await registerClient([redirectUri]);
+    const authUrl = new URL(meta.authorization_endpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("scope", negotiateScopes(meta));
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", pkce.method);
+    console.log("Opening browser to authenticate...");
+    console.log(`If the browser doesn't open, visit:\n  ${authUrl.toString()}\n`);
+    openUrl(authUrl.toString());
+    console.log("Waiting for authentication...");
+    try {
+        const code = await codePromise;
+        const tokens = await exchangeCode(meta, clientId, code, pkce.verifier, redirectUri);
+        return { tokens, clientId };
+    }
+    finally {
+        close();
+    }
+}
+/**
+ * Start a loopback HTTP listener that captures the OAuth redirect
+ * (GET /callback?code=...&state=...). Resolves with the authorization code once
+ * a redirect with a matching state arrives; rejects on error/mismatch/timeout.
+ */
+function startLoopbackServer(expectedState) {
+    let resolveCode;
+    let rejectCode;
+    const codePromise = new Promise((resolve, reject) => {
+        resolveCode = resolve;
+        rejectCode = reject;
+    });
+    const server = http.createServer((req, res) => {
+        const reqUrl = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (req.method !== "GET" || reqUrl.pathname !== "/callback") {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        const error = reqUrl.searchParams.get("error");
+        const code = reqUrl.searchParams.get("code");
+        const state = reqUrl.searchParams.get("state");
+        if (error) {
+            const desc = reqUrl.searchParams.get("error_description") ?? error;
+            respondHtml(res, 400, "Authentication failed", desc);
+            rejectCode(new Error(`Authorization denied: ${desc}`));
+            return;
+        }
+        // Constant-time state comparison to avoid leaking timing on the CSRF token.
+        if (!state || !timingSafeEqual(state, expectedState)) {
+            respondHtml(res, 403, "Authentication failed", "State mismatch — possible CSRF.");
+            rejectCode(new Error("State mismatch — possible CSRF attack"));
+            return;
+        }
+        if (!code) {
+            respondHtml(res, 400, "Authentication failed", "No authorization code in callback.");
+            rejectCode(new Error("No authorization code in callback"));
+            return;
+        }
+        respondHtml(res, 200, "Authenticated!", "You can close this tab and return to the terminal.");
+        resolveCode(code);
+    });
+    return new Promise((resolve) => {
+        server.listen(0, "127.0.0.1", () => {
+            const port = server.address().port;
+            const timeout = setTimeout(() => {
+                rejectCode(new Error("Login timed out. Please try again."));
+                server.close();
+            }, LOOPBACK_TIMEOUT_MS);
+            resolve({
+                port,
+                codePromise,
+                close: () => {
+                    clearTimeout(timeout);
+                    server.close();
+                },
+            });
+        });
+    });
+}
+async function exchangeCode(meta, clientId, code, verifier, redirectUri) {
+    const res = await fetch(meta.token_endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+        }),
+    });
+    if (!res.ok) {
+        throw new Error(`Token exchange failed: ${await oauthError(res)}`);
+    }
+    return tokensFromResponse((await res.json()));
+}
+/**
+ * Run the RFC 8628 device authorization grant. Registers a client (the device
+ * flow needs no redirect, but the AS's DCR validation requires a valid
+ * redirect_uri — HTTPS or a loopback — so we register a loopback placeholder it
+ * will never redirect to), requests a device code, prints the user_code +
+ * verification_uri for the user to approve in any browser, then polls the token
+ * endpoint until approval — honoring `authorization_pending` and `slow_down`
+ * per the spec.
+ *
+ * `display` and `sleep` are injectable so tests can drive the poll loop
+ * deterministically without real timers or stdout.
+ */
+export async function loginWithDevice(opts) {
+    const display = opts?.display ?? ((line) => console.log(line));
+    const sleep = opts?.sleep ?? defaultSleep;
+    const meta = await discover();
+    if (!meta.device_authorization_endpoint) {
+        throw new Error("This Authorization Server does not support the device flow.");
+    }
+    // Device flow has no redirect, but the AS's DCR validation rejects the OAuth
+    // OOB sentinel ("redirect_uri must be HTTPS or a loopback for native
+    // clients"). Register a loopback placeholder — it satisfies validation and is
+    // never used, since the device grant never redirects.
+    const clientId = await registerClient(["http://127.0.0.1/callback"]);
+    const authzRes = await fetch(meta.device_authorization_endpoint, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+            Accept: "application/json",
+        },
+        body: new URLSearchParams({ client_id: clientId, scope: negotiateScopes(meta) }),
+    });
+    if (!authzRes.ok) {
+        throw new Error(`Device authorization failed: ${await oauthError(authzRes)}`);
+    }
+    const authz = (await authzRes.json());
+    display("");
+    display("To authenticate, visit:");
+    display(`  ${authz.verification_uri}`);
+    display("");
+    display(`And enter the code:  ${authz.user_code}`);
+    if (authz.verification_uri_complete) {
+        display("");
+        display(`Or open this URL directly:`);
+        display(`  ${authz.verification_uri_complete}`);
+    }
+    display("");
+    display("Waiting for authorization...");
+    const tokens = await pollDeviceToken(meta, clientId, authz, sleep);
+    return { tokens, clientId };
+}
+async function pollDeviceToken(meta, clientId, authz, sleep) {
+    // RFC 8628 §3.5: default interval is 5s if the server omits it; on slow_down
+    // we increase the interval by 5s and keep that as the new minimum.
+    let intervalMs = (authz.interval ?? 5) * 1000;
+    const deadline = Date.now() + authz.expires_in * 1000;
+    for (;;) {
+        if (Date.now() >= deadline) {
+            throw new Error("Device authorization expired before approval. Please try again.");
+        }
+        await sleep(intervalMs);
+        const res = await fetch(meta.token_endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: new URLSearchParams({
+                grant_type: DEVICE_CODE_GRANT,
+                device_code: authz.device_code,
+                client_id: clientId,
+            }),
+        });
+        if (res.ok) {
+            return tokensFromResponse((await res.json()));
+        }
+        const body = (await res.json().catch(() => ({})));
+        switch (body.error) {
+            case "authorization_pending":
+                continue; // keep polling at the current interval
+            case "slow_down":
+                intervalMs += 5000; // RFC 8628 §3.5
+                continue;
+            case "expired_token":
+                throw new Error("Device authorization expired before approval. Please try again.");
+            case "access_denied":
+                throw new Error("Authorization was denied.");
+            default:
+                throw new Error(`Device authorization failed: ${body.error ?? `HTTP ${res.status}`}` +
+                    (body.error_description ? ` — ${body.error_description}` : ""));
+        }
+    }
+}
+// ============================================================================
+// Refresh (RFC 6749 §6)
+// ============================================================================
+/**
+ * Exchange a refresh token for a fresh access token. Returns null if refresh is
+ * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
+ * so callers can fall back to prompting for re-login rather than crashing.
+ */
+export async function refreshTokens(refreshToken, clientId) {
+    if (!refreshToken || !clientId)
+        return null;
+    try {
+        const meta = await discover();
+        const res = await fetch(meta.token_endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+                Accept: "application/json",
+            },
+            body: new URLSearchParams({
+                grant_type: "refresh_token",
+                refresh_token: refreshToken,
+                client_id: clientId,
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        const tokens = tokensFromResponse(data);
+        // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in which
+        // case the old one remains valid — preserve it so the next refresh works.
+        if (!tokens.refreshToken)
+            tokens.refreshToken = refreshToken;
+        return tokens;
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Open `url` in the user's default browser WITHOUT a shell. The URL is always
+ * passed as a separate argv element (never concatenated into a command string),
+ * so shell metacharacters — `$(...)`, backticks, `\` — in the URL can never be
+ * interpreted as a command. Fire-and-forget: any failure (no opener installed,
+ * headless host) is swallowed because callers already print a manual-URL
+ * fallback, so a missing browser must not crash login.
+ */
+export function openBrowser(url) {
+    // On Windows, `start` is a cmd builtin and its FIRST quoted arg is the window
+    // title; the empty "" makes the URL the target rather than the title.
+    const [command, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = execFile(command, args, () => {
+            /* swallow opener errors — the manual URL fallback is already printed */
+        });
+        // Don't keep the event loop alive on the opener; login flow waits on the
+        // loopback/device promise, not on the browser process.
+        child.unref?.();
+    }
+    catch {
+        /* execFile threw synchronously (e.g. command not found) — ignore */
+    }
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Constant-time string compare that tolerates length differences. */
+function timingSafeEqual(a, b) {
+    const ab = Buffer.from(a);
+    const bb = Buffer.from(b);
+    if (ab.length !== bb.length)
+        return false;
+    return crypto.timingSafeEqual(ab, bb);
+}
+/** Escape a string for safe interpolation into HTML text content. */
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function respondHtml(res, status, title, body) {
+    res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+    // title/body are escaped: on the error path `body` carries the OAuth
+    // error_description straight from the callback query string (attacker-
+    // controllable on the loopback URL), so interpolating it raw is reflected XSS
+    // (CodeQL js/reflected-xss). Escaping closes it; the page is plain text anyway.
+    res.end(`<html><body style="font-family:system-ui;text-align:center;padding:60px">` +
+        `<h2>${escapeHtml(title)}</h2><p>${escapeHtml(body)}</p></body></html>`);
+}
+/** Format a standard OAuth error response ({error, error_description}). */
+async function oauthError(res) {
+    const body = (await res.json().catch(() => ({})));
+    if (body.error) {
+        return body.error + (body.error_description ? ` — ${body.error_description}` : "");
+    }
+    return `HTTP ${res.status}`;
+}
+async function safeBody(res) {
+    return (await res.text().catch(() => "")) || `HTTP ${res.status}`;
+}

package/dist/lib/try-me.d.ts

@@ -0,0 +1,181 @@
+/**
+ * `mnemom try-me <token>` — the deterministic Dojo-onboarding skill-runner
+ * (MNE-934, epic MNE-931).
+ *
+ * On a fresh machine with no MCP connector configured, the Dojo `/try-me`
+ * onboarding works badly because every agent improvises the manifest's flow
+ * differently. This module is the read-only client half of the fix: it resolves
+ * the shipped v5.0 briefing manifest and exposes the typed pieces + IO helpers
+ * the `try-me` command executes deterministically (resolve → birth → claim →
+ * alignment → protection → hand off).
+ *
+ * It is strictly ADDITIVE and consumes Alex's shipped endpoints READ-ONLY:
+ *   - GET /v1/dojo/try-me/resolve?token=…  (zero-auth; the token IS the credential)
+ *   - POST <gateway.endpoint>/v1/messages   (birth — the agent's first model call)
+ *   - GET /v1/agents/:id                    (public claim poll)
+ * The card-write PUTs reuse the canonical client (lib/api.ts). NOTHING in the
+ * dojo backend or the website is touched.
+ *
+ * The manifest contract mirrored here is mnemom-api `src/dojo/try-me.ts`
+ * (MANIFEST_VERSION "5.0", MNE-879 B1). We type only the fields the runner
+ * consumes and tolerate everything else (`[key: string]: unknown`) so a manifest
+ * bump that adds fields never breaks the CLI.
+ */
+/** A canonical card object (alignment/protection) — opaque to the runner; passed through verbatim. */
+export type CanonicalCard = Record<string, unknown>;
+/** The MODEL credential block — births the agent + carries gateway calls (BYOK). */
+export interface ManifestGateway {
+    /** Provider gateway route, e.g. https://gateway.mnemom.ai/anthropic */
+    endpoint: string;
+    provider: string;
+    /** Concrete model id to send at birth (bare aliases 404 upstream). */
+    model: string;
+    /** Provider-native header the credential rides on (x-api-key / Authorization / x-goog-api-key). */
+    key_header: string;
+    /** Per-session birth token (mnbt_…) — token mode (preferred). */
+    birth_token?: string;
+    /** Legacy shared provider key — present only when birth_token is absent. */
+    provider_key?: string;
+    /** Header carrying the agent's birth NAME. */
+    agent_header: string;
+    [key: string]: unknown;
+}
+/** Human-handoff surfaces (claim/grant/dojo URLs + the name question). */
+export interface ManifestHandoff {
+    name_question: string;
+    name_options: string[];
+    signup_url: string;
+    /** /claim template — {agent_id} + {hash_proof}, with &dojo_config (also binds server-side). */
+    claim_url_template: string;
+    /** First-party one-time protection-grant page — {agent_id} substituted. */
+    grant_url_template: string;
+    /** Recipe describing what hash_proof is (token mode: the raw mnbt_; legacy: SHA256). */
+    claim_hash_recipe: string;
+    dojo_url: string;
+    [key: string]: unknown;
+}
+/** The GOOD cards the agent declares. */
+export interface ManifestDeclare {
+    alignment_card: CanonicalCard;
+    protection_card: CanonicalCard;
+    protection_mode: "nudge" | string;
+    [key: string]: unknown;
+}
+export interface BriefingStep {
+    n: number;
+    title: string;
+    body: string;
+    human_handoff?: boolean;
+    [key: string]: unknown;
+}
+export interface BriefingManifest {
+    directive?: string;
+    version: string;
+    token: string;
+    reassurance?: string;
+    mission?: {
+        scenario_id?: string;
+        name?: string;
+        role_system_prompt?: string;
+        failure_conditions?: Record<string, unknown>;
+        [key: string]: unknown;
+    };
+    model?: {
+        provider: string;
+        name: string;
+    };
+    gateway: ManifestGateway;
+    declare: ManifestDeclare;
+    bind?: {
+        endpoint?: string;
+        config_id?: string;
+        [key: string]: unknown;
+    };
+    handoff: ManifestHandoff;
+    steps?: BriefingStep[];
+    state_machine?: {
+        initial?: string;
+        states?: Array<Record<string, unknown>>;
+    };
+    instructions_markdown?: string;
+    [key: string]: unknown;
+}
+/** True iff `token` is shaped like a try-me token (tryme_… / a bare slug). */
+export declare function looksLikeTryMeToken(token: string): boolean;
+/**
+ * Validate a URL the manifest handed us before we fetch/open it. The manifest is
+ * server-built so its URLs are trusted, but we guard the protocol so a malformed
+ * manifest can never coerce a non-http(s) open (e.g. file://) on the host.
+ */
+export declare function assertHttpUrl(url: string, what: string): string;
+/**
+ * Resolve a try-me token to its briefing manifest. Zero-auth — the token is the
+ * credential. Idempotent within the server's reuse window (a re-resolve replays
+ * the SAME manifest + birth credential), so a retry is safe. Maps the documented
+ * status codes to actionable messages:
+ *   400 token missing/invalid · 404 never minted · 410 used/expired ·
+ *   503 demo not configured yet (retryable) · 5xx server error.
+ */
+export declare function resolveBriefing(token: string, opts?: {
+    apiBase?: string;
+}): Promise<BriefingManifest>;
+/** Is this a token-mode manifest (per-session mnbt_ birth token) vs legacy provider key? */
+export declare function isTokenMode(manifest: BriefingManifest): boolean;
+/**
+ * The single credential the agent presents on `gateway.key_header` to be born:
+ * the per-session birth token (token mode) or the shared provider key (legacy).
+ */
+export declare function birthCredential(manifest: BriefingManifest): string;
+/**
+ * The claim `hash_proof`. In token mode it IS the birth token, presented RAW (the
+ * server double-hashes); we cannot derive the legacy SHA256("<key>|<name>") proof
+ * here because the runner never holds the provider key in token mode. For legacy
+ * manifests the caller must supply the provider key + name separately.
+ */
+export declare function claimProof(manifest: BriefingManifest): string;
+/** Build the canonical /claim URL: substitute agent_id + hash_proof; leave dojo_config as given. */
+export declare function buildClaimUrl(manifest: BriefingManifest, agentId: string, proof: string): string;
+/** Build the first-party protection-grant URL: substitute agent_id. */
+export declare function buildGrantUrl(manifest: BriefingManifest, agentId: string): string;
+/**
+ * The Dojo deep link with the agent pre-selected, so the human only has to press
+ * Begin Sim: `<dojo_url>?agent=<agent_id>` (mirrors the manifest's step 6).
+ */
+export declare function buildDojoDeepLink(manifest: BriefingManifest, agentId: string): string;
+/** The provider-native birth path under the gateway endpoint, per provider. */
+export declare function birthPath(provider: string): string;
+export interface BirthResult {
+    /** The minted agent id (mnm-…) captured from the x-mnemom-agent response header. */
+    agentId: string;
+    /** The gateway HTTP status (200 on a successful birth). */
+    status: number;
+}
+/**
+ * Be born: make the first model call through the Mnemom gateway with the birth
+ * credential, the human-chosen name, and the CONCRETE model id, then capture the
+ * minted `agent_id` from the `x-mnemom-agent` RESPONSE header.
+ *
+ * Only Anthropic births are supported here (the Dojo runs Haiku); other
+ * providers throw a clear error rather than send a malformed body. `fetchImpl`
+ * is injectable for tests.
+ */
+export declare function birthAgent(manifest: BriefingManifest, name: string, opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<BirthResult>;
+/** The slice of the public agent projection the claim poll reads. */
+export interface PublicAgentStatus {
+    id?: string;
+    name?: string | null;
+    claimed?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Read the PUBLIC (no-auth) agent projection used to detect the human's claim.
+ * Never throws — a transient 404/5xx (the agent not yet queryable, or a blip)
+ * resolves to null so the caller's poll loop simply keeps waiting.
+ */
+export declare function fetchAgentClaimed(apiBase: string, agentId: string, opts?: {
+    fetchImpl?: typeof fetch;
+}): Promise<PublicAgentStatus | null>;
+/** Small awaitable sleep used by the runner's poll loops. */
+export declare function sleep(ms: number): Promise<void>;