@geteigen/cli 0.0.0-stage → 3.1.0

package/dist/shared/brain.d.ts

@@ -0,0 +1,353 @@
+/**
+ * Supermemory-native brain contracts.
+ *
+ * Supermemory is the only durable memory store. Steer keeps a lightweight
+ * index row per document (ids, tag, kind, status, provenance, a short preview)
+ * plus policy, receipts, and audit — never memory bodies as source of truth.
+ */
+export declare const BRAIN_KINDS: readonly ["goal", "decision", "constraint", "discovery", "handoff", "feedback", "note"];
+export type BrainKind = (typeof BRAIN_KINDS)[number];
+export declare const BRAIN_STATUSES: readonly ["proposed", "active", "archived"];
+export type BrainStatus = (typeof BRAIN_STATUSES)[number];
+export declare const BRAIN_SCOPES: readonly ["shared", "room", "user", "repo", "issue", "swarm", "agent"];
+export type BrainScope = (typeof BRAIN_SCOPES)[number];
+export declare const BRAIN_SOURCES: readonly ["human", "agent_proposed", "auto_run", "chat_ingest", "handoff", "issue_outcome", "swarm_summary", "connector", "migration", "dream", "feature", "digest"];
+export type BrainSource = (typeof BRAIN_SOURCES)[number];
+export type DreamingMode = "dynamic" | "instant";
+/**
+ * Auto-remember: after each run Steer saves a cleaned session record to room +
+ * repo memory and Supermemory extracts, versions and dedupes the facts — no
+ * approval clicks. "off" disables it.
+ */
+export type AutoMemoryPolicy = "off" | "auto";
+/** Legacy "propose" / "ingest_chat" (approval-gated) map to "auto". */
+export declare function normalizeAutoMemory(raw: unknown, fallback?: AutoMemoryPolicy): AutoMemoryPolicy;
+export type ArchivePolicy = "exclude" | "delete";
+export type IngestStatus = "queued" | "processing" | "done" | "failed";
+export interface BrainScopeRef {
+    scope: BrainScope;
+    /** roomId / userId / repoKey / issueId / swarmId / agentId. Absent for `shared`. */
+    id?: string | null;
+}
+export interface BrainMemoryInfo {
+    id: string;
+    orgId: string;
+    containerTag: string;
+    scope: BrainScope;
+    scopeId: string | null;
+    /** Supermemory document id. Null while a proposal only lives in the inbox tag. */
+    docId: string | null;
+    /** Inbox (staging) document for proposals — never searched at run time. */
+    inboxDocId: string | null;
+    kind: BrainKind;
+    title: string;
+    /** Short cached preview for list rendering. Full body is fetched from Supermemory. */
+    preview: string;
+    /** Present on detail reads (fetched from Supermemory). */
+    content?: string;
+    status: BrainStatus;
+    pinned: boolean;
+    source: BrainSource;
+    repoUrl: string | null;
+    repoKey: string | null;
+    evidenceRefs: string[];
+    supersedesId: string | null;
+    supersededById: string | null;
+    createdByUserId: string | null;
+    createdByName?: string | null;
+    createdByAgentId: string | null;
+    decidedByUserId: string | null;
+    ingestStatus: IngestStatus;
+    usedInRuns: number;
+    /** Stable topic key; a newer fact with the same key replaces this one. */
+    subjectKey?: string | null;
+    /** People the memory is about or came from (user ids). */
+    people?: string[];
+    /** When the underlying event happened (not when it was saved). */
+    eventAt?: number | null;
+    episodeId?: string | null;
+    featureId?: string | null;
+    roomId?: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface BrainSimilarHit {
+    id: string;
+    memoryId: string | null;
+    text: string;
+    similarity: number;
+    title?: string | null;
+}
+export interface BrainInferredCandidate {
+    id: string;
+    containerTag: string;
+    scope: BrainScope;
+    scopeId: string | null;
+    memory: string;
+    parentCount: number;
+    createdAt: number;
+}
+export interface BrainSettings {
+    orgId: string;
+    supermemoryConfigured: boolean;
+    keySource: "org" | "steer_managed" | "none";
+    keyHint: string | null;
+    dreamingMode: DreamingMode;
+    autoMemory: AutoMemoryPolicy;
+    archivePolicy: ArchivePolicy;
+    searchLimit: number;
+    searchThreshold: number;
+    budgetChars: number;
+    includeProfiles: boolean;
+    rerank: boolean;
+    /** Admin consent for Supermemory-side data connectors into shared/repo tags. */
+    connectorsEnabled: boolean;
+    /** Admin opt-in: remember people-to-people Space chat (members see a notice). */
+    spaceCapture: boolean;
+    epoch: number;
+    epochUpdatedAt: number;
+}
+export declare const DEFAULT_BRAIN_SETTINGS: Omit<BrainSettings, "orgId" | "supermemoryConfigured" | "keySource" | "keyHint" | "epoch" | "epochUpdatedAt">;
+export interface BrainReceiptInfo {
+    id: string;
+    orgId: string;
+    runKind: "room" | "issue" | "swarm";
+    runRef: string;
+    agentId: string | null;
+    steeringUserId: string | null;
+    tags: string[];
+    tagEpochs: Record<string, number>;
+    queryHash: string;
+    memoryIds: string[];
+    resultIds: string[];
+    titles: string[];
+    profileAt: number | null;
+    requestIds: string[];
+    chars: number;
+    createdAt: number;
+    stale?: boolean;
+}
+export interface BrainAuditInfo {
+    id: string;
+    orgId: string;
+    actorUserId: string | null;
+    actorName?: string | null;
+    action: string;
+    target: string | null;
+    meta: Record<string, unknown>;
+    createdAt: number;
+}
+export interface BrainUsageInfo {
+    month: string;
+    operations: Record<string, number>;
+    total: number;
+}
+export interface BrainOverview {
+    settings: BrainSettings;
+    counts: {
+        active: number;
+        proposed: number;
+        archived: number;
+        byScope: Record<BrainScope, number>;
+        byKind: Record<string, number>;
+    };
+    repos: Array<{
+        repoKey: string;
+        repoUrl: string | null;
+        count: number;
+    }>;
+    usage: BrainUsageInfo;
+    recentReceipts: BrainReceiptInfo[];
+}
+export interface BrainGraphNode {
+    id: string;
+    kind: BrainKind | "scope";
+    label: string;
+    scope: BrainScope;
+    status?: BrainStatus;
+    pinned?: boolean;
+    weight: number;
+}
+export interface BrainGraphEdge {
+    from: string;
+    to: string;
+    rel: "in_scope" | "supersedes" | "same_repo" | "evidence";
+}
+export interface BrainGraph {
+    nodes: BrainGraphNode[];
+    edges: BrainGraphEdge[];
+}
+/** Payload for `memory-updated`, `memory-proposal` socket events. */
+export interface BrainMemoryEvent {
+    orgId: string;
+    memory: BrainMemoryInfo;
+    epoch: number;
+}
+export interface BrainEpochEvent {
+    orgId: string;
+    epoch: number;
+    tags: string[];
+}
+export declare const TAG_PREFIX = "steer:org:";
+export declare function isBrainKind(v: unknown): v is BrainKind;
+export declare function isBrainStatus(v: unknown): v is BrainStatus;
+export declare function isBrainScope(v: unknown): v is BrainScope;
+export declare function isBrainSource(v: unknown): v is BrainSource;
+/**
+ * Normalize any git remote to a stable, tag-safe key:
+ * `https://github.com/Acme/Web.git` → `github.com-acme-web`.
+ */
+export declare function normalizeRepoKey(repoUrl: string | null | undefined): string | null;
+export declare function containerTagFor(orgId: string, ref: BrainScopeRef): string;
+/**
+ * Staging tag for proposals and raw ingest (chat, handoffs). Supermemory
+ * dreams over these documents but run-time retrieval never reads them, which
+ * structurally keeps proposals out of search/profile until accepted.
+ */
+export declare function inboxTagFor(orgId: string, ref: BrainScopeRef): string;
+export declare function parseContainerTag(tag: string): {
+    org: string;
+    scope: BrainScope;
+    id: string | null;
+    inbox: boolean;
+} | null;
+/** Server-side guard: every Supermemory call must carry a tag for this org. */
+export declare function tagBelongsToOrg(tag: string, orgId: string): boolean;
+export type BrainRunKind = "room" | "issue" | "swarm" | "research";
+export interface BrainReadContext {
+    kind: BrainRunKind;
+    roomId?: string | null;
+    issueId?: string | null;
+    swarmId?: string | null;
+    repoUrl?: string | null;
+    steeringUserId?: string | null;
+    agentId?: string | null;
+    /** Composer override: only the room tag. */
+    onlyRoom?: boolean;
+    /** Composer override: include the workspace (shared) brain. Default true. */
+    includeWorkspace?: boolean;
+    /** Include the steering user's personal tag. Default true for rooms, false for issues. */
+    includePersonal?: boolean;
+    /** Include long-lived agent notes. */
+    includeAgent?: boolean;
+}
+/**
+ * Read union by context. Never includes another user's personal tag: the only
+ * `user` scope ever returned is the steering user's own.
+ */
+export declare function readScopesFor(ctx: BrainReadContext): BrainScopeRef[];
+export type BrainWriteIntent = "room_note" | "personal_note" | "org_decision" | "repo_discovery" | "issue_outcome" | "swarm_artifact" | "agent_note";
+/** Write narrowest scope: each intent maps to exactly one tag. */
+export declare function writeScopeFor(intent: BrainWriteIntent, ids: {
+    roomId?: string | null;
+    userId?: string | null;
+    repoUrl?: string | null;
+    issueId?: string | null;
+    swarmId?: string | null;
+    agentId?: string | null;
+}): BrainScopeRef;
+/** Repo-bound memories only inject when the run's repo matches. */
+export declare function repoMatches(memoryRepoKey: string | null, runRepoUrl: string | null | undefined): boolean;
+export interface MemoryPromptItem {
+    ref: string;
+    kind: string;
+    title?: string | null;
+    text: string;
+    scope: BrainScope;
+    pinned?: boolean;
+    /** Who / when / where it came from, e.g. "Priya · 2026-10-01 · PR#140". */
+    provenance?: string | null;
+}
+export interface MemoryPromptInput {
+    epoch: number;
+    profile: Array<{
+        scope: BrainScope;
+        lines: string[];
+    }>;
+    pinned: MemoryPromptItem[];
+    hits: MemoryPromptItem[];
+    budgetChars: number;
+    integrations?: string[];
+}
+/** Strip anything that could close or spoof the memory envelope. */
+export declare function neutralizeEnvelope(text: string): string;
+/**
+ * Deterministic ordering: pinned → search index → profile, each line capped,
+ * the whole block capped at `budgetChars`. Pinned rules are the only full
+ * text; everything else is an id + title index the agent can expand with the
+ * memory tools. Returns the ids actually included.
+ */
+export declare function renderMemoryBlock(input: MemoryPromptInput): {
+    text: string;
+    includedRefs: string[];
+    chars: number;
+};
+export declare function hashQuery(q: string): string;
+export declare function brainKindLabel(kind: BrainKind): string;
+export declare function brainScopeLabel(scope: BrainScope): string;
+export declare const BRAIN_EVENT_KINDS: readonly ["message.space", "message.thread", "message.ask", "message.agent_final", "run.started", "run.completed", "pr.opened", "pr.merged", "pr.closed", "issue.created", "issue.status_changed", "issue.finished", "swarm.started", "swarm.done", "memory.manual", "member.joined"];
+export type BrainEventKind = (typeof BRAIN_EVENT_KINDS)[number];
+export type BrainEventVisibility = "team" | "room" | "private";
+export interface BrainEventInfo {
+    id: string;
+    orgId: string;
+    kind: BrainEventKind;
+    actorUserId: string | null;
+    actorName?: string | null;
+    actorAgentId: string | null;
+    people: string[];
+    roomId: string | null;
+    threadId: string | null;
+    issueId: string | null;
+    swarmId: string | null;
+    repoKey: string | null;
+    ref: string | null;
+    text: string;
+    meta: Record<string, unknown>;
+    visibility: BrainEventVisibility;
+    occurredAt: number;
+    episodeId: string | null;
+}
+export declare const EPISODE_KINDS: readonly ["run", "space", "thread", "issue", "swarm", "pr"];
+export type EpisodeKind = (typeof EPISODE_KINDS)[number];
+export type EpisodeStatus = "open" | "ready" | "processing" | "done" | "failed" | "skipped";
+export declare const EPISODE_CLASSES: readonly ["team_work", "repo_knowledge", "decision", "personal", "off_topic", "sensitive"];
+export type EpisodeClass = (typeof EPISODE_CLASSES)[number];
+export declare const FACT_TYPES: readonly ["decision", "constraint", "discovery", "shipped", "feature_progress", "open_question", "preference", "status"];
+export type FactType = (typeof FACT_TYPES)[number];
+/** How a fact type is filed among the memory kinds the UI already knows. */
+export declare function factKind(type: FactType): BrainKind;
+export type FeatureStatus = "in_progress" | "in_review" | "shipped" | "abandoned";
+export interface BrainFeatureInfo {
+    id: string;
+    orgId: string;
+    repoKey: string;
+    title: string;
+    slug: string;
+    status: FeatureStatus;
+    startedAt: number;
+    prOpenedAt: number | null;
+    shippedAt: number | null;
+    prUrls: string[];
+    people: string[];
+    roomIds: string[];
+    issueIds: string[];
+    summary: string;
+    updatedAt: number;
+}
+export interface BrainTimelineQuery {
+    from?: number;
+    to?: number;
+    people?: string[];
+    repoKey?: string | null;
+    kinds?: BrainEventKind[];
+    limit?: number;
+}
+export interface BrainTimelineResult {
+    events: BrainEventInfo[];
+    features: BrainFeatureInfo[];
+}
+/** Display day for a timestamp (UTC, YYYY-MM-DD). */
+export declare function dayOf(ts: number): string;
+/** URL-safe, stable slug for feature titles. */
+export declare function featureSlug(title: string): string;