@mnemom/mnemom 0.9.1 → 0.11.0

package/dist/lib/api.d.ts

@@ -77,6 +77,166 @@ export interface AgentListItem {
     key_prefix?: string | null;
 }
 export declare function listAgents(): Promise<AgentListItem[]>;
+export interface OrgListItem {
+    org_id: string;
+    name: string;
+    slug: string;
+    is_personal: boolean;
+    is_owner: boolean;
+    role: string | null;
+    billing_email?: string | null;
+    company_name?: string | null;
+    accepted_at?: string | null;
+    created_at?: string | null;
+}
+export interface PersonalOrgRef {
+    org_id: string;
+    is_personal: true;
+    just_provisioned?: boolean;
+}
+/**
+ * GET /v1/orgs — list every org the user is a member of, including the
+ * personal-org-of-one (per ADR-044 Option A, GitHub model). Personal sorts
+ * first; multi-user orgs follow.
+ */
+export declare function listMyOrgs(): Promise<OrgListItem[]>;
+/**
+ * GET /v1/auth/me/personal-org — accessor for the user's personal org.
+ * Idempotent: lazily provisions for legacy accounts that pre-date the
+ * mnemom-api migration 161 backfill.
+ */
+export declare function getMyPersonalOrg(): Promise<PersonalOrgRef>;
+export interface TeamListItem {
+    team_id: string;
+    name: string;
+    org_id: string;
+    org_name?: string | null;
+    description?: string | null;
+    status?: string;
+    member_count?: number;
+    visibility?: string;
+}
+export interface TeamDetail {
+    team_id: string;
+    name: string;
+    org_id: string;
+    description?: string | null;
+    status?: string;
+    member_count?: number;
+    visibility?: string;
+    avatar_url?: string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+}
+export interface TeamTemplateBody {
+    team_id: string;
+    org_id: string;
+    name?: string;
+    template: Record<string, unknown> | null;
+    enabled: boolean;
+    agents_flagged_for_recompose?: number;
+    deleted?: boolean;
+}
+export type TeamTemplateKind = "alignment" | "protection";
+/**
+ * GET /v1/orgs/:org_id/teams for every org the user is a member of,
+ * concatenated. The CLI consumer that just wants "every team I can see"
+ * doesn't need to know about org boundaries; team_id is unique anyway.
+ * Returns the flat list with org_name attached for display.
+ */
+export declare function listMyTeams(): Promise<TeamListItem[]>;
+/**
+ * GET /v1/teams/:team_id — fetch a single team's row. Returns the team
+ * detail including org_id (which the CLI uses to disambiguate team_id
+ * collisions across orgs in error messages).
+ */
+export declare function getTeam(teamId: string): Promise<TeamDetail>;
+/**
+ * GET /v1/teams/:team_id/(alignment|protection)-template — read the
+ * current team-scope template + its enabled flag. Returns the wire body
+ * verbatim. Empty for teams that have no template set yet (template:
+ * null, enabled: false).
+ */
+export declare function getTeamTemplate(teamId: string, kind: TeamTemplateKind): Promise<TeamTemplateBody>;
+/**
+ * PUT /v1/teams/:team_id/(alignment|protection)-template — write the
+ * team-scope template. Body is YAML or JSON template content; the API
+ * accepts either via Content-Type. Idempotency-Key is required (per the
+ * idempotency-with-body-hash discipline in the API).
+ *
+ * On success returns the post-write team template body, including
+ * agents_flagged_for_recompose so the caller can surface the fan-out
+ * count to the user.
+ */
+export declare function putTeamTemplate(teamId: string, kind: TeamTemplateKind, yamlBody: string): Promise<TeamTemplateBody>;
+/**
+ * DELETE /v1/teams/:team_id/(alignment|protection)-template — clear the
+ * template. Idempotent (deleting an already-cleared template is a 200).
+ * Returns the post-delete team template body with deleted=true and the
+ * recompose fan-out count.
+ */
+export declare function deleteTeamTemplate(teamId: string, kind: TeamTemplateKind): Promise<TeamTemplateBody>;
+/**
+ * POST /v1/teams/:team_id/(alignment|protection)-template/preview-compose
+ * — dry-run the composer with the supplied draft against the team's
+ * current org+platform context. Returns the composed canonical output
+ * plus per-field conflicts where the draft was tightened by the
+ * org/platform floor. No DB writes.
+ */
+export declare function previewComposeTeamTemplate(teamId: string, kind: TeamTemplateKind, yamlBody: string): Promise<{
+    composed: Record<string, unknown>;
+    conflicts: unknown;
+}>;
+export interface TeamAdminGrant {
+    user_id: string;
+    granted_by: string;
+    granted_at: string;
+}
+export interface TeamAdminListResponse {
+    team_id: string;
+    org_id: string;
+    admins: TeamAdminGrant[];
+    count: number;
+}
+export interface TeamAdminGrantResponse {
+    team_id: string;
+    user_id: string;
+    granted_by: string;
+    granted_at: string;
+    revoked_at: string | null;
+    idempotent_noop: boolean;
+}
+export interface TeamAdminRevokeResponse {
+    team_id: string;
+    user_id: string;
+    revoked: boolean;
+    revoked_at?: string;
+    revoked_by?: string;
+    idempotent_noop?: boolean;
+}
+/**
+ * POST /v1/teams/:team_id/admins — grant team_admin role on a team.
+ *
+ * Per ADR-046 §3: callable by org_owner / org_admin only. The target
+ * user must already be a member of the team's org; cross-org grants 403.
+ * Idempotent — re-granting an already-active grant returns 200 with
+ * `idempotent_noop: true`.
+ */
+export declare function grantTeamAdmin(teamId: string, userId: string): Promise<TeamAdminGrantResponse>;
+/**
+ * DELETE /v1/teams/:team_id/admins/:user_id — revoke a team_admin grant.
+ *
+ * Per ADR-046 §3: callable by org_owner / org_admin OR self-revoke (the
+ * team_admin revokes their own grant — the only self-mutation). Idempotent
+ * — revoking an absent or already-revoked grant returns 200 with
+ * `idempotent_noop: true` and no audit row.
+ */
+export declare function revokeTeamAdmin(teamId: string, userId: string): Promise<TeamAdminRevokeResponse>;
+/**
+ * GET /v1/teams/:team_id/admins — list active team_admin grants on a team.
+ * Any member of the team's org can read.
+ */
+export declare function listTeamAdmins(teamId: string): Promise<TeamAdminListResponse>;
 /**
  * Look up an agent in the authenticated user's account by name.
  * Tries exact match first, then single partial match.
@@ -253,3 +413,419 @@ export declare function putProtectionCard(agentId: string, body: string, content
  * Otherwise resolves the name from the authenticated user's agent list.
  */
 export declare function resolveAgentId(agentName?: string): Promise<string>;
+export interface PostureBody {
+    posture_schema_version: "v1.0";
+    sideband: {
+        coherence: {
+            enabled: boolean;
+            cadence_seconds: number;
+            fire_on: {
+                pairwise_governance_floor_below: number | null;
+                conflict_edge_count_exceeds: number | null;
+                outlier_agents_count_exceeds: number | null;
+            };
+            severity_on_fire: "low" | "medium" | "high" | "critical";
+        };
+        fault_line: {
+            enabled: boolean;
+            cadence_seconds: number;
+            severity_floor: "low" | "medium" | "high" | "critical";
+            use_reputation_scores: boolean;
+            severity_on_fire: "low" | "medium" | "high" | "critical";
+        };
+        fleet: {
+            enabled: boolean;
+            cadence_seconds: number;
+            patterns: {
+                outliers: boolean;
+                min_pair_score_below: number | null;
+                cluster_partition: boolean;
+            };
+            severity_on_fire: "low" | "medium" | "high" | "critical";
+        };
+    };
+    fleet_identification: {
+        by: "team_membership";
+    };
+    fan_out: {
+        rule: "per_named_affected_agent";
+    };
+}
+export interface PostureSummary {
+    posture_id: string;
+    slug: string;
+    name: string;
+    description: string | null;
+    scope: "platform" | "org";
+    org_id: string | null;
+    is_default: boolean;
+    current_revision_id: string | null;
+    body: PostureBody | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+export interface PostureRevision {
+    revision_id: string;
+    posture_id: string;
+    revision_no: number;
+    body: PostureBody;
+    change_summary: string | null;
+    authored_by: string | null;
+    authored_at: string;
+}
+export interface PostureDiffEntry {
+    path: string;
+    op: "added" | "removed" | "changed";
+    before: unknown;
+    after: unknown;
+}
+/** GET /v1/postures — list visible postures. */
+export declare function listPostures(opts: {
+    orgId?: string;
+    includePlatform?: boolean;
+    includeDeleted?: boolean;
+}): Promise<PostureSummary[]>;
+/** GET /v1/postures/:id — read posture with current revision body. */
+export declare function getPosture(postureId: string): Promise<PostureSummary>;
+/** GET /v1/postures/:id/revisions — list revisions, newest first. */
+export declare function listPostureRevisions(postureId: string): Promise<PostureRevision[]>;
+/** GET /v1/postures/:id/diff?from=N&to=M — structural diff. */
+export declare function diffPostureRevisions(postureId: string, fromNo: number, toNo: number): Promise<{
+    from: {
+        revision_no: number;
+    };
+    to: {
+        revision_no: number;
+    };
+    changes: PostureDiffEntry[];
+}>;
+interface CreatePostureInput {
+    scope: "org" | "platform";
+    org_id?: string;
+    slug: string;
+    name: string;
+    description?: string | null;
+    body: PostureBody;
+    change_summary?: string | null;
+}
+/** POST /v1/postures — create new posture (org-scope only via REST). */
+export declare function createPosture(input: CreatePostureInput): Promise<PostureSummary>;
+interface UpdatePostureInput {
+    body: PostureBody;
+    change_summary?: string | null;
+    name?: string;
+    description?: string | null;
+}
+/** PUT /v1/postures/:id — write a new revision (forward-only). */
+export declare function updatePosture(postureId: string, input: UpdatePostureInput): Promise<PostureSummary>;
+interface ClonePostureInput {
+    org_id: string;
+    slug?: string;
+    name?: string;
+    description?: string | null;
+}
+/** POST /v1/postures/:id/clone — clone source to org-scope. */
+export declare function clonePosture(postureId: string, input: ClonePostureInput): Promise<PostureSummary>;
+/** DELETE /v1/postures/:id — soft-delete (refuses if assigned). */
+export declare function deletePosture(postureId: string): Promise<void>;
+/** POST /v1/postures/:id/assign — assign to a team. */
+export declare function assignPosture(postureId: string, teamId: string, pinRevisionNo?: number | null): Promise<{
+    posture_id: string;
+    team_id: string;
+    replaced_prior: boolean;
+}>;
+/** DELETE /v1/postures/:id/assignments/:team_id — remove an assignment. */
+export declare function unassignPosture(postureId: string, teamId: string): Promise<void>;
+/** POST /v1/postures/:id/preview-compose — preview effective for a team. */
+export declare function previewComposePosture(postureId: string, teamId: string): Promise<{
+    team_id: string;
+    org_id: string;
+    composed: {
+        body: PostureBody;
+        scopes_applied: Array<{
+            scope: string;
+            posture_id: string;
+            revision_no: number;
+        }>;
+    };
+}>;
+export interface SidebandAdvisory {
+    id: string;
+    agent_id: string;
+    source: string;
+    source_ref: Record<string, unknown> | null;
+    nudge_content: string;
+    concerns_summary: string;
+    status: "pending" | "consumed" | "expired";
+    created_at: string;
+    consumed_at: string | null;
+    expires_at: string;
+}
+export interface SidebandCoverageSummary {
+    axis: "coherence" | "fault_line" | "fleet";
+    total_swept: number;
+    total_fired: number;
+    total_skipped: number;
+    last_swept_at: string | null;
+    last_outcome: string | null;
+}
+export interface SidebandCoverageRow {
+    team_id: string;
+    axis: string;
+    day: string;
+    swept_count: number;
+    fired_count: number;
+    skipped_count: number;
+    last_swept_at: string;
+    last_outcome: string;
+    last_duration_ms: number | null;
+}
+/**
+ * GET /v1/agents/:id/sideband-advisories
+ *
+ * Lists pending_advisories rows where source LIKE 'sideband.%' for the
+ * given agent. Default page 50, max 200. Optional ?since=<ISO> filter.
+ */
+export declare function listSidebandAdvisoriesForAgent(agentId: string, opts?: {
+    limit?: number;
+    since?: string;
+}): Promise<{
+    agent_id: string;
+    advisories: SidebandAdvisory[];
+}>;
+/**
+ * GET /v1/teams/:id/sideband-advisories
+ *
+ * Lists pending_advisories rows for any agent that is a current member of
+ * the team. Default page 100, max 500. Optional ?since=<ISO> filter.
+ */
+export declare function listSidebandAdvisoriesForTeam(teamId: string, opts?: {
+    limit?: number;
+    since?: string;
+}): Promise<{
+    team_id: string;
+    advisories: SidebandAdvisory[];
+}>;
+/**
+ * GET /v1/teams/:id/sideband-coverage
+ *
+ * Compliance-grade proof-of-coverage for a team — last 30 days of
+ * per-axis sweep aggregates + heartbeat. Returns per-axis summary +
+ * raw rows.
+ */
+export declare function getTeamSidebandCoverage(teamId: string): Promise<{
+    team_id: string;
+    window_days: number;
+    summary: SidebandCoverageSummary[];
+    rows: SidebandCoverageRow[];
+}>;
+export interface HarnessRunSummary {
+    run_id: string;
+    started_at: string;
+    finished_at: string | null;
+    git_sha: string;
+    trigger: "nightly_cron" | "manual" | "pre_deploy";
+    lane: "full" | "fast";
+    total_pairs: number;
+    passed: number;
+    failed: number;
+    warned: number;
+    cac_violations: number;
+    i10_violations: number;
+    duration_ms: number | null;
+    is_complete: boolean;
+}
+/**
+ * GET /v1/admin/safe-house/harness-state — fetch the most recent
+ * harness run per lane (full + fast). Powers `mnemom validate
+ * safe-house`. Admin-gated; returns 403 for non-mnemom-staff.
+ */
+export declare function getSafeHouseHarnessState(): Promise<{
+    full: HarnessRunSummary | null;
+    fast: HarnessRunSummary | null;
+}>;
+export type GovernanceSignalScope = "platform" | "org" | "team" | "agent";
+export type GovernanceSignalSource = "sideband.drift" | "sideband.coherence" | "sideband.fault_line" | "sideband.fleet";
+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";
+export type GovernanceNotificationChannel = "webhook" | "slack" | "email" | "pagerduty";
+export interface GovernanceSignal {
+    id: string;
+    scope: GovernanceSignalScope;
+    scope_id: string;
+    source: GovernanceSignalSource;
+    pattern_type: string;
+    severity: GovernanceSignalSeverity;
+    detected_at: string;
+    detected_by: string;
+    org_id: string;
+    team_id: string | null;
+    agent_ids: string[];
+    detail: Record<string, unknown>;
+    source_ref: Record<string, unknown>;
+    status: GovernanceSignalStatus;
+    acknowledged_by: string | null;
+    acknowledged_at: string | null;
+    acknowledged_actor_role: string | null;
+    resolution_status: GovernanceResolutionStatus | null;
+    action_taken: string | null;
+    resolved_by: string | null;
+    resolved_at: string | null;
+    expires_at: string | null;
+    notification_state: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface GovernanceDestination {
+    id: string;
+    org_id: string;
+    channel: GovernanceNotificationChannel;
+    config: Record<string, unknown>;
+    filter: Record<string, unknown>;
+    enabled: boolean;
+    display_name: string | null;
+    last_tested_at: string | null;
+    last_test_status: "ok" | "failed" | null;
+    last_test_error: string | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface GovernanceRule {
+    id: string;
+    org_id: string;
+    name: string;
+    predicate: Record<string, unknown>;
+    destination_ids: string[];
+    enabled: boolean;
+    last_fired_at: string | null;
+    fire_count: number;
+    created_at: string;
+    updated_at: string;
+}
+interface SignalListFilters {
+    source?: string;
+    severity?: string;
+    status?: string;
+    scope?: string;
+    pattern_type?: string;
+    since?: string;
+    limit?: number;
+}
+export declare function listGovernanceSignalsForOrg(orgId: string, opts?: SignalListFilters): Promise<{
+    org_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function listGovernanceSignalsForTeam(teamId: string, opts?: SignalListFilters): Promise<{
+    team_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function listGovernanceSignalsForAgent(agentId: string, opts?: SignalListFilters): Promise<{
+    agent_id: string;
+    signals: GovernanceSignal[];
+}>;
+export declare function getGovernanceSignal(id: string): Promise<GovernanceSignal>;
+export declare function acknowledgeGovernanceSignal(id: string, body?: {
+    action_taken?: string;
+}): Promise<GovernanceSignal>;
+export declare function resolveGovernanceSignal(id: string, body: {
+    resolution_status: GovernanceResolutionStatus;
+    action_taken?: string;
+}): Promise<GovernanceSignal>;
+export declare function dismissGovernanceSignal(id: string, body?: {
+    reason?: string;
+}): Promise<GovernanceSignal>;
+export declare function listGovernanceDestinations(orgId: string): Promise<{
+    org_id: string;
+    destinations: GovernanceDestination[];
+}>;
+export declare function createGovernanceDestination(orgId: string, body: {
+    channel: GovernanceNotificationChannel;
+    config: Record<string, unknown>;
+    filter?: Record<string, unknown>;
+    display_name?: string;
+    enabled?: boolean;
+}): Promise<GovernanceDestination>;
+export declare function deleteGovernanceDestination(orgId: string, destinationId: string): Promise<{
+    ok: true;
+}>;
+export declare function testGovernanceDestination(orgId: string, destinationId: string): Promise<{
+    destination_id: string;
+    channel: GovernanceNotificationChannel;
+    result: {
+        ok: boolean;
+        attempts: number;
+        delivered_at?: string;
+        last_error?: string;
+    };
+}>;
+export declare function listGovernanceRules(orgId: string): Promise<{
+    org_id: string;
+    rules: GovernanceRule[];
+}>;
+export declare function createGovernanceRule(orgId: string, body: {
+    name: string;
+    predicate: Record<string, unknown>;
+    destination_ids: string[];
+    enabled?: boolean;
+}): Promise<GovernanceRule>;
+export declare function deleteGovernanceRule(orgId: string, ruleId: string): Promise<{
+    ok: true;
+}>;
+/**
+ * Capability-based scope vocabulary (ADR-049). Mirrors the API's
+ * VALID_SCOPES exactly. Update both surfaces together when the
+ * vocabulary changes.
+ */
+export declare const API_KEY_SCOPES: readonly ["gateway", "api:read", "api:write", "admin:org", "admin:platform"];
+export type ApiKeyScope = (typeof API_KEY_SCOPES)[number];
+export declare const DEFAULT_API_KEY_SCOPES: ApiKeyScope[];
+/**
+ * Recognize legacy two-scope sets so the CLI can annotate pre-ADR-049
+ * keys appropriately. Mirror of mnemom-api `expandLegacyScopes` logic
+ * for display purposes; the auth gate handles the actual aliasing.
+ */
+export declare function isLegacyScopeSet(scopes: string[] | undefined): boolean;
+export interface ApiKeyListItem {
+    key_id: string;
+    key_prefix: string;
+    name: string;
+    scopes: string[];
+    created_at: string;
+    last_used_at: string | null;
+    org_id?: string | null;
+}
+export interface ApiKeyCreated {
+    key_id: string;
+    key: string;
+    key_prefix: string;
+    name: string;
+    scopes: string[];
+    created_at: string;
+}
+/**
+ * GET /v1/api-keys — list the caller's active personal API keys.
+ */
+export declare function listApiKeys(): Promise<ApiKeyListItem[]>;
+/**
+ * POST /v1/api-keys — mint a new personal API key with explicit scopes.
+ *
+ * Returns the full secret only on this call. The mint-time ceiling
+ * rejects admin scopes the caller is not eligible for (admin:platform
+ * for non-staff, admin:org for users not in any org-admin role).
+ */
+export declare function createApiKey(name: string, scopes: ApiKeyScope[]): Promise<ApiKeyCreated>;
+/**
+ * POST /v1/api-keys/{key_id}/rotate — atomic mint-new + revoke-old.
+ * Returns the full new secret only on this call. The new key inherits
+ * the old key's name and scopes verbatim; the old key is revoked the
+ * moment this returns.
+ */
+export declare function rotateApiKey(keyId: string): Promise<ApiKeyCreated>;
+/**
+ * DELETE /v1/api-keys/{key_id} — soft-revoke. The key row stays for
+ * audit; `is_active` flips to false and `revoked_at` is timestamped.
+ */
+export declare function revokeApiKey(keyId: string): Promise<void>;
+export {};