zam-core 0.3.13 → 0.4.1

package/dist/index.d.ts

@@ -158,6 +158,17 @@ interface ConnectionOptions {
     /** Explicit provider; overrides ZAM_DB_PROVIDER and the credentials mode. */
     provider?: DatabaseProvider;
 }
+interface DatabaseTargetInfo {
+    /** User-facing category of database target selected for this connection. */
+    kind: "local" | "turso-native" | "turso-remote" | "turso-replica";
+    /** Driver/provider that will be used for the selected target. */
+    provider: DatabaseProvider;
+    /** Local filesystem path or remote URL selected as the database target. */
+    location: string;
+    /** Turso primary URL when the selected target is an embedded replica. */
+    syncUrl?: string;
+}
+declare function getDatabaseTargetInfo(options?: ConnectionOptions): DatabaseTargetInfo;
 /**
  * Open (or create) the ZAM database.
  * Uses configured Turso credentials for the default database when present.
@@ -969,6 +980,139 @@ declare function getMonitorLogStats(sessionId: string): {
     lineCount: number;
 };
 
+/**
+ * Observer permission policy — Layer 2 of the two-layer consent model
+ * (see docs/adr/0001-observer-permission-model.md).
+ *
+ * A host (the CLI permission system today, MCP tool-consent later) decides
+ * WHETHER an agent may invoke the observer. This module decides WHAT a given
+ * capture is then allowed to see — enforced by ZAM, because ZAM holds the
+ * camera. The policy is user-configurable through `zam settings` (the
+ * `observer.*` keys in `user_config`) and resolved here into a typed value with
+ * safe defaults.
+ *
+ * The decision functions are pure so they can be unit-tested without a DB or a
+ * live screen, and reused unchanged under a future `zam mcp serve`.
+ */
+
+declare const OBSERVER_POLICY_VERSION: 1;
+type ObserverScope = "off" | "window" | "fullscreen";
+type ObserverConsent = "per-capture" | "per-session" | "standing";
+type ObserverRetention = "none" | "session" | "persist";
+interface ObserverPolicy {
+    version: typeof OBSERVER_POLICY_VERSION;
+    /** "off" disables capture; "window" requires a target; "fullscreen" permits an untargeted grab. */
+    scope: ObserverScope;
+    /** Lower-cased process names permitted under window scope (empty = any non-denied window). */
+    allowlist: string[];
+    /** Lower-cased process/title fragments the user never wants captured (added to the built-in set). */
+    denylist: string[];
+    consent: ObserverConsent;
+    retention: ObserverRetention;
+    redactWindowTitles: boolean;
+    audioOptIn: boolean;
+}
+declare const DEFAULT_OBSERVER_POLICY: ObserverPolicy;
+/**
+ * Built-in sensitive process/title fragments that are ALWAYS non-observable.
+ * User config may extend the effective denylist but can never re-enable capture
+ * of these — a user `allowlist` cannot override the built-in floor. Matching is
+ * case-insensitive substring against process name and window title. This mirrors
+ * a conservative subset of the native Rust observer's sensitive-context set.
+ */
+declare const BUILT_IN_SENSITIVE_MATCHERS: readonly string[];
+type ObserverSettingKey = "observer.scope" | "observer.allowlist" | "observer.denylist" | "observer.consent" | "observer.retention" | "observer.redact_titles" | "observer.audio";
+/**
+ * Public wrapper around the allow/denylist normalizer so CLI list mutation
+ * (`zam observer grant/revoke`) parses entries exactly like resolveObserverPolicy.
+ */
+declare function parseObserverList(raw: string | undefined): string[];
+/** Pure: build a policy from raw setting strings (no DB access). */
+declare function parseObserverPolicy(raw: Partial<Record<ObserverSettingKey, string>>, defaults?: {
+    scope: ObserverScope;
+    consent: ObserverConsent;
+}): ObserverPolicy;
+/** Read the policy from `user_config`, falling back to active symbiosis mode presets, then safe defaults. */
+declare function resolveObserverPolicy(db: Database): Promise<ObserverPolicy>;
+type CaptureDenialReason = "scope-off" | "scope-requires-target" | "denylisted" | "not-allowlisted" | "sensitive";
+type CaptureDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: string;
+    denialReason: CaptureDenialReason;
+};
+interface CaptureRequest {
+    /** Whether the caller specified a concrete window target (--hwnd or --process-name). */
+    hasExplicitTarget: boolean;
+    /** The requested process name, if any (comparison is case-insensitive). */
+    requestedProcessName: string | null;
+}
+interface ResolvedCaptureTarget {
+    /** printwindow | copyfromscreen | fullscreen | provided | screencapture-* */
+    method: string;
+    processName: string | null;
+    windowTitle: string | null;
+}
+/** Built-in sensitive match (authoritative — user config cannot override). */
+declare function matchBuiltInSensitive(processName: string | null, windowTitle: string | null): string | null;
+/** User-denylist match. */
+declare function matchDenylist(policy: ObserverPolicy, processName: string | null, windowTitle: string | null): string | null;
+/**
+ * Phase 1 — decide before any pixels are grabbed, from scope plus the requested
+ * target. Cheap denials (disabled observer, missing target, an explicitly named
+ * sensitive/denied process) happen here so no screenshot is taken at all.
+ */
+declare function decidePreCapture(policy: ObserverPolicy, request: CaptureRequest): CaptureDecision;
+/**
+ * Phase 2 — decide after the window was resolved into a concrete target. This
+ * is the first point where the real process/title are known, so the
+ * sensitive/denylist check against the *actual* captured window happens here;
+ * the caller discards the pixels if it fails.
+ */
+declare function decidePostCapture(policy: ObserverPolicy, target: ResolvedCaptureTarget): CaptureDecision;
+/** True if the user has set any `observer.*` key in user_config. */
+declare function isObserverPolicyConfigured(db: Database): Promise<boolean>;
+/** Hint surfaced when a UI session starts with no observer policy configured. */
+declare const OBSERVER_POLICY_UNSET_HINT: string;
+
+/**
+ * Bridge between the ObserverPolicy (Layer 2) and the native Rust observer
+ * sidecar. The sidecar reads a kernel-written policy file at
+ * `<observer-dir>/policy.json` instead of its own `ZAM_OBSERVER_PRIVACY_POLICY`
+ * env var, so the headless `capture-ui` path and the live sidecar share one
+ * source of truth. See docs/adr/0001-observer-permission-model.md (item 4).
+ */
+
+/** Filename, under the observer dir, that the Rust sidecar reads. */
+declare const SIDECAR_POLICY_FILE = "policy.json";
+/**
+ * The Rust observer's `WindowPrivacyPolicy` wire shape (serde camelCase). These
+ * are only the user-configurable lists; the sidecar enforces its own
+ * authoritative built-in sensitive set on top, exactly like the TS side.
+ */
+interface SidecarPrivacyPolicy {
+    allowProcesses: string[];
+    denyProcesses: string[];
+    denyTitleMarkers: string[];
+}
+/**
+ * Pure mapping from an ObserverPolicy to the sidecar's `WindowPrivacyPolicy`.
+ * A denylist term should block on process OR title, so it feeds both the
+ * process and title-marker lists.
+ */
+declare function toSidecarPrivacyPolicy(policy: ObserverPolicy): SidecarPrivacyPolicy;
+/**
+ * Resolve the policy from settings and write the sidecar file. Returns the
+ * path written and the serialized policy. The directory mirrors
+ * `getUiObserverDir()`, which the Rust observer resolves identically
+ * (`ZAM_OBSERVER_DIR`, else `~/.zam/observer`).
+ */
+declare function syncObserverSidecarPolicy(db: Database, dir?: string): Promise<{
+    path: string;
+    policy: SidecarPrivacyPolicy;
+}>;
+
 /**
  * Cascade Block & Unblock — prerequisite-aware blocking logic.
  *
@@ -1598,6 +1742,22 @@ declare function decideUpdate(input: {
     latestVersion: string;
     channel: InstallChannel;
 }): UpdateDecision;
+/** A single step an executor runs to APPLY an update, in order. */
+type UpdateStepKind = "git-pull" | "npm-install" | "npm-build" | "distribute-skills" | "run-command" | "self-update";
+interface UpdateStep {
+    kind: UpdateStepKind;
+    /** Human-readable description of the step. */
+    label: string;
+    /** For "run-command": the exact command to run. */
+    command?: string;
+}
+/**
+ * Turn a decision into the ordered steps that APPLY it — the counterpart to
+ * `decideUpdate`, which only decides whether and how. Pure and side-effect
+ * free, so the sequencing is unit-tested; the CLI resolves paths and runs each
+ * step. Empty when no update is available.
+ */
+declare function planUpdate(decision: UpdateDecision): UpdateStep[];
 
 /**
  * Per-machine install configuration — Increment 12, Phase 3.
@@ -1732,4 +1892,4 @@ declare function resolveAllBeliefPaths(db: Database): Promise<string[]>;
  */
 declare function resolveAllGoalPaths(db: Database): Promise<string[]>;
 
-export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, type BloomLevel$1 as BloomLevel, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type LocalLLMRunner, type LogStepInput, type MonitorEvent, type Neighborhood, type NeighborhoodToken, type ObservationRating, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SkillProposal, type SkillSource, type SnapshotManifest, type Statement, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearTursoCredentials, compareVersions, createAgentSkill, createFSRS, createGoal, createToken, decideUpdate, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateZshHooks, generateZshUnhooks, getADOCredentials, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isUiObservationReport, listAgentSkills, listGoals, listTokens, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, resolveAllBeliefPaths, resolveAllGoalPaths, resolveReference, resolveRepoPath, resolveReviewContext, saveCredentials, saveInstallConfig, serializeGoal, setADOCredentials, setInstallChannel, setInstallMode, setSetting, setTursoCredentials, startSession, t, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, verifySnapshot, wouldCreateCycle, writeMonitorEvent };
+export { type ADOConfig, type ADOCredentials, type AgentSkill, type AnalysisResult, type ApplySessionSynthesisInput, type ApplySessionSynthesisResult, BUILT_IN_SENSITIVE_MATCHERS, type BloomLevel$1 as BloomLevel, type CaptureDecision, type CaptureDenialReason, type CaptureRequest, type Card, type CardDeletionImpact, type CardState$1 as CardState, type CascadeBlockResult, type CommandRecord, type CommandSequence, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, DEFAULT_OBSERVER_POLICY, DEFAULT_REVIEW_CONTEXT_MAX_CHARS, type Database, type DatabaseProvider, type DatabaseTargetInfo, type DatabaseValue, type DeleteCardResult, type DeleteTokenResult, type DiscoveryOptions, type DomainCompetence, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type LocalLLMRunner, type LogStepInput, type MonitorEvent, type Neighborhood, type NeighborhoodToken, OBSERVER_POLICY_UNSET_HINT, OBSERVER_POLICY_VERSION, type ObservationRating, type ObserverConsent, type ObserverPolicy, type ObserverRetention, type ObserverScope, type ObserverSettingKey, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, type Rating, type RecallPrompt, type RemoteDatabaseOptions, type RepoPaths, type ResolvedCaptureTarget, type ResolvedReference, type ReviewActionResult, type ReviewActionType, type ReviewContext, type ReviewLog, type ReviewQueue, type ReviewQueueItem, type ReviewQueueOptions, type RunResult, SIDECAR_POLICY_FILE, SNAPSHOT_VERSION, type SchedulingCard, type Session, type SessionStep, type SessionSummary, type SessionSynthesisCandidate, type SessionSynthesisEvidence, type SessionSynthesisPreview, type SessionSynthesisRecord, type SidecarPrivacyPolicy, type SkillProposal, type SkillSource, type SnapshotManifest, type Statement, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenPattern, type TranslationKey, type TursoCredentials, UI_OBSERVATION_PROTOCOL_VERSION, type UiActionType, type UiApplicationContext, type UiCandidateToken, type UiEvidenceRef, type UiEvidenceType, type UiObservationKind, type UiObservationReport, type UiObservedAction, type UnblockResult, type UpdateActionKind, type UpdateCardInput, type UpdateDecision, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearTursoCredentials, compareVersions, createAgentSkill, createFSRS, createGoal, createToken, decidePostCapture, decidePreCapture, decideUpdate, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateZshHooks, generateZshUnhooks, getADOCredentials, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isUiObservationReport, listAgentSkills, listGoals, listTokens, loadADOConfig, loadCredentials, loadInstallConfig, logReview, logStep, matchBuiltInSensitive, matchDenylist, matchesFilePath, monitorLogExists, normalizeLocale, normalizePath, openDatabase, openDatabaseWithSync, openRemoteDatabase, pairCommands, parseGoalFile, parseMonitorLog, parseObserverList, parseObserverPolicy, parseSnapshot, parseUiObservationLog, planOpenCodeInstall, planUpdate, prepareLocalModel, prepareSessionSynthesis, readMonitorLog, readUiObservationLog, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveReference, resolveRepoPath, resolveReviewContext, saveCredentials, saveInstallConfig, serializeGoal, setADOCredentials, setInstallChannel, setInstallMode, setSetting, setTursoCredentials, startSession, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, verifySnapshot, wouldCreateCycle, writeMonitorEvent };