@hasna/knowledge 0.2.10 → 0.2.12

package/README.md

@@ -62,6 +62,9 @@ open-knowledge export --format jsonl
 # Show resolved workspace paths
 open-knowledge paths --scope project --json
 
+# Inspect local/S3 artifact storage and source ownership
+open-knowledge storage status --scope project --json
+
 # Initialize the project SQLite catalog
 open-knowledge db init --scope project
 
@@ -82,6 +85,10 @@ open-knowledge source resolve open-files://file/f_123/revision/rev_456 --scope p
 
 # Inspect local safety policy and approvals
 open-knowledge safety status --scope project --json
+
+# Inspect AI SDK provider credentials and model aliases
+open-knowledge providers status --scope project --json
+open-knowledge providers models --scope project --json
 ```
 
 ## Commands
@@ -164,6 +171,18 @@ open-knowledge paths [--scope global|project|local] [--json]
 Show the resolved Hasna app workspace, JSON compatibility store, SQLite path,
 artifact directories, and config.
 
+### storage
+```bash
+open-knowledge storage status [--scope project] [--json]
+open-knowledge storage validate [--scope project] [--json]
+```
+Show the storage contract for local or S3-backed generated artifacts. Local mode
+uses `.hasna/apps/knowledge` for config, SQLite, indexes, wiki artifacts, logs,
+runs, and exports. S3 mode stores generated artifacts under the configured
+knowledge bucket/prefix while `open-files` remains the source of truth for raw
+source bytes. The command also reports artifact classes, allowed source ref
+schemes, and warnings for non-scalable or unsafe config.
+
 ### db
 ```bash
 open-knowledge db init [--scope project]
@@ -226,6 +245,19 @@ Inspect and operate the local safety model. Source reads are read-only by
 default, web search and S3 reads are opt-in, generated writes require approval
 by default, and known secret patterns are redacted before chunk storage.
 
+### providers
+```bash
+open-knowledge providers status [--scope project] [--json]
+open-knowledge providers models [--scope project] [--json]
+open-knowledge providers check [provider|model-alias] [--scope project] [--json]
+```
+Inspect AI SDK v6 provider readiness for OpenAI, Anthropic, and DeepSeek. The
+provider layer resolves BYOK credentials from `OPENAI_API_KEY`,
+`ANTHROPIC_API_KEY`, and `DEEPSEEK_API_KEY` by default, exposes model aliases
+such as `default`, `fast`, `reasoning`, `sonnet`, and `deepseek`, and records
+provider capability metadata for structured output, tool use, tool streaming,
+reasoning, embeddings, and native web-search support.
+
 ### help
 ```bash
 open-knowledge help [command]
@@ -260,8 +292,9 @@ open-knowledge-mcp
 The MCP server exposes item tools (`ok_add`, `ok_list`, `ok_get`, `ok_update`,
 `ok_delete`, `ok_archive`, `ok_restore`, `ok_upsert`, `ok_untag`,
 `ok_bulk_delete`, `ok_prune`, `ok_dedupe`, `ok_stats`, `ok_export`,
-`ok_import`, `ok_batch`), workspace inspection (`ok_paths`), and source-ref
-parsing/resolution (`ok_parse_source_ref`, `ok_resolve_source`).
+`ok_import`, `ok_batch`), workspace/storage inspection (`ok_paths`,
+`ok_storage_status`), and source-ref parsing/resolution
+(`ok_parse_source_ref`, `ok_resolve_source`).
 
 ## Source And Artifact Boundary
 
@@ -281,6 +314,11 @@ source ref. It does not copy raw files into the knowledge workspace; local file,
 S3, web, and open-files inputs are converted into redacted chunks with offsets,
 hashes, revision metadata, and FTS rows.
 
+AI provider configuration is local/BYOK by default. `open-knowledge` declares
+AI SDK v6 provider support through `ai`, `@ai-sdk/openai`,
+`@ai-sdk/anthropic`, and `@ai-sdk/deepseek`, but does not call providers until a
+future prompt/agent command explicitly requests a model.
+
 Generated knowledge artifacts can be stored locally under
 `.hasna/apps/knowledge/artifacts` or through the S3 artifact-store adapter.
 

package/bin/open-knowledge-mcp.js

@@ -13660,7 +13660,7 @@ import { existsSync as existsSync7, readFileSync as readFileSync7, writeFileSync
 // package.json
 var package_default = {
   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: {
@@ -13677,7 +13677,7 @@ var package_default = {
   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"
   },
@@ -13710,7 +13710,11 @@ var package_default = {
   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: {
@@ -13764,6 +13768,28 @@ function defaultKnowledgeConfig() {
       preferred_ref: "open-files",
       allowed_schemes: ["open-files", "s3", "file", "https", "http"]
     },
+    providers: {
+      default_model: "openai:gpt-5.2",
+      aliases: {
+        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"
+      },
+      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"
+      }
+    },
     safety: {
       network: {
         web_search_enabled: false,
@@ -14365,7 +14391,8 @@ function getKnowledgeDbStats(path) {
       run_events: count(db, "run_events"),
       redaction_findings: count(db, "redaction_findings"),
       audit_events: count(db, "audit_events"),
-      approval_gates: count(db, "approval_gates")
+      approval_gates: count(db, "approval_gates"),
+      storage_objects: count(db, "storage_objects")
     };
   } finally {
     db.close();
@@ -15773,6 +15800,300 @@ async function ingestSourceRef(options) {
   };
 }
 
+// src/providers.ts
+var DEFAULT_PROVIDER_SETTINGS = {
+  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"
+  }
+};
+var PROVIDER_CAPABILITIES = {
+  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
+  }
+};
+var BUILTIN_ALIASES = {
+  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(config2) {
+  return config2.providers ?? {};
+}
+function providerSettings(config2, provider) {
+  const configured = providerConfig(config2)[provider] ?? {};
+  return {
+    ...DEFAULT_PROVIDER_SETTINGS[provider],
+    ...configured
+  };
+}
+function modelAliases(config2) {
+  const configured = providerConfig(config2);
+  return {
+    ...BUILTIN_ALIASES,
+    ...configured.default_model ? { default: configured.default_model } : {},
+    ...configured.aliases ?? {}
+  };
+}
+function parseModelRef(modelRef) {
+  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 };
+}
+function resolveModelRef(aliasOrRef, config2) {
+  const aliases = modelAliases(config2);
+  return aliases[aliasOrRef] ?? aliasOrRef;
+}
+function listModelRegistry(config2) {
+  const aliases = modelAliases(config2);
+  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]
+    };
+  });
+}
+function providerCredentialStatus(config2, env = process.env) {
+  return Object.keys(DEFAULT_PROVIDER_SETTINGS).map((provider) => {
+    const settings = providerSettings(config2, 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
+    };
+  });
+}
+function providerStatus(config2, env = process.env) {
+  return {
+    default_model: resolveModelRef("default", config2),
+    providers: providerCredentialStatus(config2, env),
+    models: listModelRegistry(config2)
+  };
+}
+
+// src/storage-contract.ts
+import { createHash as createHash5, randomUUID as randomUUID4 } from "crypto";
+var GENERATED_ARTIFACTS = [
+  {
+    kind: "schema",
+    prefix: "schemas/",
+    description: "Machine-readable agent schemas and source rules."
+  },
+  {
+    kind: "index",
+    prefix: "indexes/",
+    description: "Small orientation indexes and future shard manifests."
+  },
+  {
+    kind: "log",
+    prefix: "logs/",
+    description: "Append-only JSONL run and wiki-maintenance log partitions."
+  },
+  {
+    kind: "run",
+    prefix: "runs/",
+    description: "Prompt/tool/cost ledgers and generated output records."
+  },
+  {
+    kind: "wiki_page",
+    prefix: "wiki/",
+    description: "Generated cited Markdown pages, not raw source files."
+  },
+  {
+    kind: "export",
+    prefix: "exports/",
+    description: "Portable exports and snapshots of derived knowledge state."
+  }
+];
+function hashArtifactBody(body) {
+  const bytes = typeof body === "string" ? Buffer.from(body) : Buffer.from(body);
+  return {
+    hash: `sha256:${createHash5("sha256").update(bytes).digest("hex")}`,
+    size_bytes: bytes.byteLength
+  };
+}
+function artifactKindForKey(key) {
+  const match = GENERATED_ARTIFACTS.find((entry) => key.startsWith(entry.prefix));
+  return match?.kind ?? "artifact";
+}
+function resolveStorageContract(config2, workspace, scope = "global") {
+  const validation = validateStorageConfig(config2, workspace);
+  const s3 = config2.storage.s3 ?? null;
+  const prefix = s3?.prefix?.replace(/^\/+|\/+$/g, "") ?? "";
+  const s3UriPrefix = s3 ? `s3://${s3.bucket}/${prefix ? `${prefix}/` : ""}` : "";
+  return {
+    scope,
+    mode: config2.mode,
+    storage_type: config2.storage.type,
+    workspace_home: workspace.home,
+    local_layout: {
+      app_path: HASNA_KNOWLEDGE_APP_PATH,
+      config_path: workspace.configPath,
+      json_store_path: workspace.jsonStorePath,
+      knowledge_db_path: workspace.knowledgeDbPath,
+      directories: {
+        artifacts: workspace.artifactsDir,
+        cache: workspace.cacheDir,
+        exports: workspace.exportsDir,
+        indexes: workspace.indexesDir,
+        logs: workspace.logsDir,
+        runs: workspace.runsDir,
+        schemas: workspace.schemasDir,
+        wiki: workspace.wikiDir
+      }
+    },
+    artifact_store: {
+      type: config2.storage.type,
+      artifacts_root: config2.storage.artifacts_root,
+      uri_prefix: config2.storage.type === "s3" ? s3UriPrefix : `file://${workspace.artifactsDir}/`,
+      s3: s3 ? {
+        bucket: s3.bucket,
+        prefix,
+        region: s3.region ?? null,
+        profile: s3.profile ?? null,
+        server_side_encryption: s3.server_side_encryption ?? null,
+        kms_key_configured: Boolean(s3.kms_key_id)
+      } : null
+    },
+    source_ownership: {
+      owner: "open-files",
+      preferred_ref: config2.sources.preferred_ref,
+      allowed_schemes: config2.sources.allowed_schemes,
+      raw_source_bytes_stored_in_open_knowledge: false,
+      stores: [
+        "source refs",
+        "source revisions and hashes",
+        "citation spans",
+        "redacted extracted chunks",
+        "embeddings",
+        "generated wiki artifacts",
+        "indexes",
+        "run ledgers"
+      ],
+      does_not_store: [
+        "raw open-files bytes",
+        "S3 object credentials",
+        "connector secrets",
+        "hosted tenant ownership state"
+      ]
+    },
+    generated_artifacts: GENERATED_ARTIFACTS,
+    scalability: {
+      catalog: "knowledge.db tracks sources, revisions, chunks, citations, indexes, runs, and storage_objects.",
+      indexes: "Indexes are cataloged DB rows plus sharded artifacts, not one giant index.md.",
+      logs: "Logs use dated JSONL partitions under logs/yyyy/mm/dd.jsonl.",
+      markdown: "Markdown pages are the readable wiki layer over DB/object-store state."
+    },
+    warnings: validation.warnings
+  };
+}
+function validateStorageConfig(config2, workspace) {
+  const errors3 = [];
+  const warnings = [];
+  if (!workspace.home.endsWith(HASNA_KNOWLEDGE_APP_PATH)) {
+    warnings.push(`Workspace home does not end with ${HASNA_KNOWLEDGE_APP_PATH}: ${workspace.home}`);
+  }
+  if (config2.storage.type === "s3") {
+    if (!config2.storage.s3?.bucket)
+      errors3.push("storage.s3.bucket is required when storage.type is s3.");
+    if (!config2.storage.s3?.prefix)
+      warnings.push("storage.s3.prefix is empty; generated knowledge artifacts will be written at the bucket root.");
+    if (config2.mode === "local")
+      warnings.push("storage.type is s3 while mode is local; this is valid for BYO S3, but hosted wrappers should set mode to hosted.");
+  }
+  if (config2.storage.type === "local" && config2.storage.s3) {
+    warnings.push("storage.s3 is configured but ignored while storage.type is local.");
+  }
+  if (config2.sources.preferred_ref !== "open-files") {
+    warnings.push("sources.preferred_ref should stay open-files for durable company knowledge.");
+  }
+  if (!config2.sources.allowed_schemes.includes("open-files")) {
+    errors3.push("sources.allowed_schemes must include open-files.");
+  }
+  return {
+    ok: errors3.length === 0,
+    errors: errors3,
+    warnings
+  };
+}
+function recordStorageObjects(db, objects, now = new Date) {
+  const timestamp = now.toISOString();
+  const statement = db.prepare(`
+    INSERT INTO storage_objects (
+      id, artifact_uri, kind, content_type, hash, size_bytes, metadata_json, created_at, updated_at
+    )
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(artifact_uri) DO UPDATE SET
+      kind = excluded.kind,
+      content_type = excluded.content_type,
+      hash = excluded.hash,
+      size_bytes = excluded.size_bytes,
+      metadata_json = excluded.metadata_json,
+      updated_at = excluded.updated_at
+  `);
+  const insert = db.transaction((entries) => {
+    for (const entry of entries) {
+      statement.run(randomUUID4(), entry.uri, entry.kind, entry.content_type ?? null, entry.hash ?? null, entry.size_bytes ?? null, JSON.stringify({
+        key: entry.key,
+        ...entry.metadata ?? {}
+      }), timestamp, timestamp);
+    }
+  });
+  insert(objects);
+}
+
 // src/wiki-layout.ts
 function todayParts(now) {
   const year = String(now.getUTCFullYear());
@@ -15847,19 +16168,29 @@ async function initializeWikiLayout(store, now = new Date) {
     root_index_key: rootIndexKey,
     wiki_readme_key: wikiReadmeKey
   };
-  const writes = [
-    store.put({ key: schemaKey, body: agentSchemaTemplate(), content_type: "text/markdown" }),
-    store.put({ key: rootIndexKey, body: rootIndexTemplate(), content_type: "text/markdown" }),
-    store.put({ key: wikiReadmeKey, body: wikiReadmeTemplate(), content_type: "text/markdown" }),
-    store.put({ key: logKey, body: `${JSON.stringify(event)}
-`, content_type: "application/x-ndjson" })
+  const entries = [
+    { key: schemaKey, body: agentSchemaTemplate(), content_type: "text/markdown" },
+    { key: rootIndexKey, body: rootIndexTemplate(), content_type: "text/markdown" },
+    { key: wikiReadmeKey, body: wikiReadmeTemplate(), content_type: "text/markdown" },
+    { key: logKey, body: `${JSON.stringify(event)}
+`, content_type: "application/x-ndjson" }
   ];
-  await Promise.all(writes);
+  const artifacts = await Promise.all(entries.map(async (entry) => {
+    const result = await store.put(entry);
+    return {
+      key: result.key,
+      uri: result.uri,
+      kind: artifactKindForKey(entry.key),
+      content_type: entry.content_type,
+      ...hashArtifactBody(entry.body)
+    };
+  }));
   return {
     schema_key: schemaKey,
     root_index_key: rootIndexKey,
     wiki_readme_key: wikiReadmeKey,
     log_key: logKey,
+    artifacts,
     written: [schemaKey, rootIndexKey, wikiReadmeKey, logKey]
   };
 }
@@ -15899,6 +16230,12 @@ class KnowledgeService {
   artifactStore() {
     return createArtifactStore(this.config(), this.ensureWorkspace());
   }
+  storageContract() {
+    return resolveStorageContract(this.config(), this.ensureWorkspace(), this.scope);
+  }
+  validateStorage() {
+    return validateStorageConfig(this.config(), this.ensureWorkspace());
+  }
   paths() {
     const workspace = this.ensureWorkspace();
     return {
@@ -15927,7 +16264,16 @@ class KnowledgeService {
     return getKnowledgeDbStats(workspace.knowledgeDbPath);
   }
   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) {
     const workspace = this.ensureWorkspace();
@@ -15967,6 +16313,12 @@ class KnowledgeService {
       safetyPolicy: this.safetyPolicy()
     });
   }
+  providerStatus(env = process.env) {
+    return providerStatus(this.config(), env);
+  }
+  modelRegistry() {
+    return listModelRegistry(this.config());
+  }
 }
 function createKnowledgeService(options = {}) {
   return new KnowledgeService(options);
@@ -16032,6 +16384,17 @@ function buildServer() {
   }, async ({ scope }) => {
     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: exports_external.string().describe("Source reference URI")
   }, async ({ uri }) => {
@@ -16058,6 +16421,18 @@ function buildServer() {
       return errorText(error48 instanceof Error ? error48.message : String(error48));
     }
   });
+  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: exports_external.string().describe("Item title"),
     content: exports_external.string().describe("Item content/body"),