@hasna/knowledge 0.2.10 → 0.2.12

package/docs/architecture/ai-native-knowledge-base.md

@@ -133,6 +133,18 @@ Raw files still route through `open-files`. Knowledge S3 storage is for derived
 artifacts such as wiki pages, index shards, schema versions, logs, exports, and
 run outputs.
 
+The storage contract is inspectable through:
+
+```bash
+open-knowledge storage status --scope project --json
+```
+
+That contract names the local app path, SQLite catalog, generated artifact
+classes, S3 bucket/prefix when configured, and the source ownership rule that
+raw source bytes stay in `open-files`. The `storage_objects` table catalogs
+generated artifacts by URI, kind, hash, size, and metadata so local mode and
+remote/S3 mode share the same DB-facing shape.
+
 ## Wiki Model
 
 The Karpathy-style wiki pattern is implemented as scalable artifacts, not three
@@ -208,6 +220,21 @@ The command should:
 7. Record a run ledger with tool calls, sources, costs, outputs, and generated
    records.
 
+## Provider Registry
+
+AI provider setup is BYOK and AI SDK v6 based. The local provider layer tracks:
+
+- OpenAI via `@ai-sdk/openai`, defaulting to `openai:gpt-5.2`.
+- Anthropic via `@ai-sdk/anthropic`, defaulting to
+  `anthropic:claude-sonnet-4-6`.
+- DeepSeek via `@ai-sdk/deepseek`, defaulting to `deepseek:deepseek-chat`.
+
+Model aliases live in config and can be inspected with
+`open-knowledge providers models`. Credentials are resolved from env vars by
+default, checked without making provider calls, and usage can be normalized into
+the existing `provider_usage` table for future prompt, embedding, and web-search
+runs.
+
 ## Non-Goals
 
 - Do not make `open-knowledge` own raw source files.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   "scripts": {
     "test": "bun test",
     "test:cli": "bun test tests/cli.test.ts",
-    "build": "bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers src/mcp.js",
+    "build": "bun build --target=bun --outfile=bin/open-knowledge.js --minify --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/cli.ts && bun build --target=bun --outfile=bin/open-knowledge-mcp.js --external @modelcontextprotocol/sdk --external @aws-sdk/client-s3 --external @aws-sdk/credential-providers --external ai --external @ai-sdk/openai --external @ai-sdk/anthropic --external @ai-sdk/deepseek src/mcp.js",
     "prepublishOnly": "bun run build",
     "postinstall": "bun run build"
   },
@@ -50,7 +50,11 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1063.0",
     "@aws-sdk/credential-providers": "^3.1063.0",
+    "@ai-sdk/anthropic": "^3.0.81",
+    "@ai-sdk/deepseek": "^2.0.35",
+    "@ai-sdk/openai": "^3.0.68",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "ai": "^6.0.197",
     "zod": "^4.3.6"
   },
   "devDependencies": {

package/src/cli.ts

@@ -7,6 +7,7 @@
 import { defaultStorePath, loadStore, saveStore, withLock, makeId, makeShortId, ensureStore, type KnowledgeItem } from './store';
 import { openKnowledgeDb } from './knowledge-db';
 import { createKnowledgeService } from './service';
+import { assertProviderCredentials, parseModelRef, resolveModelRef, type AiProviderId } from './providers';
 import { approvalStatus, assertS3ReadAllowed, assertWebSearchAllowed, createApprovalGate, recordAuditEvent, recordRedactionFindings, redactSecrets } from './safety';
 import pkg from '../package.json' with { type: 'json' };
 
@@ -59,7 +60,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'db', 'wiki', 'source', 'ingest', 'reindex', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -161,12 +162,14 @@ Commands:
   dedupe                       Remove duplicate items by title+content (requires --yes)
   stats                        Show knowledge base statistics
   paths                        Show resolved workspace/store paths
+  storage status|validate      Inspect local/S3 artifact storage contract
   db init|stats                Initialize or inspect local knowledge.db
   wiki init                    Initialize scalable wiki/schema/index/log artifacts
   source resolve <source-ref>  Resolve read-only source content and citation evidence
   ingest manifest <file|s3://> Ingest an open-files manifest into knowledge.db
   ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
+  providers status|models|check Inspect AI SDK provider config and credentials
   safety status|check|approve|audit|redact
   help [command]               Show help
 
@@ -228,11 +231,13 @@ function printCommandHelp(command: string): void {
   if (command === 'dedupe') { console.log('Usage: open-knowledge dedupe --yes [--json]'); return; }
   if (command === 'stats') { console.log('Usage: open-knowledge stats [--json]'); return; }
   if (command === 'paths') { console.log('Usage: open-knowledge paths [--scope local|global|project] [--json]'); return; }
+  if (command === 'storage') { console.log('Usage: open-knowledge storage status|validate [--scope local|global|project] [--json]'); return; }
   if (command === 'db') { console.log('Usage: open-knowledge db init|stats [--scope local|global|project] [--json]'); return; }
   if (command === 'wiki') { console.log('Usage: open-knowledge wiki init [--scope local|global|project] [--json]'); return; }
   if (command === 'source') { console.log('Usage: open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope local|global|project] [--json]'); return; }
   if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
+  if (command === 'providers') { console.log('Usage: open-knowledge providers status|models|check [provider|model-alias] [--scope local|global|project] [--json]'); return; }
   if (command === 'safety') { console.log('Usage: open-knowledge safety status|check|approve|audit|redact [args] [--scope local|global|project] [--json]'); return; }
   printGlobalHelp();
 }
@@ -278,11 +283,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex providers safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex providers safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths storage db wiki source ingest reindex providers safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -308,6 +313,31 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'storage') {
+    const action = positional[1] ?? 'status';
+    if (action === 'status') {
+      const contract = service.storageContract();
+      const validation = service.validateStorage();
+      output({
+        ok: validation.ok,
+        ...contract,
+        validation,
+        message: `${contract.storage_type} artifact storage at ${contract.artifact_store.uri_prefix}`,
+      }, flags.json);
+      return;
+    }
+    if (action === 'validate') {
+      const validation = service.validateStorage();
+      output({
+        ok: validation.ok,
+        validation,
+        message: validation.ok ? 'Storage contract valid' : `Storage contract invalid: ${validation.errors.join('; ')}`,
+      }, flags.json);
+      return;
+    }
+    throw new Error("Invalid storage action. Use 'status' or 'validate'.");
+  }
+
   if (command === 'db') {
     const action = positional[1] ?? 'init';
     if (action !== 'init' && action !== 'stats') {
@@ -504,6 +534,30 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'providers') {
+    const action = positional[1] ?? 'status';
+    if (action === 'status') {
+      const status = service.providerStatus();
+      const configured = status.providers.filter((entry) => entry.configured).length;
+      output({ ok: true, ...status, message: `${configured}/${status.providers.length} provider credential(s) configured` }, flags.json);
+      return;
+    }
+    if (action === 'models') {
+      const models = service.modelRegistry();
+      output({ ok: true, models, message: `${models.length} model alias(es)` }, flags.json);
+      return;
+    }
+    if (action === 'check') {
+      const target = positional[2] ?? 'default';
+      const modelRef = resolveModelRef(target, service.config());
+      const parsed = parseModelRef(modelRef);
+      const credential = assertProviderCredentials(parsed.provider as AiProviderId, service.config());
+      output({ ok: true, target, model_ref: modelRef, provider: parsed.provider, model: parsed.model, credential, message: `${parsed.provider} credentials configured` }, flags.json);
+      return;
+    }
+    throw new Error("Invalid providers action. Use 'status', 'models', or 'check'.");
+  }
+
   ensureStore(storePath);
 
   if (command === 'add') {

package/src/knowledge-db.ts

@@ -16,6 +16,7 @@ export interface KnowledgeDbStats {
   redaction_findings: number;
   audit_events: number;
   approval_gates: number;
+  storage_objects: number;
 }
 
 const MIGRATION_1 = `
@@ -280,6 +281,7 @@ export function getKnowledgeDbStats(path: string): KnowledgeDbStats {
       redaction_findings: count(db, 'redaction_findings'),
       audit_events: count(db, 'audit_events'),
       approval_gates: count(db, 'approval_gates'),
+      storage_objects: count(db, 'storage_objects'),
     };
   } finally {
     db.close();

package/src/mcp.js

@@ -77,6 +77,18 @@ export function buildServer() {
     return jsonText(createKnowledgeService({ scope }).paths());
   });
 
+  registerTool(server, 'ok_storage_status', 'Knowledge storage status', 'Inspect local/S3 artifact storage, source ownership, and scalability contract', {
+    scope: scopeField,
+  }, async ({ scope }) => {
+    const service = createKnowledgeService({ scope });
+    const validation = service.validateStorage();
+    return jsonText({
+      ok: validation.ok,
+      ...service.storageContract(),
+      validation,
+    });
+  });
+
   registerTool(server, 'ok_parse_source_ref', 'Parse source reference', 'Parse and validate an open-files, S3, file, or web source ref', {
     uri: z.string().describe('Source reference URI'),
   }, async ({ uri }) => {
@@ -105,6 +117,20 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_provider_status', 'AI provider status', 'Inspect configured AI SDK providers, model aliases, and BYOK credential availability', {
+    scope: scopeField,
+  }, async ({ scope }) => {
+    const service = createKnowledgeService({ scope });
+    return jsonText({ ok: true, ...service.providerStatus() });
+  });
+
+  registerTool(server, 'ok_provider_models', 'AI provider models', 'List AI SDK model aliases and capability metadata', {
+    scope: scopeField,
+  }, async ({ scope }) => {
+    const service = createKnowledgeService({ scope });
+    return jsonText({ ok: true, models: service.modelRegistry() });
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/providers.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import type { Database } from 'bun:sqlite';
+import type { KnowledgeConfig } from './workspace';
+
+export type AiProviderId = 'openai' | 'anthropic' | 'deepseek';
+
+export interface AiProviderSettings {
+  api_key_env: string;
+  base_url?: string;
+  default_model: string;
+}
+
+export interface AiProvidersConfig {
+  default_model?: string;
+  aliases?: Record<string, string>;
+  openai?: Partial<AiProviderSettings>;
+  anthropic?: Partial<AiProviderSettings>;
+  deepseek?: Partial<AiProviderSettings>;
+}
+
+export interface ModelCapabilities {
+  text_generation: boolean;
+  structured_output: boolean;
+  tool_usage: boolean;
+  tool_streaming: boolean;
+  image_input: boolean;
+  native_web_search: boolean;
+  reasoning: boolean;
+  embeddings: boolean;
+}
+
+export interface ModelRegistryEntry {
+  alias: string;
+  model_ref: string;
+  provider: AiProviderId;
+  model: string;
+  default: boolean;
+  capabilities: ModelCapabilities;
+}
+
+export interface ProviderCredentialStatus {
+  provider: AiProviderId;
+  api_key_env: string;
+  configured: boolean;
+  source: 'env' | 'missing';
+  base_url: string | null;
+  default_model: string;
+}
+
+export interface ProviderStatusResult {
+  default_model: string;
+  providers: ProviderCredentialStatus[];
+  models: ModelRegistryEntry[];
+}
+
+export interface NormalizedProviderUsage {
+  provider: string;
+  model: string;
+  input_tokens: number;
+  output_tokens: number;
+  cost_usd: number;
+  metadata: Record<string, unknown>;
+}
+
+type ProviderFactory = (settings: { apiKey: string; baseURL?: string }) => unknown;
+
+export interface AiProviderRuntimeOptions {
+  config?: KnowledgeConfig;
+  env?: Record<string, string | undefined>;
+  factories?: Partial<Record<AiProviderId, ProviderFactory>>;
+}
+
+const DEFAULT_PROVIDER_SETTINGS: Record<AiProviderId, AiProviderSettings> = {
+  openai: {
+    api_key_env: 'OPENAI_API_KEY',
+    default_model: 'gpt-5.2',
+  },
+  anthropic: {
+    api_key_env: 'ANTHROPIC_API_KEY',
+    default_model: 'claude-sonnet-4-6',
+  },
+  deepseek: {
+    api_key_env: 'DEEPSEEK_API_KEY',
+    default_model: 'deepseek-chat',
+  },
+};
+
+const PROVIDER_CAPABILITIES: Record<AiProviderId, ModelCapabilities> = {
+  openai: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: true,
+    native_web_search: true,
+    reasoning: true,
+    embeddings: true,
+  },
+  anthropic: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: true,
+    native_web_search: false,
+    reasoning: true,
+    embeddings: false,
+  },
+  deepseek: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: false,
+    native_web_search: false,
+    reasoning: true,
+    embeddings: false,
+  },
+};
+
+const BUILTIN_ALIASES: Record<string, string> = {
+  default: 'openai:gpt-5.2',
+  fast: 'openai:gpt-5-mini',
+  reasoning: 'anthropic:claude-opus-4-6',
+  sonnet: 'anthropic:claude-sonnet-4-6',
+  deepseek: 'deepseek:deepseek-chat',
+  'deepseek-reasoning': 'deepseek:deepseek-reasoner',
+};
+
+function providerConfig(config?: KnowledgeConfig): AiProvidersConfig {
+  return (config as KnowledgeConfig & { providers?: AiProvidersConfig }).providers ?? {};
+}
+
+export function providerSettings(config: KnowledgeConfig | undefined, provider: AiProviderId): AiProviderSettings {
+  const configured = providerConfig(config)[provider] ?? {};
+  return {
+    ...DEFAULT_PROVIDER_SETTINGS[provider],
+    ...configured,
+  };
+}
+
+export function modelAliases(config?: KnowledgeConfig): Record<string, string> {
+  const configured = providerConfig(config);
+  return {
+    ...BUILTIN_ALIASES,
+    ...(configured.default_model ? { default: configured.default_model } : {}),
+    ...(configured.aliases ?? {}),
+  };
+}
+
+export function parseModelRef(modelRef: string): { provider: AiProviderId; model: string } {
+  const [provider, ...rest] = modelRef.split(':');
+  const model = rest.join(':');
+  if (provider !== 'openai' && provider !== 'anthropic' && provider !== 'deepseek') {
+    throw new Error(`Unsupported AI provider: ${provider}`);
+  }
+  if (!model) throw new Error(`Invalid model ref: ${modelRef}. Expected provider:model.`);
+  return { provider, model };
+}
+
+export function resolveModelRef(aliasOrRef: string, config?: KnowledgeConfig): string {
+  const aliases = modelAliases(config);
+  return aliases[aliasOrRef] ?? aliasOrRef;
+}
+
+export function listModelRegistry(config?: KnowledgeConfig): ModelRegistryEntry[] {
+  const aliases = modelAliases(config);
+  return Object.entries(aliases).map(([alias, modelRef]) => {
+    const parsed = parseModelRef(modelRef);
+    return {
+      alias,
+      model_ref: modelRef,
+      provider: parsed.provider,
+      model: parsed.model,
+      default: alias === 'default',
+      capabilities: PROVIDER_CAPABILITIES[parsed.provider],
+    };
+  });
+}
+
+export function providerCredentialStatus(config: KnowledgeConfig | undefined, env: Record<string, string | undefined> = process.env): ProviderCredentialStatus[] {
+  return (Object.keys(DEFAULT_PROVIDER_SETTINGS) as AiProviderId[]).map((provider) => {
+    const settings = providerSettings(config, provider);
+    const configured = Boolean(env[settings.api_key_env]);
+    return {
+      provider,
+      api_key_env: settings.api_key_env,
+      configured,
+      source: configured ? 'env' : 'missing',
+      base_url: settings.base_url ?? null,
+      default_model: settings.default_model,
+    };
+  });
+}
+
+export function providerStatus(config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): ProviderStatusResult {
+  return {
+    default_model: resolveModelRef('default', config),
+    providers: providerCredentialStatus(config, env),
+    models: listModelRegistry(config),
+  };
+}
+
+export function assertProviderCredentials(provider: AiProviderId, config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): ProviderCredentialStatus {
+  const status = providerCredentialStatus(config, env).find((entry) => entry.provider === provider);
+  if (!status) throw new Error(`Unsupported AI provider: ${provider}`);
+  if (!status.configured) throw new Error(`Missing ${status.api_key_env} for ${provider}. Set the env var to use this provider.`);
+  return status;
+}
+
+async function defaultFactory(provider: AiProviderId): Promise<ProviderFactory> {
+  if (provider === 'openai') {
+    const { createOpenAI } = await import('@ai-sdk/openai');
+    return createOpenAI as ProviderFactory;
+  }
+  if (provider === 'anthropic') {
+    const { createAnthropic } = await import('@ai-sdk/anthropic');
+    return createAnthropic as ProviderFactory;
+  }
+  const { createDeepSeek } = await import('@ai-sdk/deepseek');
+  return createDeepSeek as ProviderFactory;
+}
+
+export async function createAiSdkProviderRegistry(options: AiProviderRuntimeOptions = {}) {
+  const { createProviderRegistry } = await import('ai');
+  const env = options.env ?? process.env;
+  const providers: Record<string, unknown> = {};
+  for (const provider of Object.keys(DEFAULT_PROVIDER_SETTINGS) as AiProviderId[]) {
+    const settings = providerSettings(options.config, provider);
+    const apiKey = env[settings.api_key_env];
+    if (!apiKey) continue;
+    const factory = options.factories?.[provider] ?? await defaultFactory(provider);
+    providers[provider] = factory({ apiKey, baseURL: settings.base_url });
+  }
+  return createProviderRegistry(providers as never);
+}
+
+export async function languageModelFor(aliasOrRef: string, options: AiProviderRuntimeOptions = {}) {
+  const modelRef = resolveModelRef(aliasOrRef, options.config);
+  const parsed = parseModelRef(modelRef);
+  assertProviderCredentials(parsed.provider, options.config, options.env);
+  const registry = await createAiSdkProviderRegistry(options);
+  return registry.languageModel(modelRef as `${string}:${string}`);
+}
+
+function usageNumber(usage: Record<string, unknown>, keys: string[]): number {
+  for (const key of keys) {
+    const value = usage[key];
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+  }
+  return 0;
+}
+
+export function normalizeAiSdkUsage(input: {
+  provider: string;
+  model: string;
+  usage?: Record<string, unknown> | null;
+  providerMetadata?: Record<string, unknown> | null;
+  costUsd?: number;
+}): NormalizedProviderUsage {
+  const usage = input.usage ?? {};
+  return {
+    provider: input.provider,
+    model: input.model,
+    input_tokens: usageNumber(usage, ['inputTokens', 'promptTokens', 'input_tokens', 'prompt_tokens']),
+    output_tokens: usageNumber(usage, ['outputTokens', 'completionTokens', 'output_tokens', 'completion_tokens']),
+    cost_usd: input.costUsd ?? 0,
+    metadata: {
+      usage,
+      provider_metadata: input.providerMetadata ?? {},
+    },
+  };
+}
+
+export function recordProviderUsage(db: Database, input: NormalizedProviderUsage & { run_id?: string | null; created_at?: string }): string {
+  const id = `usage_${randomUUID()}`;
+  db.run(
+    `INSERT INTO provider_usage (id, run_id, provider, model, input_tokens, output_tokens, cost_usd, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      id,
+      input.run_id ?? null,
+      input.provider,
+      input.model,
+      input.input_tokens,
+      input.output_tokens,
+      input.cost_usd,
+      JSON.stringify(input.metadata),
+      input.created_at ?? new Date().toISOString(),
+    ],
+  );
+  return id;
+}
+
+export function createDeterministicFakeProvider(provider: AiProviderId): ProviderFactory {
+  return () => ({
+    languageModel: (modelId: string) => ({
+      provider,
+      modelId,
+      specificationVersion: 'v3',
+    }),
+    chat: (modelId: string) => ({
+      provider,
+      modelId,
+      specificationVersion: 'v3',
+    }),
+  });
+}

package/src/service.ts

@@ -1,10 +1,18 @@
 import { createArtifactStore } from './artifact-store';
 import { consumeOpenFilesOutbox } from './outbox-consume';
-import { getKnowledgeDbStats, migrateKnowledgeDb } from './knowledge-db';
+import { getKnowledgeDbStats, migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
 import { ingestOpenFilesManifest } from './manifest-ingest';
 import { ingestSourceRef } from './source-ingest';
 import { resolveOpenFilesSource } from './source-resolver';
+import { providerStatus, listModelRegistry, type ProviderStatusResult, type ModelRegistryEntry } from './providers';
 import { resolveSafetyPolicy } from './safety';
+import {
+  recordStorageObjects,
+  resolveStorageContract,
+  validateStorageConfig,
+  type StorageContract,
+  type StorageValidationResult,
+} from './storage-contract';
 import { initializeWikiLayout } from './wiki-layout';
 import {
   ensureKnowledgeWorkspace,
@@ -75,6 +83,14 @@ export class KnowledgeService {
     return createArtifactStore(this.config(), this.ensureWorkspace());
   }
 
+  storageContract(): StorageContract {
+    return resolveStorageContract(this.config(), this.ensureWorkspace(), this.scope);
+  }
+
+  validateStorage(): StorageValidationResult {
+    return validateStorageConfig(this.config(), this.ensureWorkspace());
+  }
+
   paths(): KnowledgePathsResult {
     const workspace = this.ensureWorkspace();
     return {
@@ -106,7 +122,16 @@ export class KnowledgeService {
   }
 
   async initWiki() {
-    return initializeWikiLayout(this.artifactStore());
+    const workspace = this.ensureWorkspace();
+    migrateKnowledgeDb(workspace.knowledgeDbPath);
+    const result = await initializeWikiLayout(this.artifactStore());
+    const db = openKnowledgeDb(workspace.knowledgeDbPath);
+    try {
+      recordStorageObjects(db, result.artifacts);
+    } finally {
+      db.close();
+    }
+    return result;
   }
 
   async ingestManifest(input: string) {
@@ -150,6 +175,14 @@ export class KnowledgeService {
       safetyPolicy: this.safetyPolicy(),
     });
   }
+
+  providerStatus(env: Record<string, string | undefined> = process.env): ProviderStatusResult {
+    return providerStatus(this.config(), env);
+  }
+
+  modelRegistry(): ModelRegistryEntry[] {
+    return listModelRegistry(this.config());
+  }
 }
 
 export function createKnowledgeService(options: KnowledgeServiceOptions = {}): KnowledgeService {