zam-core 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -537,9 +537,10 @@ declare function deleteCardForUser(db: Database, tokenId: string, userId: string
  *
  * Ported from the PoC's due-tokens command.
  *
- * When `domain` is set, only due cards in that token domain are returned.
+ * When `domain` or `knowledgeContext` is set, only matching due cards are
+ * returned.
  */
-declare function getDueCards(db: Database, userId: string, now?: string, domain?: string): Promise<DueCard[]>;
+declare function getDueCards(db: Database, userId: string, now?: string, domain?: string, knowledgeContext?: string): Promise<DueCard[]>;
 /**
  * Get all blocked cards for a user.
  *
@@ -548,6 +549,68 @@ declare function getDueCards(db: Database, userId: string, now?: string, domain?
  */
 declare function getBlockedCards(db: Database, userId: string): Promise<BlockedCard[]>;
 
+/**
+ * Knowledge Context repository — typed wrappers around the contexts and token_contexts tables.
+ *
+ * A context represents a first-class facet (e.g. work, school, private) that can have
+ * attributes like default generation language.
+ */
+
+interface KnowledgeContext {
+    id: string;
+    name: string;
+    label: string | null;
+    language: string | null;
+    created_at: string;
+}
+interface CreateKnowledgeContextInput {
+    name: string;
+    label?: string | null;
+    language?: string | null;
+}
+interface UpdateKnowledgeContextInput {
+    name?: string;
+    label?: string | null;
+    language?: string | null;
+}
+/**
+ * Create a new knowledge context.
+ */
+declare function createKnowledgeContext(db: Database, input: CreateKnowledgeContextInput): Promise<KnowledgeContext>;
+/**
+ * Retrieve a knowledge context by its unique name.
+ */
+declare function getKnowledgeContextByName(db: Database, name: string): Promise<KnowledgeContext | undefined>;
+/**
+ * Retrieve a knowledge context by its ULID.
+ */
+declare function getKnowledgeContextById(db: Database, id: string): Promise<KnowledgeContext | undefined>;
+/**
+ * List all knowledge contexts ordered by creation date (oldest first) or name.
+ */
+declare function listKnowledgeContexts(db: Database): Promise<KnowledgeContext[]>;
+/**
+ * Update mutable fields on a knowledge context.
+ */
+declare function updateKnowledgeContext(db: Database, id: string, updates: UpdateKnowledgeContextInput): Promise<KnowledgeContext>;
+/**
+ * Delete a knowledge context. Cascades deletion of associated token mappings.
+ */
+declare function deleteKnowledgeContext(db: Database, id: string): Promise<void>;
+/**
+ * Assign a token to a knowledge context.
+ * Safe to call repeatedly (noop if already assigned).
+ */
+declare function assignTokenToContext(db: Database, tokenId: string, contextId: string): Promise<void>;
+/**
+ * Remove a token from a knowledge context.
+ */
+declare function unassignTokenFromContext(db: Database, tokenId: string, contextId: string): Promise<void>;
+/**
+ * List all knowledge contexts assigned to a given token.
+ */
+declare function listContextsForToken(db: Database, tokenId: string): Promise<KnowledgeContext[]>;
+
 /**
  * Prerequisite repository — typed wrappers around the prerequisites table.
  *
@@ -562,6 +625,7 @@ interface Prerequisite {
 /** A prerequisite row joined with the token it points to. */
 interface PrerequisiteWithToken extends Prerequisite {
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: number;
@@ -603,6 +667,7 @@ declare function getDependents(db: Database, tokenId: string): Promise<Prerequis
 interface NeighborhoodToken {
     id: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: number;
@@ -802,6 +867,7 @@ type SymbiosisMode = "shadowing" | "copilot" | "autonomy";
 interface Token {
     id: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloom_level: BloomLevel$1;
@@ -817,6 +883,7 @@ interface Token {
 }
 interface CreateTokenInput {
     slug: string;
+    title?: string;
     concept: string;
     domain?: string;
     bloom_level?: BloomLevel$1;
@@ -828,6 +895,7 @@ interface CreateTokenInput {
     topic_id?: string | null;
 }
 interface UpdateTokenInput {
+    title?: string | null;
     concept?: string;
     domain?: string;
     bloom_level?: BloomLevel$1;
@@ -840,6 +908,15 @@ interface UpdateTokenInput {
 }
 interface ListTokensOptions {
     domain?: string;
+    /**
+     * Filter by domain prefix using `/` as separator (e.g. "company-team").
+     * Matches exact or startsWith(prefix + "/").
+     */
+    domainPrefix?: string;
+    /**
+     * Filter by knowledge context name (e.g. "work-company").
+     */
+    knowledgeContext?: string;
 }
 interface TokenDeleteImpact {
     cards: number;
@@ -908,13 +985,14 @@ declare function deleteToken(db: Database, slug: string): Promise<DeleteTokenRes
  */
 declare function findTokens(db: Database, query: string): Promise<ScoredToken[]>;
 /**
- * List all tokens, optionally filtered by domain.
- * Results are ordered by bloom_level then slug.
+ * List all tokens, optionally filtered by domain or knowledge context.
+ * Results are ordered by bloom_level then domain then slug (or bloom_level then slug if domain-filtered).
  */
 declare function listTokens(db: Database, options?: ListTokensOptions): Promise<Token[]>;
 interface PersonalCard {
     tokenId: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloomLevel: BloomLevel$1;
@@ -938,14 +1016,28 @@ interface PersonalCard {
     topicId: string | null;
 }
 declare function slugify(text: string): string;
+/**
+ * Strip domain prefix (using / separator) from slug for display.
+ */
+declare function getShortSlug(slug: string, domainPrefix?: string | null): string;
+/**
+ * Primary display name for a token: human title if present, else short slug.
+ * Never falls back to concept (which is a spoiler).
+ */
+declare function getDisplayTitle(t: {
+    title?: string | null;
+    slug: string;
+}, activeDomainScope?: string | null): string;
 declare function generateTokenSlug(db: Database, domain: string, concept: string, question?: string | null): Promise<string>;
 declare function listPersonalCards(db: Database, userId: string, options?: {
     query?: string;
     domain?: string;
+    knowledgeContext?: string;
 }): Promise<PersonalCard[]>;
 interface CurriculumCardInput {
     question: string;
     concept: string;
+    title?: string;
     domain: string;
     source_link?: string | null;
     context?: string;
@@ -982,6 +1074,7 @@ interface FoundationProposalInput {
     question: string;
     concept: string;
     domain: string;
+    title?: string;
     context?: string;
     bloom_level?: number;
     symbiosis_mode?: string | null;
@@ -1002,6 +1095,7 @@ interface SourceProposalInput {
     question: string;
     concept: string;
     domain: string;
+    title?: string;
     bloom_level: number;
     symbiosis_mode: string;
     excerpt: string;
@@ -1054,7 +1148,9 @@ interface EmbeddedTokenRow {
  * vector derives from exactly this string — never the slug, which is an
  * identifier, not meaning.
  */
-declare function embeddingContentForToken(t: Pick<Token, "concept" | "question" | "domain">): string;
+declare function embeddingContentForToken(t: Pick<Token, "concept" | "question" | "domain"> & {
+    title?: string | null;
+}): string;
 declare function computeContentHash(text: string): string;
 /**
  * Encode a vector as a little-endian float32 BLOB. Builds a fresh buffer (no
@@ -1850,11 +1946,13 @@ interface ReviewQueueOptions {
     maxNew?: number;
     maxReviews?: number;
     now?: Date;
+    knowledgeContext?: string;
 }
 interface ReviewQueueItem {
     cardId: string;
     tokenId: string;
     slug: string;
+    title: string;
     concept: string;
     domain: string;
     bloomLevel: number;
@@ -2102,6 +2200,7 @@ interface WorkspaceConfig {
     sourceControl?: WorkspaceSourceControl;
     knowledgeScopes?: string[];
     defaultAgent?: string;
+    activeKnowledgeContext?: string;
 }
 /** Load ~/.zam/config.json. Returns an empty config if missing or unreadable. */
 declare function loadInstallConfig(path?: string): InstallConfig;
@@ -2136,6 +2235,8 @@ declare function removeConfiguredWorkspace(id: string, path?: string): Workspace
  * good for moving snapshots between machines"), never for behavior.
  */
 declare function detectSyncProvider(dir: string): string | null;
+declare function getActiveWorkspaceContext(path?: string): string | undefined;
+declare function setActiveWorkspaceContext(contextName: string | undefined, path?: string): boolean;
 
 interface InstallResult {
     success: boolean;
@@ -2233,4 +2334,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, 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 ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, 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 EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type FoundationSuggestion, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, 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 OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, 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 SourceProposalInput, type SplitProposalInput, type Statement, type SuggestFoundationsOptions, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, 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, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, buildAncestorMap, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listEmbeddedTokens, listGoals, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, 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, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, suggestFoundations, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unblockReady, updateCard, updateGoalStatus, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, 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 ConfirmFoundationsResult, type ConnectionOptions, type CreateAgentSkillInput, type CreateGoalInput, type CreateKnowledgeContextInput, type CreateReviewInput, type CreateSessionInput, type CreateTokenInput, type Credentials, type CurriculumCardInput, 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 EmbeddedTokenRow, type EmbeddingCoverage, type EmbeddingStaleness, type EvaluateInput, type EvaluateResult, type ExecuteReviewActionInput, type ExecutionContext, type FSRSParameters, type FoundationProposalInput, type FoundationSuggestion, type Goal, type GoalFrontmatter, type GoalStatus, type GoalSummary, HOMEBREW_CASK, type HybridScoredToken, type HybridSearchOptions, type ImportCurriculumResult, type ImportResult, type InstallChannel, type InstallConfig, type InstallMode, type InstallPlan, type InstallResult, type KnowledgeContext, type ListTokensOptions, type LocalLLMRunner, type LogStepInput, type MachineAiConfig, type MachineProviderRecord, type MachineRoleBinding, 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 OllamaDetectionOptions, type PersonalCard, type PrepareSessionSynthesisInput, type Prerequisite, type PrerequisiteWithToken, type PromptInput, REVIEW_CONTEXT_CACHE_TTL_MS, 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 SourceProposalInput, type SplitProposalInput, type Statement, type SuggestFoundationsOptions, type SupportedLocale, type SymbiosisMode, type SynthesisConfidence, type SystemProfile, type Token, type TokenDeleteImpact, type TokenEmbedding, type TokenNeedingEmbedding, 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 UpdateKnowledgeContextInput, type UpdateStep, type UpdateStepKind, type UpdateTokenInput, type UserSetting, type UserStats, WINGET_PACKAGE_ID, type WorkItem, type WorkspaceConfig, type WorkspaceKind, type WorkspaceSourceControl, addPrerequisite, analyzeObservation, appendUiObservationReport, applySessionSynthesis, assignTokenToContext, buildAncestorMap, buildReviewQueue, buildUiSynthesisCandidates, cascadeBlock, clearADOCredentials, clearProviderApiKey, clearReviewContextCache, clearTursoCredentials, compareVersions, computeContentHash, confirmCardSplit, confirmFoundations, confirmSourceImport, cosineSimilarity, createAgentSkill, createFSRS, createGoal, createKnowledgeContext, createToken, decidePostCapture, decidePreCapture, decideUpdate, decodeEmbedding, deleteCardForUser, deleteKnowledgeContext, deleteSetting, deleteToken, deprecateToken, detectSyncProvider, detectSystemLocale, discoverSkills, distributeGlobalSkills, embeddingContentForToken, encodeEmbedding, endSession, ensureCard, ensureMonitorDir, ensureUiObserverDir, evaluateRating, executeReviewAction, exportSnapshot, extractTasks, extractTokenRefs, fetchActiveWorkItems, findTokens, generateBashHooks, generateBashUnhooks, generateConceptFreeCue, generatePowerShellHooks, generatePowerShellUnhooks, generatePrompt, generateTokenSlug, generateZshHooks, generateZshUnhooks, getADOCredentials, getActiveWorkspace, getActiveWorkspaceContext, getActiveWorkspaceId, getAgentSkill, getAllSettings, getAllSettingsDetailed, getBlockedCards, getCard, getCardById, getCardDeletionImpact, getConfiguredWorkspaces, getDatabaseTargetInfo, getDefaultDbPath, getDependents, getDisplayTitle, getDomainCompetence, getDueCards, getEmbeddingCoverage, getGoal, getGoalTree, getInstallChannel, getInstallMode, getKnowledgeContextById, getKnowledgeContextByName, getMachineAiConfig, getMonitorDir, getMonitorLogStats, getMonitorPath, getPackageSkillPath, getPrerequisites, getProviderApiKey, getRepoPaths, getReviewsForCard, getReviewsForUser, getSessionSummary, getSessionSynthesisRecords, getSetting, getShortSlug, getSystemProfile, getTokenById, getTokenBySlug, getTokenDeleteImpact, getTokenEmbedding, getTokenNeighborhood, getTursoCredentials, getUiObservationPath, getUiObserverDir, getUserStats, hasCommand, importCurriculumCards, importSnapshot, injectShellHooks, installFastFlowLM, installOllama, installOpenCode, interleave, isObserverPolicyConfigured, isOllamaInstalled, isUiObservationReport, listAgentSkills, listContextsForToken, listEmbeddedTokens, listGoals, listKnowledgeContexts, listPersonalCards, listProviderApiKeyRefs, listTokens, listTokensNeedingEmbedding, 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, removeConfiguredWorkspace, resolveAllBeliefPaths, resolveAllGoalPaths, resolveObserverPolicy, resolveOllamaCommand, resolveReference, resolveRepoPath, resolveReviewContext, saveConfiguredWorkspaces, saveCredentials, saveInstallConfig, saveMachineAiConfig, searchTokensHybrid, serializeGoal, setADOCredentials, setActiveWorkspaceContext, setActiveWorkspaceId, setInstallChannel, setInstallMode, setProviderApiKey, setSetting, setTursoCredentials, slugify, startSession, suggestFoundations, syncObserverSidecarPolicy, t, toSidecarPrivacyPolicy, uiObservationLogExists, uiObservationTimeSpan, unassignTokenFromContext, unblockReady, updateCard, updateGoalStatus, updateKnowledgeContext, updateToken, upsertConfiguredWorkspace, upsertTokenEmbedding, verifySnapshot, wouldCreateCycle, writeMonitorEvent };