@hasna/knowledge 0.2.19 → 0.2.21

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

@@ -43,6 +43,14 @@ The future hosted/SaaS wrapper owns:
 The OSS package must stay useful without a hosted account. Hosted mode should be
 an optional remote client over explicit API contracts.
 
+The local hosted-aware contract follows the `open-skills` pattern: `mode` is
+`local` by default, `setup --mode hosted` records `hosted.api_url`, env vars
+`KNOWLEDGE_API_URL` and `KNOWLEDGE_API_KEY` can override local config, and
+credentials live outside project state in `~/.hasna/knowledge/auth.json`.
+`remote contracts` publishes the registry/search/ask/build/sync/status/logs and
+artifact endpoints that a SaaS wrapper can implement. Local use, local search,
+and local artifact generation do not require this remote API.
+
 ## Local Workspace
 
 Project-local state lives at:

package/docs/architecture/hybrid-semantic-search.md

@@ -180,3 +180,12 @@ Reindexing is driven by source revisions:
 - Permission filters run before model context assembly.
 - Retrieval internals can swap from JSON vectors to pgvector or managed vector
   stores without changing CLI/MCP result contracts.
+
+## Evaluation Fixtures
+
+`tests/semantic-evals.test.ts` and `tests/fixtures/semantic-eval-fixtures.ts`
+seed no-network corpora for retrieval quality checks. The fixtures cover
+keyword hits, deterministic fake-vector fallback for synonym-style prompts,
+citation correctness, stale revision filtering, non-read-only provenance
+filtering, rerank ordering, generated wiki-page retrieval, missing-source
+answers, and `knowledge <prompt>` context assembly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/knowledge",
-  "version": "0.2.19",
+  "version": "0.2.21",
   "description": "Agent-friendly local knowledge CLI with JSON output, pagination, and safe destructive actions",
   "type": "module",
   "bin": {

package/src/auth.ts

@@ -0,0 +1,123 @@
+import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import type { KnowledgeConfig } from './workspace';
+
+export interface KnowledgeAuthConfig {
+  api_key: string;
+  email?: string;
+  org_id?: string;
+  org_slug?: string;
+  user_id?: string;
+  api_url?: string;
+  created_at: string;
+}
+
+export interface KnowledgeAuthStatus {
+  authenticated: boolean;
+  source: 'env' | 'file' | 'none';
+  api_url: string;
+  auth_path: string;
+  email: string | null;
+  org_id: string | null;
+  org_slug: string | null;
+  user_id: string | null;
+  api_key_present: boolean;
+}
+
+export const DEFAULT_KNOWLEDGE_API_URL = 'https://knowledge.hasna.xyz';
+
+export function normalizeKnowledgeApiOrigin(apiUrl: string): string {
+  const url = new URL(apiUrl);
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+    throw new Error('Knowledge API URL must use http or https.');
+  }
+  const pathname = url.pathname.replace(/\/+$/, '');
+  if (pathname === '/api' || pathname === '/api/v1') {
+    url.pathname = '/';
+  } else if (pathname.endsWith('/api/v1')) {
+    url.pathname = pathname.slice(0, -'/api/v1'.length) || '/';
+  } else if (pathname.endsWith('/api')) {
+    url.pathname = pathname.slice(0, -'/api'.length) || '/';
+  }
+  return url.toString().replace(/\/+$/, '');
+}
+
+export function knowledgeAuthPath(env: Record<string, string | undefined> = process.env): string {
+  if (env.HASNA_KNOWLEDGE_AUTH_PATH) return env.HASNA_KNOWLEDGE_AUTH_PATH;
+  const root = env.HASNA_KNOWLEDGE_AUTH_DIR ?? join(homedir(), '.hasna', 'knowledge');
+  return join(root, 'auth.json');
+}
+
+export function resolveKnowledgeApiUrl(
+  config?: KnowledgeConfig,
+  env: Record<string, string | undefined> = process.env,
+): string {
+  return normalizeKnowledgeApiOrigin(env.KNOWLEDGE_API_URL ?? config?.hosted?.api_url ?? DEFAULT_KNOWLEDGE_API_URL);
+}
+
+export function getKnowledgeAuth(env: Record<string, string | undefined> = process.env): KnowledgeAuthConfig | null {
+  try {
+    const path = knowledgeAuthPath(env);
+    if (!existsSync(path)) return null;
+    const parsed = JSON.parse(readFileSync(path, 'utf8')) as KnowledgeAuthConfig;
+    return typeof parsed.api_key === 'string' && parsed.api_key.length > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function saveKnowledgeAuth(
+  auth: Omit<KnowledgeAuthConfig, 'created_at'> & { created_at?: string },
+  env: Record<string, string | undefined> = process.env,
+): KnowledgeAuthConfig {
+  const path = knowledgeAuthPath(env);
+  const stored: KnowledgeAuthConfig = {
+    ...auth,
+    api_url: auth.api_url ? normalizeKnowledgeApiOrigin(auth.api_url) : undefined,
+    created_at: auth.created_at ?? new Date().toISOString(),
+  };
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, `${JSON.stringify(stored, null, 2)}\n`, { mode: 0o600 });
+  return stored;
+}
+
+export function clearKnowledgeAuth(env: Record<string, string | undefined> = process.env): boolean {
+  try {
+    unlinkSync(knowledgeAuthPath(env));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getKnowledgeApiKey(env: Record<string, string | undefined> = process.env): { apiKey: string | null; source: KnowledgeAuthStatus['source'] } {
+  if (env.KNOWLEDGE_API_KEY) return { apiKey: env.KNOWLEDGE_API_KEY, source: 'env' };
+  if (env.HASNA_KNOWLEDGE_API_KEY) return { apiKey: env.HASNA_KNOWLEDGE_API_KEY, source: 'env' };
+  const auth = getKnowledgeAuth(env);
+  return auth?.api_key ? { apiKey: auth.api_key, source: 'file' } : { apiKey: null, source: 'none' };
+}
+
+export function knowledgeAuthStatus(
+  config?: KnowledgeConfig,
+  env: Record<string, string | undefined> = process.env,
+): KnowledgeAuthStatus {
+  const auth = getKnowledgeAuth(env);
+  const key = getKnowledgeApiKey(env);
+  const apiUrl = env.KNOWLEDGE_API_URL
+    ? resolveKnowledgeApiUrl(config, env)
+    : auth?.api_url
+      ? normalizeKnowledgeApiOrigin(auth.api_url)
+      : resolveKnowledgeApiUrl(config, env);
+  return {
+    authenticated: Boolean(key.apiKey),
+    source: key.source,
+    api_url: apiUrl,
+    auth_path: knowledgeAuthPath(env),
+    email: key.source === 'file' ? auth?.email ?? null : null,
+    org_id: key.source === 'file' ? auth?.org_id ?? null : null,
+    org_slug: key.source === 'file' ? auth?.org_slug ?? null : null,
+    user_id: key.source === 'file' ? auth?.user_id ?? null : null,
+    api_key_present: Boolean(key.apiKey),
+  };
+}

package/src/cli.ts

@@ -55,6 +55,13 @@ interface Flags {
   generate?: boolean;
   approveWrite?: boolean;
   provider?: string;
+  mode?: string;
+  apiUrl?: string;
+  apiKey?: string;
+  email?: string;
+  org?: string;
+  orgId?: string;
+  userId?: string;
   domain?: string[];
   fileResults?: boolean;
   full?: boolean;
@@ -72,7 +79,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'setup', 'auth', 'remote', 'storage', 'db', 'wiki', 'source', 'ingest', 'reindex', 'search', 'web', 'ask', 'build', 'embeddings', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -116,6 +123,13 @@ function parseArgs(argv: string[]): ParseResult {
       case '--generate': flags.generate = true; break;
       case '--approve-write': flags.approveWrite = true; break;
       case '--provider': flags.provider = argv[i + 1]; i += 1; break;
+      case '--mode': flags.mode = argv[i + 1]; i += 1; break;
+      case '--api-url': flags.apiUrl = argv[i + 1]; i += 1; break;
+      case '--api-key': flags.apiKey = argv[i + 1]; i += 1; break;
+      case '--email': flags.email = argv[i + 1]; i += 1; break;
+      case '--org': flags.org = argv[i + 1]; i += 1; break;
+      case '--org-id': flags.orgId = argv[i + 1]; i += 1; break;
+      case '--user-id': flags.userId = argv[i + 1]; i += 1; break;
       case '--domain': flags.domain = [...(flags.domain ?? []), argv[i + 1]]; i += 1; break;
       case '--file-results': flags.fileResults = true; break;
       case '--full': flags.full = true; break;
@@ -190,6 +204,9 @@ Commands:
   dedupe                       Remove duplicate items by title+content (requires --yes)
   stats                        Show knowledge base statistics
   paths                        Show resolved workspace/store paths
+  setup                        Configure local or hosted mode
+  auth login|whoami|logout     Manage hosted API credentials
+  remote contracts|status      Inspect hosted client contracts/readiness
   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
@@ -216,6 +233,13 @@ Global Options:
   --generate                   Call AI SDK text generation for ask/build
   --approve-write              Record approval intent for future durable wiki writes
   --provider <name>            Provider override for web search
+  --mode local|hosted          Configure OSS local or hosted-aware mode
+  --api-url <url>              Hosted API origin (or KNOWLEDGE_API_URL)
+  --api-key <key>              Hosted API key for auth login
+  --email <email>              Hosted account email metadata
+  --org <slug>                 Hosted organization slug metadata
+  --org-id <id>                Hosted organization id metadata
+  --user-id <id>               Hosted user id metadata
   --domain <domain>            Restrict provider web search to a domain
   --file-results               File web snippets as web source refs
   --full                       Force full embedding index rebuild
@@ -274,6 +298,9 @@ 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 === 'setup') { console.log('Usage: open-knowledge setup --mode local|hosted [--api-url https://...] [--scope local|global|project] [--json]'); return; }
+  if (command === 'auth') { console.log('Usage: open-knowledge auth login|whoami|logout [--api-key <key>] [--email <email>] [--org <slug>] [--api-url https://...] [--scope local|global|project] [--json]'); return; }
+  if (command === 'remote') { console.log('Usage: open-knowledge remote contracts|status [--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; }
@@ -330,11 +357,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 storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --domain --file-results --full --fake --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 setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --model --dimensions --semantic --context --generate --approve-write --provider --mode --api-url --api-key --email --org --org-id --user-id --domain --file-results --full --fake --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 storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--full)--full" "(--fake)--fake" "(-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]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--domain)--domain[domain]:" "(--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 setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(--semantic)--semantic" "(--context)--context" "(--generate)--generate" "(--approve-write)--approve-write" "(--file-results)--file-results" "(--full)--full" "(--fake)--fake" "(-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]:" "(--model)--model[model ref]:" "(--dimensions)--dimensions[embedding dimensions]:number:" "(--provider)--provider[provider]:" "(--mode)--mode"\{local,hosted\}:" "(--api-url)--api-url[hosted API URL]:" "(--api-key)--api-key[hosted API key]:" "(--email)--email[email]:" "(--org)--org[org slug]:" "(--org-id)--org-id[org id]:" "(--user-id)--user-id[user id]:" "(--domain)--domain[domain]:" "(--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 storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; 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 -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; complete -c open-knowledge -l fake; 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 model; complete -c open-knowledge -l dimensions; 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 setup auth remote storage db wiki source ingest reindex search web ask build embeddings providers safety help ls rm edit unarchive knowledge"; 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 -l semantic; complete -c open-knowledge -l context; complete -c open-knowledge -l generate; complete -c open-knowledge -l approve-write; complete -c open-knowledge -l provider; complete -c open-knowledge -l mode; complete -c open-knowledge -l api-url; complete -c open-knowledge -l api-key; complete -c open-knowledge -l email; complete -c open-knowledge -l org; complete -c open-knowledge -l org-id; complete -c open-knowledge -l user-id; complete -c open-knowledge -l domain; complete -c open-knowledge -l file-results; complete -c open-knowledge -l full; complete -c open-knowledge -l fake; 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 model; complete -c open-knowledge -l dimensions; 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'.");
     }
@@ -365,6 +392,84 @@ async function run(argv: string[]): Promise<void> {
     return;
   }
 
+  if (command === 'setup') {
+    const result = service.setup({
+      mode: flags.mode,
+      apiUrl: flags.apiUrl,
+    });
+    output(result, flags.json);
+    return;
+  }
+
+  if (command === 'auth') {
+    const action = positional[1] ?? 'whoami';
+    if (action === 'whoami' || action === 'status') {
+      const result = service.authStatus(process.env);
+      output({ ok: true, ...result, message: result.authenticated ? `Authenticated via ${result.source}` : 'Not authenticated' }, flags.json);
+      return;
+    }
+    if (action === 'login') {
+      const apiKey = flags.apiKey ?? process.env.KNOWLEDGE_API_KEY ?? process.env.HASNA_KNOWLEDGE_API_KEY;
+      if (!apiKey) throw new Error('Usage: open-knowledge auth login --api-key <key> [--email <email>]');
+      const auth = service.saveAuth({
+        apiKey,
+        email: flags.email,
+        orgSlug: flags.org,
+        orgId: flags.orgId,
+        userId: flags.userId,
+        apiUrl: flags.apiUrl,
+      }, process.env);
+      output({
+        ok: true,
+        authenticated: true,
+        email: auth.email ?? null,
+        org_slug: auth.org_slug ?? null,
+        api_url: auth.api_url ?? service.authStatus(process.env).api_url,
+        auth_path: service.authStatus(process.env).auth_path,
+        message: `Saved hosted credentials for ${auth.email ?? 'API key'}`,
+      }, flags.json);
+      return;
+    }
+    if (action === 'logout') {
+      const removed = service.clearAuth(process.env);
+      output({ ok: true, removed, message: removed ? 'Removed hosted credentials' : 'No hosted credentials found' }, flags.json);
+      return;
+    }
+    throw new Error("Invalid auth action. Use 'login', 'whoami', or 'logout'.");
+  }
+
+  if (command === 'remote') {
+    const action = positional[1] ?? 'status';
+    if (action === 'contracts' || action === 'contract') {
+      const auth = service.authStatus(process.env);
+      output({
+        ok: true,
+        authenticated: auth.authenticated,
+        api_url: auth.api_url,
+        contract: service.remoteContract(),
+        message: `Remote contract v${service.remoteContract().contract_version}`,
+      }, flags.json);
+      return;
+    }
+    if (action === 'status') {
+      const auth = service.authStatus(process.env);
+      const contract = service.remoteContract();
+      output({
+        ok: true,
+        mode: service.config().mode,
+        authenticated: auth.authenticated,
+        auth_source: auth.source,
+        api_url: auth.api_url,
+        client_ready: Boolean(service.remoteClient(process.env)),
+        contract_version: contract.contract_version,
+        capabilities: contract.capabilities,
+        message: auth.authenticated ? `Remote client ready for ${auth.api_url}` : 'Remote client not authenticated',
+      }, flags.json);
+      return;
+    }
+    throw new Error("Invalid remote action. Use 'contracts' or 'status'.");
+  }
+
   if (command === 'storage') {
     const action = positional[1] ?? 'status';
     if (action === 'status') {

package/src/remote-client.ts

@@ -0,0 +1,268 @@
+import { getKnowledgeApiKey, resolveKnowledgeApiUrl } from './auth';
+import type { KnowledgeConfig } from './workspace';
+
+export const REMOTE_KNOWLEDGE_CONTRACT_VERSION = 1 as const;
+
+export type RemoteKnowledgeRunStatus = 'queued' | 'running' | 'completed' | 'failed' | 'canceled';
+
+export interface RemoteKnowledgeSourceContract {
+  owner: 'open-files';
+  preferred_ref: 'open-files';
+  allowed_schemes: string[];
+  raw_source_bytes_stored_in_open_knowledge: false;
+}
+
+export interface RemoteKnowledgeArtifactContract {
+  storage_type: 'local' | 's3' | 'managed';
+  uri_prefix: string | null;
+  generated_only: true;
+}
+
+export interface RemoteKnowledgeRegistryContract {
+  contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
+  service: 'open-knowledge';
+  mode: 'local' | 'hosted';
+  capabilities: string[];
+  endpoints: {
+    registry: string;
+    search: string;
+    ask: string;
+    build: string;
+    sync: string;
+    run_status: string;
+    run_logs: string;
+    run_artifacts: string;
+  };
+  source_contract: RemoteKnowledgeSourceContract;
+  artifact_contract: RemoteKnowledgeArtifactContract;
+}
+
+export interface RemoteKnowledgeRunContract {
+  contract_version: typeof REMOTE_KNOWLEDGE_CONTRACT_VERSION;
+  id?: string;
+  type?: 'search' | 'ask' | 'build' | 'sync' | 'artifact' | 'status';
+  status?: RemoteKnowledgeRunStatus | string;
+  query?: string;
+  prompt?: string;
+  output_preview?: unknown;
+  citations?: unknown[];
+  artifacts?: unknown[];
+  usage?: Record<string, unknown>;
+  created_at?: string;
+  started_at?: string;
+  completed_at?: string;
+  duration_ms?: number;
+  error_code?: string;
+  error_message?: string;
+  error?: string;
+  details?: unknown;
+}
+
+export interface RemoteKnowledgeSearchRequest {
+  query: string;
+  limit?: number;
+  semantic?: boolean;
+  source_refs?: string[];
+}
+
+export interface RemoteKnowledgePromptRequest extends RemoteKnowledgeSearchRequest {
+  prompt: string;
+  generate?: boolean;
+  approve_write?: boolean;
+}
+
+export interface RemoteKnowledgeSyncRequest {
+  source_refs?: string[];
+  artifact_prefix?: string;
+  mode?: 'pull' | 'push' | 'both';
+}
+
+export interface RemoteKnowledgeLogEntry {
+  id?: string;
+  run_id?: string;
+  level?: string;
+  event?: string;
+  metadata?: Record<string, unknown>;
+  created_at?: string;
+}
+
+export interface RemoteKnowledgeArtifact {
+  id?: string;
+  uri?: string;
+  key?: string;
+  kind?: string;
+  content_type?: string;
+  hash?: string;
+  size_bytes?: number;
+  metadata?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function stringValue(record: Record<string, unknown>, key: string): string | undefined {
+  const value = record[key];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function numberValue(record: Record<string, unknown>, key: string): number | undefined {
+  const value = record[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function arrayValue(record: Record<string, unknown>, key: string): unknown[] | undefined {
+  const value = record[key];
+  return Array.isArray(value) ? value : undefined;
+}
+
+export function normalizeRemoteKnowledgeRunContract(payload: unknown, fallback?: Partial<RemoteKnowledgeRunContract>): RemoteKnowledgeRunContract {
+  const record = isRecord(payload) ? payload : {};
+  return {
+    contract_version: REMOTE_KNOWLEDGE_CONTRACT_VERSION,
+    id: stringValue(record, 'id') ?? fallback?.id,
+    type: (stringValue(record, 'type') as RemoteKnowledgeRunContract['type'] | undefined) ?? fallback?.type,
+    status: stringValue(record, 'status') ?? fallback?.status,
+    query: stringValue(record, 'query') ?? fallback?.query,
+    prompt: stringValue(record, 'prompt') ?? fallback?.prompt,
+    output_preview: Object.prototype.hasOwnProperty.call(record, 'output_preview') ? record.output_preview : fallback?.output_preview,
+    citations: arrayValue(record, 'citations') ?? fallback?.citations,
+    artifacts: arrayValue(record, 'artifacts') ?? fallback?.artifacts,
+    usage: isRecord(record.usage) ? record.usage : fallback?.usage,
+    created_at: stringValue(record, 'created_at') ?? fallback?.created_at,
+    started_at: stringValue(record, 'started_at') ?? fallback?.started_at,
+    completed_at: stringValue(record, 'completed_at') ?? fallback?.completed_at,
+    duration_ms: numberValue(record, 'duration_ms') ?? fallback?.duration_ms,
+    error_code: stringValue(record, 'error_code') ?? fallback?.error_code,
+    error_message: stringValue(record, 'error_message') ?? fallback?.error_message,
+    error: stringValue(record, 'error') ?? fallback?.error,
+    details: Object.prototype.hasOwnProperty.call(record, 'details') ? record.details : fallback?.details,
+  };
+}
+
+export function knowledgeRegistryContract(input: {
+  mode: 'local' | 'hosted';
+  sourceSchemes: string[];
+  storageType: 'local' | 's3' | 'managed';
+  artifactUriPrefix: string | null;
+}): RemoteKnowledgeRegistryContract {
+  return {
+    contract_version: REMOTE_KNOWLEDGE_CONTRACT_VERSION,
+    service: 'open-knowledge',
+    mode: input.mode,
+    capabilities: [
+      'registry',
+      'search',
+      'ask',
+      'build',
+      'sync',
+      'status',
+      'logs',
+      'artifacts',
+      'open-files-source-refs',
+      's3-generated-artifacts',
+    ],
+    endpoints: {
+      registry: '/api/v1/knowledge/registry',
+      search: '/api/v1/knowledge/search',
+      ask: '/api/v1/knowledge/ask',
+      build: '/api/v1/knowledge/build',
+      sync: '/api/v1/knowledge/sync',
+      run_status: '/api/v1/knowledge/runs/{run_id}',
+      run_logs: '/api/v1/knowledge/runs/{run_id}/logs',
+      run_artifacts: '/api/v1/knowledge/runs/{run_id}/artifacts',
+    },
+    source_contract: {
+      owner: 'open-files',
+      preferred_ref: 'open-files',
+      allowed_schemes: input.sourceSchemes,
+      raw_source_bytes_stored_in_open_knowledge: false,
+    },
+    artifact_contract: {
+      storage_type: input.storageType,
+      uri_prefix: input.artifactUriPrefix,
+      generated_only: true,
+    },
+  };
+}
+
+export class RemoteKnowledgeClient {
+  constructor(
+    private readonly apiKey: string,
+    private readonly apiUrl: string,
+  ) {}
+
+  static fromConfig(config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): RemoteKnowledgeClient | null {
+    const key = getKnowledgeApiKey(env);
+    if (!key.apiKey) return null;
+    return new RemoteKnowledgeClient(key.apiKey, resolveKnowledgeApiUrl(config, env));
+  }
+
+  private async request(path: string, options: RequestInit = {}): Promise<Response> {
+    return fetch(`${this.apiUrl}${path}`, {
+      ...options,
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+  }
+
+  async registry(): Promise<RemoteKnowledgeRegistryContract> {
+    const response = await this.request('/api/v1/knowledge/registry');
+    return response.json() as Promise<RemoteKnowledgeRegistryContract>;
+  }
+
+  async search(request: RemoteKnowledgeSearchRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/search', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'search', query: request.query });
+  }
+
+  async ask(request: RemoteKnowledgePromptRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/ask', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'ask', prompt: request.prompt });
+  }
+
+  async build(request: RemoteKnowledgePromptRequest): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/build', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'build', prompt: request.prompt });
+  }
+
+  async sync(request: RemoteKnowledgeSyncRequest = {}): Promise<RemoteKnowledgeRunContract> {
+    const response = await this.request('/api/v1/knowledge/sync', {
+      method: 'POST',
+      body: JSON.stringify(request),
+    });
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { type: 'sync' });
+  }
+
+  async runStatus(runId: string): Promise<RemoteKnowledgeRunContract | null> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}`);
+    if (!response.ok) return null;
+    return normalizeRemoteKnowledgeRunContract(await response.json(), { id: runId, type: 'status' });
+  }
+
+  async runLogs(runId: string): Promise<RemoteKnowledgeLogEntry[]> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}/logs`);
+    if (!response.ok) return [];
+    const payload = await response.json();
+    return Array.isArray(payload) ? payload as RemoteKnowledgeLogEntry[] : [];
+  }
+
+  async runArtifacts(runId: string): Promise<RemoteKnowledgeArtifact[]> {
+    const response = await this.request(`/api/v1/knowledge/runs/${encodeURIComponent(runId)}/artifacts`);
+    if (!response.ok) return [];
+    const payload = await response.json();
+    return Array.isArray(payload) ? payload as RemoteKnowledgeArtifact[] : [];
+  }
+}