@mnemom/mnemom 0.12.1 → 0.14.0

package/dist/lib/api.d.ts

@@ -9,56 +9,187 @@ export declare const API_BASE: string;
  * cached reservation) — when omitted, we mint a UUIDv4.
  */
 export declare function newIdempotencyKey(): string;
+/**
+ * GET /v1/agents/:id.
+ *
+ * Source-verified at canonical ref c18491e6 (handleGetAgent): the OWNER view
+ * returns the raw agents row plus a computed `status` (active if last_seen
+ * within 1h); a non-owner of a claimed+public agent gets publicAgentProjection
+ * ({ id, name, claimed: !!claimed_by, last_seen, ... }). The previously-typed
+ * `gateway` is a PHANTOM — no agents column and neither projection emits it;
+ * it was always undefined. `claimed` is only emitted on the public projection
+ * (derived from claimed_by); the owner view carries claimed_by/claimed_at.
+ * Fields are optional/nullable to tolerate both projections.
+ */
 export interface Agent {
     id: string;
-    gateway: string;
+    status?: "active" | "offline";
     last_seen: string | null;
-    claimed: boolean;
-    email?: string;
-    created_at: string;
+    email?: string | null;
+    created_at?: string;
+    claimed_by?: string | null;
+    claimed_at?: string | null;
+    name?: string | null;
+    claimed?: boolean;
 }
 /**
- * Per api.mnemom.ai/openapi.json#components/schemas/IntegrityScore:
+ * GET /v1/integrity/:id — components/schemas/IntegrityScore:
  *
  *   { agent_id, total_traces, verified_traces, violation_count, integrity_score }
  *
  * `integrity_score` is a value in [0, 1].
  *
- * Pre-this-fix the CLI's interface declared `score` / `verified` /
- * `violations` / `last_updated` — none of which exist on the wire. The
- * `mnemom integrity` command rendered every field as `undefined` (and the
- * score as `NaN%`) against any agent. Field names now match the docs
- * verbatim.
+ * The array-vs-object divergence flagged here previously is RESOLVED upstream:
+ * source-verified at canonical contract ref c18491e6, handleGetIntegrity now
+ * normalizes BOTH the RPC path (which Supabase wraps as a one-row array) and
+ * the manual fallback to a single object with `agent_id` always populated —
+ * the interface comment in src/index.ts credits "CLI consumers" for the fix.
+ * So `agent_id` is reliably emitted (hence required here). The defensive
+ * array-unwrap in getIntegrity below is retained only as belt-and-suspenders
+ * for a CLI pointed at an older, pre-normalization API.
  *
- * NOTE — API shape divergence (flagged for a follow-up mnemom-api PR):
- * the RPC path in handleGetIntegrity returns an *array* of one object
- * (Supabase wraps TABLE-returning RPCs as arrays) without `agent_id`;
- * the manual fallback returns the *object* with `agent_id`. The docs
- * canonical is the object shape. We accept both shapes defensively in
- * getIntegrity below so this CLI works against today's prod API and
- * keeps working when the API normalizes to a single shape.
+ * (The spec schema does not list a `required` array, but the emitted-set
+ * always includes all five fields — doc-set == emitted-set.)
  */
 export interface IntegrityScore {
-    agent_id?: string;
+    agent_id: string;
     total_traces: number;
     verified_traces: number;
     violation_count: number;
     integrity_score: number;
 }
+/**
+ * GET /v1/traces row — components/schemas/APTrace.
+ *
+ * Source-verified at canonical ref c18491e6: handleGetTraces selects the raw
+ * `traces` table rows (no projection), whose columns are AIP-NESTED:
+ * `trace_id, timestamp, action(object), decision(object), verification(object|null)`
+ * (confirmed by the explicit selects at index.ts:2563 / :4217 and the
+ * `trace.decision.selection_reasoning` / `trace.verification?.verified`
+ * readers).
+ *
+ * Pre-this-fix the CLI typed this FLAT — { id, action:string, verified:boolean,
+ * reasoning, tool_name } — none of which the wire emits. `mnemom logs` rendered
+ * every action as "[object Object]" and flagged EVERY trace as [VIOLATION]
+ * (undefined `verified` is falsy). Field names + nesting now match the wire.
+ */
 export interface Trace {
-    id: string;
+    trace_id: string;
     agent_id: string;
     timestamp: string;
-    action: string;
-    verified: boolean;
-    reasoning?: string;
-    tool_name?: string;
-    tool_input?: Record<string, unknown>;
+    action: {
+        type?: string;
+        name?: string;
+        category?: string;
+    };
+    decision?: {
+        selected?: string;
+        selection_reasoning?: string;
+        values_applied?: string[];
+        confidence?: number | null;
+    };
+    verification: {
+        verified: boolean;
+        violations: string[];
+    } | null;
+    created_at?: string;
+}
+/**
+ * Canonical API error envelope — backward-tolerant.
+ *
+ * Source-verified against mnemom-api (2026-05-28): the wire is NOT uniformly
+ * nested. Three live shapes:
+ *   1. NESTED   {error:{code,message}, spec_deviation?}  — the spec-validate
+ *      enforce-hook only (500 internal_error / undocumented_status_code /
+ *      enforced body deviations). src/runtime/spec-validate-hook.ts.
+ *   2. FLAT     {error:"message"}                        — every per-module
+ *      errorResponse() helper (org/sideband/network/admin/governance + the
+ *      top-level errorResponse in index.ts). The DOMINANT shape.
+ *   3. FLAT+code {error:"message", code:"..."}           — auth routes
+ *      (src/auth/routes.ts).
+ * No route emits a top-level `message` field; `details` is reserved/forward-
+ * tolerant. We parse all three and prefer nested.
+ *
+ * LIVE-WIRE NOTE (shepherd 48-probe sweep, staging+prod): the spec-validate
+ * ENFORCE hook is active on both deployed envs and normalizes every body to the
+ * NESTED shape before the wire — so in practice the CLI sees nested universally.
+ * The flat / flat+code tolerance is insurance for non-enforce contexts
+ * (local dev server, enforce=observe). The hook also adds a top-level
+ * `spec_deviation` sibling AND can REWRITE an undocumented status to a synthetic
+ * 500 (e.g. an undocumented 404 → 500 with `spec_deviation.original_status:404`).
+ * We surface that as MnemomApiError.effectiveStatus so command-layer 404/empty-
+ * state branching isn't fooled by the rewrite.
+ *
+ * Pre-this-fix ApiError was flat {error,message} read at `error.message` (top
+ * level) — undefined for every real shape → the server message was dropped.
+ */
+export interface SpecDeviation {
+    keyword?: string;
+    field?: string;
+    original_status?: number;
 }
 export interface ApiError {
-    error: string;
-    message: string;
+    error?: string | {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+    message?: string;
+    code?: string;
+    details?: unknown;
+    conflict_agent_id?: string;
+    spec_deviation?: SpecDeviation;
 }
+/** Normalized error fields extracted from any of the three envelope shapes. */
+export interface ParsedApiError {
+    message?: string;
+    code?: string;
+    details?: unknown;
+    conflict_agent_id?: string;
+    spec_deviation?: SpecDeviation;
+}
+/**
+ * Extract the human message + code + details from a raw error body,
+ * tolerating all three live envelope shapes (prefer nested).
+ */
+export declare function normalizeApiError(raw: ApiError | null | undefined): ParsedApiError;
+/** Parse a non-OK Response body into normalized error fields (never throws). */
+export declare function parseApiErrorBody(response: Response): Promise<ParsedApiError>;
+/**
+ * Structured API error. `message` is the human-readable server message (or a
+ * fallback); `.status`/`.code`/`.details`/`.conflictAgentId` give callers a
+ * structured surface to branch on without parsing the message string.
+ * `instanceof MnemomApiError` narrows in command-layer catch blocks.
+ */
+export declare class MnemomApiError extends Error {
+    /** The wire HTTP status — may be a synthetic 500 from the enforce hook. */
+    readonly status: number;
+    /**
+     * The TRUE intended status: `spec_deviation.original_status ?? status`. The
+     * enforce hook can rewrite an undocumented status to a synthetic 500; command
+     * layers MUST branch on `effectiveStatus` (not `status`) for 404/empty-state
+     * detection or they'll be fooled by the rewrite.
+     */
+    readonly effectiveStatus: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    readonly conflictAgentId?: string;
+    /** Top-level enforce-hook sibling (present only on a spec-rewritten body). */
+    readonly specDeviation?: SpecDeviation;
+    constructor(status: number, message: string, opts?: {
+        code?: string;
+        details?: unknown;
+        conflictAgentId?: string;
+        specDeviation?: SpecDeviation;
+    });
+}
+/**
+ * Read a non-OK Response into a MnemomApiError, preferring the server message
+ * and falling back to `${fallback}: ${status}` when the body carried none.
+ * Captures the enforce-hook `spec_deviation` sibling so `.effectiveStatus`
+ * reflects the true intended status behind any synthetic-500 rewrite.
+ */
+export declare function readApiError(response: Response, fallback: string): Promise<MnemomApiError>;
 export declare function postApi<T>(endpoint: string, body: unknown, opts?: {
     idempotencyKey?: string;
 }): Promise<T>;
@@ -76,6 +207,13 @@ export interface AgentListItem {
     containment_status: string | null;
     key_prefix?: string | null;
 }
+/**
+ * @deprecated Legacy per-user listing — `GET /v1/agents` is scoped by the
+ * caller's `claimed_by` rows, which ADR-062 retired as an authorization /
+ * listing boundary (org_id is now the sole boundary). New code must list via
+ * {@link listOrgAgents} (org-scoped). Retained only for back-compat callers;
+ * the `mnemom agents` command and name resolution no longer use it.
+ */
 export declare function listAgents(): Promise<AgentListItem[]>;
 export interface OrgListItem {
     org_id: string;
@@ -100,6 +238,85 @@ export interface PersonalOrgRef {
  * first; multi-user orgs follow.
  */
 export declare function listMyOrgs(): Promise<OrgListItem[]>;
+/**
+ * One agent row from the org-scoped fleet (`get_org_agent_fleet`). Mirrors the
+ * website's `OrgFleetAgent` shape so the CLI and dashboard read the same
+ * surface. This is the ADR-062-canonical listing: every agent has exactly one
+ * governing org, and the fleet is keyed on `org_id` (not `claimed_by`).
+ */
+export interface OrgFleetAgent {
+    agent_id: string;
+    agent_name: string;
+    owner_email: string | null;
+    last_seen: string | null;
+    created_at: string;
+    integrity_score: number;
+    coverage_ratio: number;
+    latest_verdict: string | null;
+    active_drift_alerts: number;
+    worst_drift_severity: string | null;
+    check_count: number;
+    containment_status?: string | null;
+    avatar_url?: string | null;
+}
+/**
+ * GET /v1/orgs/:org_id/agents — the org-scoped agent fleet (ADR-062). Any
+ * member of the org may read it; non-members get 403.
+ */
+export declare function fetchOrgFleet(orgId: string): Promise<OrgFleetAgent[]>;
+/** An {@link AgentListItem} tagged with the org it belongs to. */
+export interface OrgAgentRow extends AgentListItem {
+    org_id: string;
+    org_name: string;
+}
+/**
+ * List agents the ADR-062 way: scoped by org membership, never by `claimed_by`.
+ *
+ * - With `orgId`: lists that single org's fleet.
+ * - Without `orgId`: aggregates the fleet across every org the caller belongs
+ *   to (the same pattern as {@link listAllTeams}), tagging each row with its
+ *   org. Orgs the caller can't read (403/404) are skipped silently so one
+ *   inaccessible org doesn't fail the whole listing.
+ */
+export declare function listOrgAgents(orgId?: string): Promise<OrgAgentRow[]>;
+/**
+ * Result of a successful agent claim (ADR-062). Mirrors the locked
+ * `POST /v1/agents/:id/claim` 200 body verbatim — only the fields the
+ * endpoint actually returns. `org_id` is the org the agent ACTUALLY landed
+ * in (resolved server-side: the requested org, or the caller's personal org
+ * when none was supplied), so the CLI can confirm placement without a
+ * follow-up read. Optional/defaulted on the type so a mid-deploy CLI pointed
+ * at an older API that omits a field degrades to a sane value rather than
+ * crashing.
+ */
+export interface ClaimAgentResult {
+    claimed: boolean;
+    agent_id: string;
+    /** Resolved landing org (may differ from the request); null if unscoped. */
+    org_id: string | null;
+    /** ISO-8601 claim timestamp; null if the server omits it. */
+    claimed_at: string | null;
+}
+/**
+ * POST /v1/agents/:id/claim — claim an agent into an org (ADR-062).
+ *
+ * Body is `{ hash_proof, org_id? }`. `hash_proof` (the agent's full SHA-256
+ * proof) authenticates the caller as the agent's owner; the user's own auth
+ * header rides along too so the platform can validate org membership and link
+ * the principal. Omit `orgId` to land in the caller's personal org (the
+ * platform default); a supplied `orgId` is validated against the caller's
+ * memberships server-side (a non-member gets a 403 the command layer turns
+ * into a teaching error listing claimable orgs).
+ *
+ * An Idempotency-Key is minted (and held across the 401-refresh retry) so a
+ * retried claim replays the same logical operation server-side.
+ */
+export declare function claimAgent(agentId: string, body: {
+    hashProof: string;
+    orgId?: string;
+}, opts?: {
+    idempotencyKey?: string;
+}): Promise<ClaimAgentResult>;
 /**
  * GET /v1/auth/me/personal-org — accessor for the user's personal org.
  * Idempotent: lazily provisions for legacy accounts that pre-date the
@@ -238,11 +455,11 @@ export declare function revokeTeamAdmin(teamId: string, userId: string): Promise
  */
 export declare function listTeamAdmins(teamId: string): Promise<TeamAdminListResponse>;
 /**
- * Look up an agent in the authenticated user's account by name.
+ * Look up an agent by name across the caller's org fleets (ADR-062-scoped via
+ * {@link listOrgAgents}, not the legacy `claimed_by` list).
  * Tries exact match first, then single partial match.
  * Throws if multiple agents partially match (ambiguous).
  * Returns null if no match found.
- * Note: capped at 100 agents by listAgents().
  */
 export declare function getAgentByName(name: string): Promise<AgentListItem | null>;
 /**
@@ -270,88 +487,6 @@ export declare function getIntegrity(id: string): Promise<IntegrityScore>;
  * don't need a special case for it.
  */
 export declare function getTraces(id: string, limit?: number): Promise<Trace[]>;
-export interface AlignmentCard {
-    card_id?: string;
-    version?: string;
-    issued_at?: string;
-    expires_at?: string;
-    principal?: {
-        name?: string;
-        type?: string;
-        organization?: string;
-    };
-    values?: {
-        declared?: string[];
-        definitions?: Record<string, string>;
-    };
-    autonomy_envelope?: {
-        bounded_actions?: string[];
-        forbidden_actions?: string[];
-        escalation_triggers?: Array<{
-            condition: string;
-            action?: string;
-        }>;
-    };
-    audit_commitment?: {
-        log_level?: string;
-        retention_days?: number;
-        access_policy?: string;
-    };
-    extensions?: Record<string, unknown>;
-    [key: string]: unknown;
-}
-export interface CardResponse {
-    card_id: string;
-    agent_id: string;
-    card_json: AlignmentCard;
-    created_at: string;
-    updated_at: string;
-}
-export declare function getCard(agentId: string): Promise<CardResponse | null>;
-export declare function updateCard(agentId: string, cardJson: AlignmentCard, opts?: {
-    idempotencyKey?: string;
-}): Promise<{
-    updated: boolean;
-    card_id: string;
-}>;
-export declare function reverifyAgent(agentId: string, opts?: {
-    idempotencyKey?: string;
-}): Promise<{
-    reverified: number;
-}>;
-export interface PolicyResponse {
-    id: string;
-    name: string;
-    description: string | null;
-    policy_json: Record<string, unknown>;
-    version: number;
-    created_by: string;
-    created_at: string;
-}
-export interface PolicyListResponse {
-    agent_id: string;
-    policy: PolicyResponse | null;
-}
-export declare function getPolicy(agentId: string): Promise<PolicyListResponse | null>;
-export declare function publishPolicy(agentId: string, policyJson: Record<string, unknown>, opts?: {
-    idempotencyKey?: string;
-}): Promise<{
-    id: string;
-    version: number;
-    created: boolean;
-}>;
-export declare function testPolicyHistorical(agentId: string, policyJson: Record<string, unknown>, limit?: number): Promise<{
-    agent_id: string;
-    policy_name: string;
-    total_traces: number;
-    results: unknown[];
-    summary: {
-        pass: number;
-        warn: number;
-        fail: number;
-        skipped: number;
-    };
-}>;
 /**
  * Fetch the canonical alignment card as YAML (or JSON fallback).
  * Returns the raw response body as a string.
@@ -402,6 +537,30 @@ export declare const PROTECTION_CARD_MAX_BYTES: number;
 export declare function putProtectionCard(agentId: string, body: string, contentType?: "text/yaml" | "application/json", opts?: {
     idempotencyKey?: string;
 }): Promise<PublishedCardResponse>;
+export interface CardPreviewResult {
+    /** true ⇔ the server accepted+composed the card (HTTP 200). */
+    valid: boolean;
+    status: number;
+    /** Canonical composed card (200 only). */
+    composed?: Record<string, unknown>;
+    /** Per-field tightenings applied by the org/platform floor (200 only). */
+    conflicts?: unknown[];
+    /** Warning-mode coherence findings (200 only). */
+    coherence_violations?: unknown[];
+    /** Parsed error envelope on a 4xx validation failure (invalid only). */
+    error?: {
+        code?: string;
+        message?: string;
+        details?: unknown;
+    };
+}
+/**
+ * Dry-run validate + compose a card body against the server's authoritative
+ * pipeline. Returns a structured result — a 422/400 validation failure is an
+ * expected `valid:false` outcome (NOT a thrown error). 401 throws (caller
+ * should fall back to offline validation); 403/5xx throw a MnemomApiError.
+ */
+export declare function previewComposeAgentCard(agentId: string, kind: TeamTemplateKind, body: string, contentType?: "text/yaml" | "application/json"): Promise<CardPreviewResult>;
 /**
  * Resolve an agent name or ID to a server agent ID.
  *
@@ -646,7 +805,7 @@ export declare function getSafeHouseHarnessState(): Promise<{
     fast: HarnessRunSummary | null;
 }>;
 export type GovernanceSignalScope = "platform" | "org" | "team" | "agent";
-export type GovernanceSignalSource = "sideband.drift" | "sideband.coherence" | "sideband.fault_line" | "sideband.fleet";
+export type GovernanceSignalSource = "sideband.drift" | "sideband.coherence" | "sideband.fault_line" | "sideband.fleet" | "network.threat_level.changed";
 export type GovernanceSignalSeverity = "info" | "warn" | "high" | "critical";
 export type GovernanceSignalStatus = "open" | "acknowledged" | "resolved" | "dismissed" | "expired";
 export type GovernanceResolutionStatus = "action_taken" | "wont_fix" | "duplicate" | "false_positive" | "self_resolved";
@@ -674,6 +833,7 @@ export interface GovernanceSignal {
     resolved_by: string | null;
     resolved_at: string | null;
     expires_at: string | null;
+    webhook_delivery_id: string | null;
     notification_state: Record<string, unknown>;
     created_at: string;
     updated_at: string;
@@ -828,6 +988,36 @@ export declare function rotateApiKey(keyId: string): Promise<ApiKeyCreated>;
  * audit; `is_active` flips to false and `revoked_at` is timestamped.
  */
 export declare function revokeApiKey(keyId: string): Promise<void>;
+export interface LicenseValidationResult {
+    valid: boolean;
+    license_id?: string;
+    plan_id?: string;
+    feature_flags?: Record<string, boolean>;
+    limits?: Record<string, unknown>;
+    expires_at?: string;
+    next_check_seconds?: number;
+    warning?: string | null;
+    [key: string]: unknown;
+}
+/**
+ * POST /v1/license/validate — validate a license JWT for an instance.
+ *
+ * UNAUTHENTICATED by design (the license JWT IS the credential; this is a
+ * pre-login path) — sends NO auth header. Source-verified at canonical ref
+ * c18491e6 (handleLicenseValidate): the request body keys are
+ * `{ license, instance_id, instance_metadata }` (NOT `jwt`) — sending `jwt`
+ * would 400 "license is required".
+ *
+ * Returns the parsed validation result on 2xx (including the grace-period
+ * `valid:false` 200 body); throws MnemomApiError on non-2xx so the command
+ * renders `.message`/`.status`. This fixes the live H1 "[object Object]" bug:
+ * the old command-layer `err.error || "unknown"` string-coerced the nested
+ * `{code,message}` object that the enforce hook puts on the wire.
+ *
+ * `license deactivate` may reuse this (best-effort, fire-and-forget) by
+ * catching the throw at the command layer.
+ */
+export declare function validateLicense(jwt: string, instanceId: string, instanceMetadata?: Record<string, unknown>): Promise<LicenseValidationResult>;
 export interface RecipeReportInput {
     type: "fn" | "fp";
     summary: string;