Skip to content
Python
11.1 KB
Raw Blame
import type {
  ConnectionSetupCapability,
  ConnectionSetupExecute,
  ConnectionSetupJournal,
  ConnectionSetupPreview,
  ConnectionSetupResult,
  ConnectionSetupSelection,
} from "@one-memory/contracts";
import type { LanguagePreference, LanguageSnapshot } from "@one-memory/i18n";
import type { DebugLogSnapshot } from "./debug-log-types.js";

export type RecallPermissionTool =
  | "om_recall"
  | "om_ask"
  | "om_conversations"
  | "om_matters"
  | "om_diagnostic_trace";

/** Display-only local receipt. Never an authorization token. */
export interface RecallPermissionReceipt {
  readonly installationId: string;
  readonly hostId: string;
  readonly revision: number;
  readonly status: "install-only" | "approved" | "revoked";
  readonly allowedTools: readonly RecallPermissionTool[];
  readonly allowedScopes: readonly string[];
}

export interface RecallPermissionStatus {
  hostId: string;
  state:
    | "not-installed"
    | "install-only"
    | "approved"
    | "revoked"
    | "relink-required"
    | "unavailable"
    | "unsupported";
  reason:
    | "installation_incomplete"
    | "credential_missing_or_changed"
    | "legacy_installation"
    | "managed_config_changed"
    | "permission_store_unavailable"
    | "unsupported_transport"
    | null;
  receipt: RecallPermissionReceipt | null;
}

export interface SyncHookStatus {
  hostId: string;
  state:
    | "unsupported"
    | "connection-required"
    | "not-installed"
    | "installed"
    | "modified"
    | "unavailable";
  reason: string | null;
}

export interface SyncHookPreview {
  hostId: string;
  operation: "install" | "uninstall";
  installationId: string;
  revision: number;
  fingerprint: string;
  files: Array<{
    path: string;
    action: "create" | "update" | "remove";
    owner: "host" | "one-memory";
  }>;
}

export interface ApplySyncHookInput {
  operation: "install" | "uninstall";
  installationId: string;
  revision: number;
  fingerprint: string;
  userConfirmed: true;
}

export interface SetRecallPermissionInput {
  installationId: string;
  expectedRevision: number;
  allowedTools: readonly RecallPermissionTool[];
  allowedScopes: readonly string[];
  userConfirmed: true;
}

export interface RevokeRecallPermissionInput {
  installationId: string;
  expectedRevision: number;
  userConfirmed: true;
}

export interface RecallHostStatus {
  hostId: string;
  label: string;
  /** Whether this host is actually installed on the machine. */
  present: boolean;
  /** Whether our files are there and unaltered. Not whether recall works.
   *
   * The two came apart once: three hosts were installed against a plausible
   * but wrong discovery path, every file intact, and recalled nothing. So the
   * link's own verdict is carried separately.
   */
  installed: boolean;
  /** Optional only for renderers attached to an older desktop shell. */
  permission?: RecallPermissionStatus;
  /** Launch request support, not a verified input-box prefill receipt. */
  handoff?: "open" | "copy";
  /** What the last self-check said, recorded at install time.
   *
   * Recorded rather than live, because probing starts a process per host and
   * this list is refreshed often.
   */
  selfCheck: { state: string; detail: string; probed_at: string } | null;
  /** Whether the call-rule skill on disk still matches what we ship (R-33). */
  skillDrift: {
    state: "in_sync" | "stale" | "modified";
    installedVersion: number | null;
    currentVersion: number;
  } | null;
}

/** A fresh self-check of one host, and whether it can be repaired. */
export interface RecallLinkCheck {
  hostId: string;
  probe: {
    state: "wired" | "unreachable" | "reachable_but_blind";
    detail: string;
    discoveryPath: string | null;
    discoveryPresent: boolean;
    probedAt: string;
  };
  skill: {
    state: "in_sync" | "stale" | "modified";
    installedVersion: number | null;
    currentVersion: number;
    detail: string;
  } | null;
  /** Non-null only when the host points somewhere other than where the app
   * writes. Null when the app is merely not running: the entry is already
   * correct then, and offering to repair it would send the user to fix the
   * wrong thing. */
  repoint: { from: string | null; to: string } | null;
}

/** The lines one install would change, and a little of the text around them. */
export interface RecallPreviewHunk {
  /** 1-based line number in the file as it stands now. */
  startLine: number;
  removed: string[];
  added: string[];
  contextBefore: string[];
  contextAfter: string[];
}

export interface RecallPreviewFile {
  path: string;
  /** `host` is the other program's own settings file; `one-memory` is ours. */
  owner: "host" | "one-memory";
  existed: boolean;
  /** Null when this file is not changed at all. */
  hunk: RecallPreviewHunk | null;
}

export interface RecallInstallPreview {
  hostId: string;
  hostLabel: string;
  files: RecallPreviewFile[];
  /** Identifies the on-disk state this preview describes. */
  fingerprint: string;
}

export interface SkillSyncPreview extends RecallInstallPreview {
  upToDate: boolean;
  conflict: boolean;
  requiresConfirmation?: boolean;
  drift?: {
    state: "in_sync" | "stale" | "modified";
    installedVersion: number | null;
    currentVersion: number;
  };
}

export interface RecallUninstallFile {
  path: string;
  owner: "host" | "one-memory";
  /** Null when this file is not changed at all, or when it is removed. */
  hunk: RecallPreviewHunk | null;
  /** The whole file goes, rather than a region of it changing. */
  deleted: boolean;
}

/** A place that may still hold part of the connection, which the desktop
 * could not settle; a person has to look at it. */
export interface RecallRemovalFinding {
  path: string;
  where: string;
}

export interface RecallUninstallPreview {
  hostId: string;
  hostLabel: string;
  files: RecallUninstallFile[];
  /** Non-empty when the app cannot be called off without a person looking;
   * nothing is removed then. Absent from older desktops. */
  review?: RecallRemovalFinding[];
  /** Identifies the on-disk state this preview describes. */
  fingerprint: string;
}

declare global {
  interface Window {
    oneMemory?: {
      getBuildInfo?(): {
        version: string;
        buildNumber: string;
        commit: string;
      };
      getLanguagePreference?(): Promise<LanguageSnapshot>;
      setLanguagePreference?(
        preference: LanguagePreference,
      ): Promise<LanguageSnapshot>;
      onLanguagePreferenceChanged?(
        listener: (snapshot: LanguageSnapshot) => void,
      ): () => void;
      getDebugLogs?(): Promise<DebugLogSnapshot>;
      /** Renderer end of the four-step UI/kernel trace. */
      logUiTrace?(input: {
        action: string;
        page: string;
        phase: "action" | "result";
        status?: string;
        reason?: string;
        count?: number;
        duration_ms?: number;
        trace_id?: string;
      }): Promise<{ state: "logged" }>;
      markDiagnosticIncident?(description?: string): Promise<{
        incident_id: string;
        session_id: string;
        timestamp: string;
      }>;
      exportDiagnostics?(): Promise<{
        state: "exported";
        filename?: string;
        path?: string;
        file_count?: number;
      }>;
      getBackgroundHealth?(): Promise<{
        state: "healthy" | "stopped" | "degraded" | "untrusted" | "unknown";
        code: string;
        core: "running" | "stopped" | "unhealthy" | "untrusted" | "unknown";
        broker:
          | "running"
          | "stopped"
          | "unhealthy"
          | "untrusted"
          | "not_checked";
        instanceId?: string;
      }>;
      restartBackground?(): Promise<{ state: "restarted" }>;
      getConnectionSetupCapability?(): Promise<ConnectionSetupCapability>;
      previewConnectionSetup?(
        input: ConnectionSetupSelection,
      ): Promise<ConnectionSetupPreview>;
      executeConnectionSetup?(
        input: ConnectionSetupExecute,
      ): Promise<ConnectionSetupResult>;
      getConnectionSetupReceipt?(
        operationId: string,
      ): Promise<ConnectionSetupJournal | null>;
      getLoginPreference?(): Promise<{
        supported: boolean;
        enabled: boolean;
        status: string;
      }>;
      setLoginPreference?(input: {
        openAtLogin: boolean;
        userConfirmed: true;
      }): Promise<{ supported: boolean; enabled: boolean; status: string }>;
      requestQuit?(confirmed: true): Promise<void>;
      pickSourceDirectory?(sourceId: string): Promise<{
        cancelled: boolean;
        path: string | null;
      }>;
      getDisplayPreferences?(): Promise<{
        reduceMotion: boolean;
        reduceTransparency: boolean;
        revision: number;
      }>;
      onDisplayPreferencesChanged?(
        listener: (preferences: {
          reduceMotion: boolean;
          reduceTransparency: boolean;
          revision: number;
        }) => void,
      ): () => void;
      getApiToken(): Promise<string>;
      getApiBaseUrl(): Promise<string>;
      createCustomHarnessSkill?(displayName: string): Promise<{
        displayName: string;
        expiresAt: string;
        skill: string;
      }>;
      copyText?(text: string): Promise<void>;
      getRecallHosts(): Promise<RecallHostStatus[]>;
      getSyncHookStatus?(hostId: string): Promise<SyncHookStatus>;
      previewSyncHook?(
        hostId: string,
        operation: "install" | "uninstall",
      ): Promise<SyncHookPreview>;
      applySyncHook?(
        hostId: string,
        input: ApplySyncHookInput,
      ): Promise<SyncHookStatus>;
      /** Absent in older shells; never infer approval from installation. */
      getRecallPermission?(hostId: string): Promise<RecallPermissionStatus>;
      setRecallPermission?(
        hostId: string,
        input: SetRecallPermissionInput,
      ): Promise<RecallPermissionStatus>;
      revokeRecallPermission?(
        hostId: string,
        input: RevokeRecallPermissionInput,
      ): Promise<RecallPermissionStatus>;
      previewRecallInstall(hostId: string): Promise<RecallInstallPreview>;
      probeRecallHost(hostId: string): Promise<RecallLinkCheck>;
      previewSkillSync(hostId: string): Promise<SkillSyncPreview>;
      applySkillSync(
        hostId: string,
        approved?: string,
        overwriteModified?: boolean,
      ): Promise<{ hostId: string; synced: boolean }>;
      /** Repoint installed hosts at the running app without reissuing grants. */
      repairRecallCommands?(): Promise<string[]>;
      installRecall(
        hostId: string,
        approved?: string,
      ): Promise<{
        hostId: string;
        installed: boolean;
        permission?: RecallPermissionStatus;
      }>;
      /** Start a chat in another app with these memories already typed in.
       * `opened: false` means that app takes no starting prompt. */
      openHandoff(
        hostId: string,
        prompt: string,
      ): Promise<{ opened: boolean; reason: string | null }>;
      previewRecallUninstall(hostId: string): Promise<RecallUninstallPreview>;
      uninstallRecall(
        hostId: string,
        approved?: string,
      ): Promise<{
        hostId: string;
        installed: boolean;
        permission?: RecallPermissionStatus;
      }>;
    };
  }
}