@mnemom/mnemom 0.14.6 → 0.15.1-next.0

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>;

package/dist/lib/try-me.js

@@ -0,0 +1,245 @@
+/**
+ * `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.
+ */
+import { MnemomApiError, readApiError } from "./api.js";
+import { getApiUrl } from "./config.js";
+// ── resolve (zero-auth; the token IS the credential) ─────────────────────────
+const TOKEN_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** True iff `token` is shaped like a try-me token (tryme_… / a bare slug). */
+export function looksLikeTryMeToken(token) {
+    return TOKEN_RE.test(token.trim());
+}
+/**
+ * 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 function assertHttpUrl(url, what) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`${what} is not a valid URL: ${url}`);
+    }
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+        throw new Error(`${what} must be http(s): ${url}`);
+    }
+    return parsed.href;
+}
+/** Shape gate: a resolved manifest must carry the fields the runner depends on. */
+function isUsableManifest(m) {
+    if (!m || typeof m !== "object")
+        return false;
+    const x = m;
+    return (typeof x.token === "string" &&
+        !!x.gateway &&
+        typeof x.gateway.endpoint === "string" &&
+        typeof x.gateway.model === "string" &&
+        typeof x.gateway.key_header === "string" &&
+        !!x.declare &&
+        !!x.handoff &&
+        typeof x.handoff.claim_url_template === "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 async function resolveBriefing(token, opts = {}) {
+    const apiBase = (opts.apiBase ?? getApiUrl()).replace(/\/$/, "");
+    const url = `${apiBase}/v1/dojo/try-me/resolve?token=${encodeURIComponent(token)}`;
+    let response;
+    try {
+        response = await fetch(url, { headers: { Accept: "application/json" } });
+    }
+    catch (err) {
+        throw new Error(`Couldn't reach the Mnemom API at ${apiBase}: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+    }
+    if (!response.ok) {
+        // The resolve endpoint emits the nested {error:{code,message}} envelope, so
+        // readApiError surfaces the server's own message. Layer on actionable hints
+        // for the burn/expiry/setup cases.
+        const apiErr = await readApiError(response, "Failed to resolve the try-me briefing");
+        if (response.status === 410) {
+            throw new MnemomApiError(410, `${apiErr.message} A try-me token is single-use — mint a fresh one and try again.`, { code: apiErr.code });
+        }
+        if (response.status === 404) {
+            throw new MnemomApiError(404, `${apiErr.message} (no briefing exists for that token)`, {
+                code: apiErr.code,
+            });
+        }
+        if (response.status === 503) {
+            throw new MnemomApiError(503, `${apiErr.message} (the Dojo demo isn't fully configured yet — retryable)`, { code: apiErr.code });
+        }
+        throw apiErr;
+    }
+    const manifest = (await response.json().catch(() => null));
+    if (!isUsableManifest(manifest)) {
+        throw new Error("The resolved briefing is missing fields this CLI needs (gateway/declare/handoff). " +
+            "The manifest version may be newer than this CLI — run `npx @mnemom/mnemom@latest`.");
+    }
+    return manifest;
+}
+// ── credential + proof + URL builders (pure) ─────────────────────────────────
+/** Is this a token-mode manifest (per-session mnbt_ birth token) vs legacy provider key? */
+export function isTokenMode(manifest) {
+    return (typeof manifest.gateway.birth_token === "string" && manifest.gateway.birth_token.length > 0);
+}
+/**
+ * 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 function birthCredential(manifest) {
+    const cred = manifest.gateway.birth_token ?? manifest.gateway.provider_key;
+    if (!cred) {
+        throw new Error("Briefing carries no birth credential (neither birth_token nor provider_key).");
+    }
+    return cred;
+}
+/**
+ * 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 function claimProof(manifest) {
+    if (isTokenMode(manifest))
+        return manifest.gateway.birth_token;
+    throw new Error('Legacy provider-key manifests need SHA256("<provider_key>|<name>") as the claim proof; ' +
+        "token-mode (mnbt_) briefings are expected here.");
+}
+/** Build the canonical /claim URL: substitute agent_id + hash_proof; leave dojo_config as given. */
+export function buildClaimUrl(manifest, agentId, proof) {
+    const url = manifest.handoff.claim_url_template
+        .replace("{agent_id}", encodeURIComponent(agentId))
+        .replace("{hash_proof}", encodeURIComponent(proof));
+    return assertHttpUrl(url, "claim_url_template");
+}
+/** Build the first-party protection-grant URL: substitute agent_id. */
+export function buildGrantUrl(manifest, agentId) {
+    const url = manifest.handoff.grant_url_template.replace("{agent_id}", encodeURIComponent(agentId));
+    return assertHttpUrl(url, "grant_url_template");
+}
+/**
+ * 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 function buildDojoDeepLink(manifest, agentId) {
+    const base = assertHttpUrl(manifest.handoff.dojo_url, "dojo_url");
+    const u = new URL(base);
+    u.searchParams.set("agent", agentId);
+    return u.href;
+}
+/** The provider-native birth path under the gateway endpoint, per provider. */
+export function birthPath(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "/v1/messages";
+        case "openai":
+            return "/v1/chat/completions";
+        case "google":
+            // Gemini's generateContent path needs the model in it; surfaced to the
+            // caller, which only supports Anthropic births today (the Dojo default).
+            return "/v1beta/models";
+        default:
+            return "/v1/messages";
+    }
+}
+/**
+ * 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 async function birthAgent(manifest, name, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const provider = manifest.gateway.provider;
+    if (provider !== "anthropic") {
+        throw new Error(`This CLI can birth Anthropic agents only (the Dojo default); manifest provider is "${provider}". ` +
+            "Birth it manually per the manifest's step 2, then re-run with --agent <id>.");
+    }
+    const endpoint = assertHttpUrl(manifest.gateway.endpoint, "gateway.endpoint");
+    const url = endpoint.replace(/\/$/, "") + birthPath(provider);
+    const cred = birthCredential(manifest);
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        [manifest.gateway.key_header]: cred,
+        [manifest.gateway.agent_header]: name,
+        // Anthropic Messages API requires a version header; the gateway forwards it.
+        "anthropic-version": "2023-06-01",
+    };
+    const body = JSON.stringify({
+        model: manifest.gateway.model,
+        max_tokens: 32,
+        messages: [
+            {
+                role: "user",
+                content: "I am being born into the Mnemom Dojo. Reply with a one-word greeting.",
+            },
+        ],
+    });
+    const response = await doFetch(url, { method: "POST", headers, body });
+    // Capture the agent id BEFORE inspecting ok/body — the gateway stamps it on the
+    // response header even for a non-2xx model reply, and a born agent is the point.
+    const agentId = response.headers.get(manifest.gateway.agent_header.toLowerCase());
+    if (!response.ok && !agentId) {
+        const text = await response.text().catch(() => "");
+        throw new MnemomApiError(response.status, `Birth call failed (${response.status}) and no agent id was minted: ${text.slice(0, 300)}`);
+    }
+    if (!agentId || !/^mnm-/.test(agentId)) {
+        throw new Error(`Birth succeeded (${response.status}) but the gateway returned no mnm- agent id on the ` +
+            `${manifest.gateway.agent_header} response header. Cannot continue.`);
+    }
+    return { agentId, status: response.status };
+}
+/**
+ * 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 async function fetchAgentClaimed(apiBase, agentId, opts = {}) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const base = apiBase.replace(/\/$/, "");
+    const url = `${base}/v1/agents/${encodeURIComponent(agentId)}`;
+    try {
+        const response = await doFetch(url, { headers: { Accept: "application/json" } });
+        if (!response.ok)
+            return null;
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+/** Small awaitable sleep used by the runner's poll loops. */
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.14.6",
+  "version": "0.15.1-next.0",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {
@@ -8,10 +8,11 @@
     "smoltbot": "./dist/smoltbot-shim.js"
   },
   "scripts": {
-    "build": "npm install --prefix ../shared/policy-engine && npm run build --prefix ../shared/policy-engine && tsc",
+    "build": "npm install && npm install --prefix ../shared/policy-engine && npm run build --prefix ../shared/policy-engine && tsc",
     "dev": "tsx src/index.ts",
     "gen:command-tree": "tsx scripts/gen-command-tree.mjs",
     "check:command-tree": "tsx scripts/gen-command-tree.mjs --check",
+    "version": "npm run gen:command-tree && git add command-tree.json",
     "test": "vitest"
   },
   "dependencies": {

package/dist/commands/integrity.d.ts

@@ -1 +0,0 @@
-export declare function integrityCommand(agentName?: string): Promise<void>;