@capekai/core 1.0.0

package/src/tools/install-manifest.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import type { InstallManifest } from '@capekai/tool';
+
+export type { InstallManifest };
+
+const INSTALL_MANIFEST = '.install-manifest.json';
+
+function isInstallManifest(data: unknown): data is InstallManifest {
+  if (typeof data !== 'object' || data === null) return false;
+  const value = data as Record<string, unknown>;
+  return typeof value.toolName === 'string'
+    && (value.toolVersion === null || typeof value.toolVersion === 'string')
+    && typeof value.installedAt === 'string'
+    && typeof value.entry === 'string'
+    && typeof value.runtime === 'string';
+}
+
+export function readInstallManifest(toolsDir: string, toolName: string): InstallManifest | null {
+  const manifestPath = join(toolsDir, toolName, INSTALL_MANIFEST);
+  if (!existsSync(manifestPath)) return null;
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+    if (!isInstallManifest(parsed)) {
+      console.warn(`[install-manifest] Invalid manifest for ${toolName}: missing required fields`);
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+export function writeInstallManifest(toolDir: string, manifest: InstallManifest): void {
+  writeFileSync(getManifestPath(toolDir), JSON.stringify(manifest, null, 2));
+}
+
+export function getManifestPath(toolDir: string): string {
+  return join(toolDir, INSTALL_MANIFEST);
+}

package/src/tools/llm-api.ts

@@ -0,0 +1,77 @@
+import { streamText, streamObject } from 'ai';
+import { jsonSchema } from 'ai';
+import type { ModelMessage } from 'ai';
+import type { LlmApi } from '@capekai/tool'
+import { LlmTextOptions, LlmStructuredOptions, LlmImage } from '@capekai/tool';
+import { getModelWithMetadata } from '../core/model-utils';
+
+export function createLlmApi(defaultModelId?: string, defaultProviderId?: string, sessionId?: string): LlmApi {
+  return {
+    async generateText(options: LlmTextOptions): Promise<string> {
+      const { model, omitMaxOutputTokens, providerOptions, useProviderInstructions } = await getModelWithMetadata({
+        modelId: options.model || defaultModelId,
+        providerId: options.provider || defaultProviderId,
+        systemPrompt: options.system,
+        sessionId,
+      });
+
+      let userContent: string | Array<{ type: 'text'; text: string } | { type: 'image'; image: string | Uint8Array; mimeType: string }> = options.prompt;
+
+      if (options.image) {
+        const images: LlmImage[] = Array.isArray(options.image) ? options.image : [options.image];
+        userContent = [
+          { type: 'text', text: options.prompt },
+          ...images.map((img) => ({
+            type: 'image' as const,
+            image: img.data,
+            mimeType: img.mediaType,
+          })),
+        ];
+      }
+
+      const stream = streamText({
+        model,
+        system: (!options.system || useProviderInstructions) ? undefined : options.system,
+        messages: [{ role: 'user' as const, content: userContent }] as ModelMessage[],
+        maxOutputTokens: omitMaxOutputTokens ? undefined : (options.maxTokens ?? 4096),
+        providerOptions: providerOptions as unknown as Parameters<typeof streamText>[0]['providerOptions'],
+      });
+
+      return stream.text;
+    },
+
+    async generateStructured<T = unknown>(options: LlmStructuredOptions): Promise<T> {
+      const { model, omitMaxOutputTokens, providerOptions, useProviderInstructions } = await getModelWithMetadata({
+        modelId: options.model || defaultModelId,
+        providerId: options.provider || defaultProviderId,
+        systemPrompt: options.system,
+        sessionId,
+      });
+
+      let userContent: string | Array<{ type: 'text'; text: string } | { type: 'image'; image: string | Uint8Array; mimeType: string }> = options.prompt;
+
+      if (options.image) {
+        const images: LlmImage[] = Array.isArray(options.image) ? options.image : [options.image];
+        userContent = [
+          { type: 'text', text: options.prompt },
+          ...images.map((img) => ({
+            type: 'image' as const,
+            image: img.data,
+            mimeType: img.mediaType,
+          })),
+        ];
+      }
+
+      const result = streamObject({
+        model,
+        system: (!options.system || useProviderInstructions) ? undefined : options.system,
+        messages: [{ role: 'user' as const, content: userContent }] as ModelMessage[],
+        schema: jsonSchema(options.schema),
+        maxOutputTokens: omitMaxOutputTokens ? undefined : (options.maxTokens ?? 4096),
+        providerOptions: providerOptions as unknown as Parameters<typeof streamObject>[0]['providerOptions'],
+      });
+
+      return result.object as Promise<T>;
+    },
+  };
+}

package/src/tools/registry.ts

@@ -0,0 +1,206 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readdir } from 'fs/promises';
+import { existsSync } from 'fs';
+import { watch } from 'fs';
+import { basename, dirname, join, resolve, relative } from 'path';
+import type { ToolDefinition } from '@capekai/tool'
+import { LoadedTool } from '@capekai/tool';
+import { readInstallManifest } from './install-manifest';
+
+export interface ToolRegistryResolver {
+  get(name: string): LoadedTool | null;
+  list(): LoadedTool[];
+}
+
+const toolsCache: Map<string, LoadedTool> = new Map();
+const scopedResolver = new AsyncLocalStorage<ToolRegistryResolver>();
+let lastScanTime = 0;
+const CACHE_TTL = 60000;
+
+let watcher: ReturnType<typeof watch> | null = null;
+let debounceTimer: ReturnType<typeof setTimeout> | null = null;
+let watcherToolsPath: string | null = null;
+let defaultToolsPath: string | null = null;
+
+export function withToolRegistryResolver<T>(resolver: ToolRegistryResolver, callback: () => T): T {
+  return scopedResolver.run(resolver, callback);
+}
+
+/** True when an ambient scoped tool resolver is installed. The legacy
+ * unscoped execution path keeps its unconditional builtin-tool injection;
+ * scoped compositions resolve every tool, including retrieve-tool-output,
+ * through their resolver instead. */
+export function hasScopedToolRegistryResolver(): boolean {
+  return scopedResolver.getStore() !== undefined;
+}
+
+export function configureToolsPath(path?: string): void {
+  defaultToolsPath = path ? resolve(path) : null;
+  clearCache();
+}
+
+function getDefaultToolsPath(): string | null {
+  return defaultToolsPath;
+}
+
+export async function loadToolModule(toolDir: string): Promise<LoadedTool | null> {
+  const toolName = basename(toolDir);
+  const toolsBasePath = dirname(toolDir);
+  const manifest = readInstallManifest(toolsBasePath, toolName);
+  let modulePath: string | null = null;
+
+  if (manifest?.entry) {
+    const manifestEntryPath = join(toolDir, manifest.entry);
+    if (existsSync(manifestEntryPath)) modulePath = manifestEntryPath;
+  }
+
+  if (!modulePath) {
+    const toolJsPath = join(toolDir, 'tool.js');
+    const toolTsPath = join(toolDir, 'tool.ts');
+    if (existsSync(toolJsPath)) modulePath = toolJsPath;
+    else if (existsSync(toolTsPath)) modulePath = toolTsPath;
+  }
+
+  if (!modulePath) return null;
+
+  try {
+    const module = await import(modulePath);
+    if (!module.definition || typeof module.execute !== 'function') {
+      console.warn(`Tool at ${toolDir} missing required exports (definition, execute)`);
+      return null;
+    }
+    const definition: ToolDefinition = module.definition;
+    if (!definition.name || !definition.inputSchema) {
+      console.warn(`Tool at ${toolDir} has invalid definition (missing name or inputSchema)`);
+      return null;
+    }
+    return { definition, execute: module.execute, path: toolDir };
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.includes('Cannot find module')) console.warn(`Tool at ${toolDir} has missing dependencies: ${message}`);
+    else if (message.includes('SyntaxError') || message.includes('Unexpected')) console.warn(`Tool at ${toolDir} has a syntax/load error: ${message}`);
+    else console.warn(`Failed to load tool module at ${toolDir}:`, error);
+    return null;
+  }
+}
+
+function invalidateToolAtPath(filePath: string): void {
+  if (!watcherToolsPath) return;
+  const relativePath = relative(watcherToolsPath, filePath);
+  const toolDir = relativePath.split(/[\\/]/)[0];
+  if (!toolDir || toolDir === '.' || toolDir === '..') return;
+  const toolPath = join(watcherToolsPath, toolDir);
+  const key = [...toolsCache.keys()].find((name) => toolsCache.get(name)?.path === toolPath);
+  if (key) toolsCache.delete(key);
+}
+
+function scheduleInvalidation(filePath: string): void {
+  if (debounceTimer) clearTimeout(debounceTimer);
+  debounceTimer = setTimeout(() => {
+    invalidateToolAtPath(filePath);
+    debounceTimer = null;
+  }, 100);
+}
+
+export function watchTools(toolsPath: string | null = getDefaultToolsPath()): void {
+  if (!toolsPath) return;
+  if (watcher) stopWatching();
+  const absoluteToolsPath = resolve(toolsPath);
+  watcherToolsPath = absoluteToolsPath;
+  try {
+    watcher = watch(absoluteToolsPath, { recursive: true }, (_event, filename) => {
+      if (filename) scheduleInvalidation(join(absoluteToolsPath, filename));
+    });
+    watcher.on('error', (error) => console.warn(`Tool watcher error: ${error}`));
+  } catch {
+    console.warn(`Failed to start tool watcher for: ${absoluteToolsPath}`);
+    watcherToolsPath = null;
+  }
+}
+
+export function stopWatching(): void {
+  if (debounceTimer) {
+    clearTimeout(debounceTimer);
+    debounceTimer = null;
+  }
+  if (watcher) {
+    watcher.close();
+    watcher = null;
+  }
+  watcherToolsPath = null;
+}
+
+export async function scanTools(toolsPath: string | null = getDefaultToolsPath()): Promise<LoadedTool[]> {
+  const tools: LoadedTool[] = [];
+  if (toolsPath) {
+    const absoluteToolsPath = resolve(toolsPath);
+    try {
+      const entries = await readdir(absoluteToolsPath, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory() || entry.name.endsWith('.staging') || entry.name.endsWith('.previous')) continue;
+        const loaded = await loadToolModule(join(absoluteToolsPath, entry.name));
+        if (loaded) tools.push(loaded);
+      }
+    } catch {
+      console.warn(`Tools directory not found: ${absoluteToolsPath}`);
+    }
+  }
+
+  toolsCache.clear();
+  for (const loaded of tools) toolsCache.set(loaded.definition.name, loaded);
+  lastScanTime = Date.now();
+  return tools;
+}
+
+let ensureScannedPromise: Promise<void> | null = null;
+
+function ensureScanned(): Promise<void> {
+  if (Date.now() - lastScanTime < CACHE_TTL) return Promise.resolve();
+  if (ensureScannedPromise === null) {
+    ensureScannedPromise = scanTools().then(() => undefined).finally(() => {
+      ensureScannedPromise = null;
+    });
+  }
+  return ensureScannedPromise;
+}
+
+export async function getTool(name: string): Promise<LoadedTool | null> {
+  const resolver = scopedResolver.getStore();
+  if (resolver) return resolver.get(name);
+  await ensureScanned();
+  return toolsCache.get(name) ?? null;
+}
+
+export async function listTools(): Promise<ToolDefinition[]> {
+  const resolver = scopedResolver.getStore();
+  if (resolver) return resolver.list().map((loaded) => loaded.definition);
+  await ensureScanned();
+  return [...toolsCache.values()].map((loaded) => loaded.definition);
+}
+
+/** Synchronous cache read of one installed tool. Ignores any ambient
+ * scoped resolver: this is the dir-scan branch of `getTool`, for
+ * resolver implementations that layer installed tools beneath their
+ * own contributions. Returns null when the cache has not been scanned
+ * (or the name is unknown); callers own ensuring a scan happened. */
+export function getInstalledTool(name: string): LoadedTool | null {
+  return toolsCache.get(name) ?? null;
+}
+
+/** Synchronous snapshot of the installed-tools cache. Ignores any
+ * ambient scoped resolver, like `getInstalledTool`. Empty when the
+ * cache has not been scanned. */
+export function listInstalledTools(): LoadedTool[] {
+  return [...toolsCache.values()];
+}
+
+/** True when the installed-tools cache is empty because no scan has
+ * run yet (as opposed to a genuinely empty tools directory). */
+export function hasUnscannedToolCache(): boolean {
+  return lastScanTime === 0;
+}
+
+export function clearCache(): void {
+  toolsCache.clear();
+  lastScanTime = 0;
+}

package/src/tools/tool-artifact.ts

@@ -0,0 +1,182 @@
+import { createReadStream, existsSync, mkdirSync, readdirSync } from 'fs';
+import { join, basename, dirname } from 'path';
+import * as tar from 'tar';
+import { BlobReader, ZipReader, BlobWriter } from '@zip.js/zip.js';
+import { createHash } from 'crypto';
+
+export class ArtifactError extends Error {
+  constructor(message: string, public readonly stage: string) {
+    super(message);
+    this.name = 'ArtifactError';
+  }
+}
+
+export interface DownloadResult {
+  archivePath: string;
+}
+
+export async function downloadArtifact(
+  url: string,
+  destDir: string,
+): Promise<DownloadResult> {
+  mkdirSync(destDir, { recursive: true });
+
+  const urlPath = new URL(url).pathname;
+  const archiveName = basename(urlPath) || 'artifact';
+  const archivePath = join(destDir, archiveName);
+
+  let response: Response;
+  try {
+    response = await fetch(url);
+    if (!response.ok) {
+      throw new ArtifactError(
+        `HTTP ${response.status}: ${response.statusText}`,
+        'download',
+      );
+    }
+    const buffer = await response.arrayBuffer();
+    await Bun.write(archivePath, buffer);
+  } catch (err: unknown) {
+    if (err instanceof ArtifactError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ArtifactError(`Download failed: ${message}`, 'download');
+  }
+
+  return { archivePath };
+}
+
+export async function verifyChecksum(
+  archivePath: string,
+  expectedSha256: string | undefined,
+): Promise<void> {
+  if (!expectedSha256) {
+    return;
+  }
+
+  if (expectedSha256.trim() === '') {
+    return;
+  }
+
+  const hash = createHash('sha256');
+  const stream = createReadStream(archivePath);
+
+  return new Promise((resolve, reject) => {
+    stream.on('data', (data) => hash.update(data));
+    stream.on('end', () => {
+      const actual = hash.digest('hex');
+      if (actual !== expectedSha256) {
+        reject(
+          new ArtifactError(
+            `Checksum mismatch: expected ${expectedSha256}, got ${actual}`,
+            'checksum',
+          ),
+        );
+      } else {
+        resolve();
+      }
+    });
+    stream.on('error', (err) =>
+      reject(new ArtifactError(`Checksum read failed: ${err.message}`, 'checksum')),
+    );
+  });
+}
+
+export async function extractArtifact(
+  archivePath: string,
+  destDir: string,
+): Promise<string> {
+  const lower = archivePath.toLowerCase();
+
+  try {
+    if (lower.endsWith('.tar.gz') || lower.endsWith('.tgz')) {
+      await extractTarGz(archivePath, destDir);
+    } else if (lower.endsWith('.zip')) {
+      await extractZip(archivePath, destDir);
+    } else {
+      throw new ArtifactError(
+        `Unsupported archive format: ${archivePath}`,
+        'extract',
+      );
+    }
+  } catch (err: unknown) {
+    if (err instanceof ArtifactError) throw err;
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ArtifactError(`Extraction failed: ${message}`, 'extract');
+  }
+
+  const extractedRoot = findExtractedRoot(destDir);
+  return extractedRoot;
+}
+
+async function extractTarGz(tarPath: string, destDir: string): Promise<void> {
+  await tar.x({
+    file: tarPath,
+    cwd: destDir,
+    strip: 0,
+  });
+}
+
+async function extractZip(zipPath: string, destDir: string): Promise<void> {
+  const file = Bun.file(zipPath);
+  const blob = new Blob([await file.arrayBuffer()]);
+  const reader = new ZipReader(new BlobReader(blob));
+
+  const entries = await reader.getEntries();
+  for (const entry of entries) {
+    const entryPath = join(destDir, entry.filename);
+
+    if (entry.directory) {
+      mkdirSync(entryPath, { recursive: true });
+      continue;
+    }
+
+    mkdirSync(dirname(entryPath), { recursive: true });
+    const writer = new BlobWriter();
+    await entry.getData(writer);
+    const data = await writer.getData();
+    await Bun.write(entryPath, data);
+  }
+
+  await reader.close();
+}
+
+function findExtractedRoot(destDir: string): string {
+  const entries = readdirSync(destDir, { withFileTypes: true });
+  const nonMetaEntries = entries.filter(
+    (e) => !e.name.startsWith('.') && e.name !== 'archive' && !e.name.endsWith('.tar.gz') && !e.name.endsWith('.tgz') && !e.name.endsWith('.zip'),
+  );
+
+  if (nonMetaEntries.length === 1 && nonMetaEntries[0].isDirectory()) {
+    return join(destDir, nonMetaEntries[0].name);
+  }
+
+  return destDir;
+}
+
+export interface ArtifactValidation {
+  entrypoint: string;
+  hasPackageJson: boolean;
+  hasVersion: boolean;
+}
+
+export function validateArtifactStructure(
+  extractedRoot: string,
+  entry: string,
+): ArtifactValidation {
+  const entryPath = join(extractedRoot, entry);
+  if (!existsSync(entryPath)) {
+    throw new ArtifactError(
+      `Entrypoint not found: ${entry}`,
+      'validate',
+    );
+  }
+
+  const hasPackageJson = existsSync(join(extractedRoot, 'package.json'));
+  const hasVersion = existsSync(join(extractedRoot, 'VERSION'));
+
+  return {
+    entrypoint: entryPath,
+    hasPackageJson,
+    hasVersion,
+  };
+}

package/src/tools/tool-source.ts

@@ -0,0 +1,53 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { Tool } from 'ai';
+
+/**
+ * Per-workspace dynamic tool discovery seam. The workspacePath is a scoping
+ * key for discovery (for example, which MCP servers are configured for that
+ * workspace), not a directory tools are stored in: installed tool packages
+ * resolve through the tools directory registry, not through this contract.
+ */
+export interface WorkspaceToolDiscovery {
+  initializeWorkspace?(workspacePath: string): Promise<void>;
+  discoverTools?(workspacePath: string, sessionId?: string): Promise<Record<string, Tool>>;
+}
+
+const defaultWorkspaceToolDiscovery: Required<WorkspaceToolDiscovery> = {
+  async initializeWorkspace(): Promise<void> {},
+  async discoverTools(): Promise<Record<string, Tool>> {
+    return {};
+  },
+};
+
+let workspaceToolDiscovery: WorkspaceToolDiscovery = defaultWorkspaceToolDiscovery;
+const scopedWorkspaceToolDiscovery = new AsyncLocalStorage<WorkspaceToolDiscovery>();
+
+function activeWorkspaceToolDiscovery(): WorkspaceToolDiscovery {
+  return scopedWorkspaceToolDiscovery.getStore() ?? workspaceToolDiscovery;
+}
+
+export function withWorkspaceToolDiscovery<T>(
+  discovery: WorkspaceToolDiscovery,
+  callback: () => T,
+): T {
+  return scopedWorkspaceToolDiscovery.run(discovery, callback);
+}
+
+export function configureWorkspaceToolDiscovery(discovery?: WorkspaceToolDiscovery): void {
+  workspaceToolDiscovery = discovery ?? defaultWorkspaceToolDiscovery;
+}
+
+export function getWorkspaceToolDiscovery(): WorkspaceToolDiscovery {
+  return activeWorkspaceToolDiscovery();
+}
+
+export async function initializeWorkspaceDiscovery(workspacePath: string): Promise<void> {
+  await activeWorkspaceToolDiscovery().initializeWorkspace?.(workspacePath);
+}
+
+export async function discoverWorkspaceTools(
+  workspacePath: string,
+  sessionId?: string,
+): Promise<Record<string, Tool>> {
+  return await activeWorkspaceToolDiscovery().discoverTools?.(workspacePath, sessionId) ?? {};
+}