@hasna/knowledge 0.2.27 → 0.2.28

package/src/agent.ts

@@ -1,367 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
-import { languageModelFor, normalizeAiSdkUsage, parseModelRef, recordProviderUsage, resolveModelRef } from './providers';
-import { retrieveKnowledgeContext, type KnowledgeContextPack, type RetrievalOptions } from './retrieval';
-import type { KnowledgeConfig } from './workspace';
-
-export interface KnowledgePromptOptions extends Omit<RetrievalOptions, 'query'> {
-  prompt: string;
-  generate?: boolean;
-  approveWrite?: boolean;
-  now?: Date;
-}
-
-export interface KnowledgePromptResult {
-  run_id: string;
-  prompt: string;
-  generated: boolean;
-  provider: string;
-  model: string;
-  answer: string;
-  context: KnowledgeContextPack;
-  citations: KnowledgeContextPack['citations'];
-  proposed_wiki_updates: Array<{
-    kind: 'answer_note';
-    title: string;
-    citations: string[];
-    requires_approval: boolean;
-  }>;
-  write_policy: {
-    approved: boolean;
-    durable_writes_performed: false;
-    reason: string;
-  };
-  usage: {
-    input_tokens: number;
-    output_tokens: number;
-    cost_usd: number;
-  };
-  warnings: string[];
-}
-
-function estimateTokens(text: string): number {
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.max(1, Math.ceil(words * 1.25));
-}
-
-function citationLabel(index: number): string {
-  return `C${index + 1}`;
-}
-
-function localAnswer(prompt: string, context: KnowledgeContextPack): string {
-  if (context.excerpts.length === 0) {
-    return `No indexed knowledge matched the prompt: ${prompt}`;
-  }
-  const lines = [
-    `Found ${context.excerpts.length} relevant knowledge excerpt(s) for: ${prompt}`,
-    '',
-    ...context.excerpts.slice(0, 5).map((excerpt, index) => {
-      const citation = context.citations.find((entry) => entry.id === excerpt.citation_id);
-      const ref = citation?.source_ref ?? citation?.source_uri ?? citation?.artifact_path ?? citation?.artifact_uri ?? 'unknown source';
-      return `[${citationLabel(index)}] ${excerpt.text} (${ref})`;
-    }),
-  ];
-  return lines.join('\n');
-}
-
-function promptForModel(prompt: string, context: KnowledgeContextPack): string {
-  const citations = context.citations.map((citation, index) => ({
-    id: citationLabel(index),
-    source_ref: citation.source_ref,
-    source_uri: citation.source_uri,
-    artifact_path: citation.artifact_path,
-    revision: citation.revision,
-    hash: citation.hash,
-    quote: citation.quote,
-  }));
-  const excerpts = context.excerpts.map((excerpt, index) => ({
-    id: citationLabel(index),
-    kind: excerpt.kind,
-    text: excerpt.text,
-    score: excerpt.score,
-  }));
-  return [
-    `Prompt: ${prompt}`,
-    '',
-    'Use only the provided context. Cite claims with citation ids like [C1]. If context is insufficient, say what is missing.',
-    '',
-    `Context excerpts:\n${JSON.stringify(excerpts, null, 2)}`,
-    '',
-    `Citations:\n${JSON.stringify(citations, null, 2)}`,
-  ].join('\n');
-}
-
-function proposedUpdates(prompt: string, context: KnowledgeContextPack): KnowledgePromptResult['proposed_wiki_updates'] {
-  if (context.citations.length === 0) return [];
-  return [{
-    kind: 'answer_note',
-    title: prompt.length > 80 ? `${prompt.slice(0, 77)}...` : prompt,
-    citations: context.citations.map((citation) => citation.id),
-    requires_approval: true,
-  }];
-}
-
-function insertRun(dbPath: string, input: {
-  runId: string;
-  prompt: string;
-  status: string;
-  provider: string;
-  model: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `INSERT INTO runs (id, type, prompt, status, provider, model, metadata_json, created_at, updated_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-      [
-        input.runId,
-        'knowledge-prompt',
-        input.prompt,
-        input.status,
-        input.provider,
-        input.model,
-        JSON.stringify(input.metadata),
-        input.now,
-        input.now,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function addRunEvent(dbPath: string, input: {
-  runId: string;
-  level: 'info' | 'warn' | 'error';
-  event: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `INSERT INTO run_events (id, run_id, level, event, metadata_json, created_at)
-       VALUES (?, ?, ?, ?, ?, ?)`,
-      [
-        `evt_${randomUUID()}`,
-        input.runId,
-        input.level,
-        input.event,
-        JSON.stringify(input.metadata),
-        input.now,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function updateRun(dbPath: string, input: {
-  runId: string;
-  status: string;
-  provider: string;
-  model: string;
-  metadata: Record<string, unknown>;
-  now: string;
-}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    db.run(
-      `UPDATE runs
-       SET status = ?, provider = ?, model = ?, metadata_json = ?, updated_at = ?
-       WHERE id = ?`,
-      [
-        input.status,
-        input.provider,
-        input.model,
-        JSON.stringify(input.metadata),
-        input.now,
-        input.runId,
-      ],
-    );
-  } finally {
-    db.close();
-  }
-}
-
-function recordUsage(dbPath: string, runId: string, usage: KnowledgePromptResult['usage'], provider: string, model: string, now: string, metadata: Record<string, unknown> = {}): void {
-  const db = openKnowledgeDb(dbPath);
-  try {
-    recordProviderUsage(db, {
-      run_id: runId,
-      provider,
-      model,
-      input_tokens: usage.input_tokens,
-      output_tokens: usage.output_tokens,
-      cost_usd: usage.cost_usd,
-      metadata,
-      created_at: now,
-    });
-  } finally {
-    db.close();
-  }
-}
-
-export async function runKnowledgePrompt(options: KnowledgePromptOptions): Promise<KnowledgePromptResult> {
-  const prompt = options.prompt.trim();
-  if (!prompt) throw new Error('Knowledge prompt is required.');
-  const now = (options.now ?? new Date()).toISOString();
-  const runId = `run_${randomUUID()}`;
-  const modelRef = resolveModelRef(options.modelRef ?? 'default', options.config);
-  const parsed = parseModelRef(modelRef);
-
-  migrateKnowledgeDb(options.dbPath);
-  insertRun(options.dbPath, {
-    runId,
-    prompt,
-    status: options.generate ? 'running' : 'dry_run',
-    provider: options.generate ? parsed.provider : 'local',
-    model: options.generate ? parsed.model : 'context-draft',
-    metadata: {
-      semantic: options.semantic === true || options.fake === true || Boolean(options.modelRef),
-      approve_write: options.approveWrite === true,
-      generated: options.generate === true,
-    },
-    now,
-  });
-
-  const { prompt: _prompt, generate: _generate, approveWrite: _approveWrite, now: _now, ...retrievalOptions } = options;
-  const context = await retrieveKnowledgeContext({
-    ...retrievalOptions,
-    query: prompt,
-  });
-  addRunEvent(options.dbPath, {
-    runId,
-    level: 'info',
-    event: 'context_retrieved',
-    metadata: {
-      results: context.results.length,
-      citations: context.citations.length,
-      warnings: context.warnings,
-    },
-    now,
-  });
-
-  let answer = localAnswer(prompt, context);
-  let generated = false;
-  let provider = 'local';
-  let model = 'context-draft';
-  let usage = {
-    input_tokens: estimateTokens(prompt) + context.excerpts.reduce((sum, excerpt) => sum + estimateTokens(excerpt.text), 0),
-    output_tokens: estimateTokens(answer),
-    cost_usd: 0,
-  };
-  const warnings = [...context.warnings];
-
-  if (options.generate) {
-    try {
-      if (options.fake) {
-        generated = true;
-        provider = parsed.provider;
-        model = parsed.model;
-        answer = `Fake generated answer for: ${prompt}\n\n${answer}`;
-      } else {
-        const { generateText } = await import('ai');
-        const languageModel = await languageModelFor(modelRef, {
-          config: options.config,
-          env: options.env,
-        });
-        const result = await generateText({
-          model: languageModel as never,
-          system: 'You answer company knowledge-base prompts using only provided context and citation ids.',
-          prompt: promptForModel(prompt, context),
-        });
-        generated = true;
-        provider = parsed.provider;
-        model = parsed.model;
-        answer = result.text;
-        const normalized = normalizeAiSdkUsage({
-          provider,
-          model,
-          usage: result.usage as Record<string, unknown> | undefined,
-          providerMetadata: result.providerMetadata as Record<string, unknown> | undefined,
-        });
-        usage = {
-          input_tokens: normalized.input_tokens,
-          output_tokens: normalized.output_tokens,
-          cost_usd: normalized.cost_usd,
-        };
-      }
-    } catch (error) {
-      addRunEvent(options.dbPath, {
-        runId,
-        level: 'error',
-        event: 'answer_generation_failed',
-        metadata: { message: error instanceof Error ? error.message : String(error) },
-        now,
-      });
-      updateRun(options.dbPath, {
-        runId,
-        status: 'failed',
-        provider: parsed.provider,
-        model: parsed.model,
-        metadata: {
-          generated: false,
-          error: error instanceof Error ? error.message : String(error),
-        },
-        now,
-      });
-      throw error;
-    }
-  }
-
-  const updates = proposedUpdates(prompt, context);
-  const writePolicy = {
-    approved: options.approveWrite === true,
-    durable_writes_performed: false as const,
-    reason: options.approveWrite
-      ? 'Approval flag recorded; durable wiki writing is deferred to the wiki compile task.'
-      : 'Dry-run mode: proposed wiki updates require approval before durable writes.',
-  };
-  addRunEvent(options.dbPath, {
-    runId,
-    level: 'info',
-    event: generated ? 'answer_generated' : 'answer_drafted',
-    metadata: {
-      provider,
-      model,
-      proposed_updates: updates.length,
-      durable_writes_performed: false,
-    },
-    now,
-  });
-  recordUsage(options.dbPath, runId, usage, provider, model, now, {
-    generated,
-    citations: context.citations.length,
-  });
-  updateRun(options.dbPath, {
-    runId,
-    status: generated ? 'completed' : 'dry_run',
-    provider,
-    model,
-    metadata: {
-      generated,
-      citations: context.citations.length,
-      proposed_updates: updates.length,
-      approve_write: options.approveWrite === true,
-    },
-    now,
-  });
-
-  return {
-    run_id: runId,
-    prompt,
-    generated,
-    provider,
-    model,
-    answer,
-    context,
-    citations: context.citations,
-    proposed_wiki_updates: updates,
-    write_policy: writePolicy,
-    usage,
-    warnings,
-  };
-}

package/src/artifact-store.ts

@@ -1,184 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join, relative, sep } from 'node:path';
-import type { KnowledgeConfig, KnowledgeWorkspace } from './workspace';
-
-interface S3ClientLike {
-  send(command: unknown): Promise<any>;
-}
-
-export interface ArtifactWrite {
-  key: string;
-  body: string | Uint8Array;
-  content_type?: string;
-  metadata?: Record<string, string>;
-}
-
-export interface ArtifactStore {
-  readonly type: 'local' | 's3';
-  readonly canRead: boolean;
-  readonly canWrite: boolean;
-  put(entry: ArtifactWrite): Promise<{ key: string; uri: string }>;
-  getText(key: string): Promise<string>;
-  exists(key: string): Promise<boolean>;
-}
-
-export function normalizeArtifactKey(key: string): string {
-  const raw = key.replace(/\\/g, '/').trim();
-  if (!raw || raw.startsWith('/')) {
-    throw new Error(`Invalid artifact key: ${key}`);
-  }
-  const segments = raw.split('/').filter(Boolean);
-  if (segments.length === 0 || segments.some((segment) => segment === '.' || segment === '..')) {
-    throw new Error(`Invalid artifact key: ${key}`);
-  }
-  return segments.join('/');
-}
-
-function assertInside(root: string, target: string): void {
-  const rel = relative(root, target);
-  if (rel.startsWith('..') || rel === '..' || rel.startsWith(`..${sep}`)) {
-    throw new Error(`Artifact path escapes root: ${target}`);
-  }
-}
-
-export class LocalArtifactStore implements ArtifactStore {
-  readonly type = 'local' as const;
-  readonly canRead = true;
-  readonly canWrite = true;
-
-  constructor(private readonly root: string) {
-    mkdirSync(root, { recursive: true });
-  }
-
-  async put(entry: ArtifactWrite): Promise<{ key: string; uri: string }> {
-    const key = normalizeArtifactKey(entry.key);
-    const path = join(this.root, key);
-    assertInside(this.root, path);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, entry.body);
-    return { key, uri: `file://${path}` };
-  }
-
-  async getText(key: string): Promise<string> {
-    const normalizedKey = normalizeArtifactKey(key);
-    const path = join(this.root, normalizedKey);
-    assertInside(this.root, path);
-    return readFileSync(path, 'utf8');
-  }
-
-  async exists(key: string): Promise<boolean> {
-    const normalizedKey = normalizeArtifactKey(key);
-    const path = join(this.root, normalizedKey);
-    assertInside(this.root, path);
-    return existsSync(path);
-  }
-}
-
-export interface S3ArtifactStoreOptions {
-  bucket: string;
-  prefix?: string;
-  region?: string;
-  profile?: string;
-  max_attempts?: number;
-  server_side_encryption?: 'AES256' | 'aws:kms';
-  kms_key_id?: string;
-  client?: S3ClientLike;
-}
-
-export class S3ArtifactStore implements ArtifactStore {
-  readonly type = 's3' as const;
-  readonly canRead = true;
-  readonly canWrite = true;
-  private client?: S3ClientLike;
-
-  constructor(private readonly options: S3ArtifactStoreOptions) {
-    this.client = options.client;
-  }
-
-  private async getClient(): Promise<S3ClientLike> {
-    if (this.client) return this.client;
-    const [{ S3Client }, { fromIni }] = await Promise.all([
-      import('@aws-sdk/client-s3'),
-      import('@aws-sdk/credential-providers'),
-    ]);
-    this.client = new S3Client({
-      region: this.options.region,
-      credentials: this.options.profile ? fromIni({ profile: this.options.profile }) : undefined,
-      maxAttempts: this.options.max_attempts,
-    });
-    return this.client;
-  }
-
-  private objectKey(key: string): string {
-    const normalizedKey = normalizeArtifactKey(key);
-    const prefix = this.options.prefix ? normalizeArtifactKey(this.options.prefix) : '';
-    return prefix ? `${prefix}/${normalizedKey}` : normalizedKey;
-  }
-
-  async put(entry: ArtifactWrite): Promise<{ key: string; uri: string }> {
-    const [{ PutObjectCommand }, client] = await Promise.all([
-      import('@aws-sdk/client-s3'),
-      this.getClient(),
-    ]);
-    const key = this.objectKey(entry.key);
-    await client.send(new PutObjectCommand({
-      Bucket: this.options.bucket,
-      Key: key,
-      Body: entry.body,
-      ContentType: entry.content_type,
-      Metadata: entry.metadata,
-      ServerSideEncryption: this.options.server_side_encryption,
-      SSEKMSKeyId: this.options.kms_key_id,
-    }));
-    return { key, uri: `s3://${this.options.bucket}/${key}` };
-  }
-
-  async getText(key: string): Promise<string> {
-    const [{ GetObjectCommand }, client] = await Promise.all([
-      import('@aws-sdk/client-s3'),
-      this.getClient(),
-    ]);
-    const objectKey = this.objectKey(key);
-    const response = await client.send(new GetObjectCommand({
-      Bucket: this.options.bucket,
-      Key: objectKey,
-    }));
-    if (!response.Body) return '';
-    return await response.Body.transformToString();
-  }
-
-  async exists(key: string): Promise<boolean> {
-    const [{ HeadObjectCommand }, client] = await Promise.all([
-      import('@aws-sdk/client-s3'),
-      this.getClient(),
-    ]);
-    const objectKey = this.objectKey(key);
-    try {
-      await client.send(new HeadObjectCommand({
-        Bucket: this.options.bucket,
-        Key: objectKey,
-      }));
-      return true;
-    } catch (error) {
-      const name = error instanceof Error ? error.name : '';
-      if (name === 'NotFound' || name === 'NoSuchKey' || name === 'NotFoundError') return false;
-      throw error;
-    }
-  }
-}
-
-export function createArtifactStore(config: KnowledgeConfig, workspace: KnowledgeWorkspace): ArtifactStore {
-  if (config.storage.type === 's3') {
-    if (!config.storage.s3?.bucket) throw new Error('S3 artifact storage requires storage.s3.bucket');
-    return new S3ArtifactStore({
-      bucket: config.storage.s3.bucket,
-      prefix: config.storage.s3.prefix,
-      region: config.storage.s3.region,
-      profile: config.storage.s3.profile,
-      max_attempts: config.storage.s3.max_attempts,
-      server_side_encryption: config.storage.s3.server_side_encryption,
-      kms_key_id: config.storage.s3.kms_key_id,
-    });
-  }
-  return new LocalArtifactStore(workspace.artifactsDir);
-}

package/src/auth.ts

@@ -1,123 +0,0 @@
-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),
-  };
-}