@tyvm/knowhow 0.0.91 → 0.0.93

package/.depcheckrc

@@ -18,7 +18,6 @@
     "@types/ws",
     "@babel/preset-typescript"
   ],
-  "skip-missing": true,
   "ignore-patterns": [
     "src/dataset/**",
     "ts_build/**",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.91",
+  "version": "0.0.93",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {
@@ -13,7 +13,8 @@
     "start": "npm run compile && node --no-node-snapshot ts_build/src/server/index.js",
     "dataset:diffs:generate": "ts-node src/dataset/diffs/generate.ts",
     "dataset:diffs:jsonl": "ts-node src/dataset/diffs/jsonl.ts",
-    "prepublishOnly": "npm run compile",
+    "prepublishOnly": "npm run compile && bash scripts/check-isolated-deps.sh",
+    "check:isolated": "bash scripts/check-isolated-deps.sh",
     "lint": "tslint ./src/**/*.ts",
     "lint:deps": "depcheck --config=.depcheckrc",
     "lint:all": "npm run lint && npm run lint:deps"
@@ -23,6 +24,7 @@
   "license": "MIT",
   "devDependencies": {
     "@babel/preset-typescript": "^7.23.3",
+    "typescript": "^5.0.0",
     "@types/diff": "^5.2.1",
     "@types/express": "^4.17.13",
     "@types/jest": "^29.5.13",
@@ -39,7 +41,6 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
-    "@aws-sdk/client-s3": "^3.588.0",
     "@google/genai": "^0.14.1",
     "@inquirer/editor": "^4.2.18",
     "@modelcontextprotocol/sdk": "^1.13.3",
@@ -58,9 +59,8 @@
     "node-jq": "^6.0.1",
     "openai": "4.89.1",
     "pdf-parse": "^1.1.1",
-    "typescript": "^4.6.3",
     "ws": "^8.18.1",
-    "zod": "^3.24.2"
+    "zod": "^3.25.0"
   },
   "directories": {
     "test": "tests"
@@ -73,5 +73,8 @@
   "bugs": {
     "url": "https://github.com/tyvm-ai/knowhow/issues"
   },
-  "homepage": "https://github.com/tyvm-ai/knowhow#readme"
+  "homepage": "https://github.com/tyvm-ai/knowhow#readme",
+  "optionalDependencies": {
+    "esbuild-register": "^3.0.0"
+  }
 }

package/scripts/check-isolated-deps.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# check-isolated-deps.sh
+# Verifies that packages/knowhow only imports dependencies it actually declares.
+# Runs tsc in an isolated temp directory with NO parent node_modules available,
+# so any dep resolved from the monorepo root will cause a real compile failure.
+#
+# Usage: bash scripts/check-isolated-deps.sh
+# Also used as the "prepublishOnly" hook to prevent publishing broken packages.
+
+set -e
+
+PACKAGE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MONOREPO_ROOT="$(cd "$PACKAGE_DIR/../.." && pwd)"
+TUNNEL_DIR="$MONOREPO_ROOT/packages/knowhow-tunnel"
+
+echo "=== Isolated dependency check for @tyvm/knowhow ==="
+echo "Package dir: $PACKAGE_DIR"
+
+# 1. Build knowhow-tunnel so we can pack it
+echo ""
+echo "--- Building knowhow-tunnel ---"
+cd "$TUNNEL_DIR"
+npm run build --silent
+
+# Pack and capture just the filename (redirect stderr so npm warnings don't corrupt JSON)
+TUNNEL_TARBALL=$(npm pack --json 2>/dev/null | node -e "process.stdin.resume(); let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>console.log(JSON.parse(d)[0].filename))")
+TUNNEL_TARBALL_PATH="$TUNNEL_DIR/$TUNNEL_TARBALL"
+echo "Packed tunnel: $TUNNEL_TARBALL_PATH"
+
+# 2. Create isolated temp directory
+WORK_DIR=$(mktemp -d)
+trap "rm -rf '$WORK_DIR'; rm -f '$TUNNEL_TARBALL_PATH'" EXIT
+echo ""
+echo "--- Creating isolated workspace at $WORK_DIR ---"
+
+# 3. Copy package source (excluding node_modules and ts_build)
+rsync -a \
+  --exclude='node_modules' \
+  --exclude='ts_build' \
+  --exclude='.knowhow' \
+  --exclude='scripts' \
+  "$PACKAGE_DIR/" "$WORK_DIR/"
+
+# 4. Copy the tunnel tarball into work dir and rewrite the dependency
+cp "$TUNNEL_TARBALL_PATH" "$WORK_DIR/$TUNNEL_TARBALL"
+cd "$WORK_DIR"
+
+# Replace workspace dep reference with local tarball path
+node -e "
+  const fs = require('fs');
+  const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
+  pkg.dependencies['@tyvm/knowhow-tunnel'] = 'file:./' + process.argv[1];
+  fs.writeFileSync('./package.json', JSON.stringify(pkg, null, 2));
+" "$TUNNEL_TARBALL"
+
+echo "Updated @tyvm/knowhow-tunnel dep to local tarball"
+
+# 5. Install in isolated dir (include devDeps for tsc) — NO parent node_modules accessible
+echo ""
+echo "--- Running npm install (isolated, including devDependencies) ---"
+npm install --ignore-scripts 2>&1 | grep -v "^npm warn deprecated" | grep -v "^$" || true
+
+# 6. Run tsc --noEmit from the isolated dir
+echo ""
+echo "--- Running tsc --noEmit (isolated) ---"
+./node_modules/.bin/tsc --noEmit
+
+echo ""
+echo "=== Isolated dependency check PASSED ==="

package/src/agents/configurable/ConfigAgent.ts

@@ -1,8 +1,8 @@
 import { AgentContext, BaseAgent } from "../base/base";
 import { Message } from "../../clients/types";
 import { Assistant, Config } from "../../types";
-import { EventService, ToolsService } from "src/services";
-import { MessageProcessor } from "src/services/MessageProcessor";
+import { EventService, ToolsService } from "../../services";
+import { MessageProcessor } from "../../services/MessageProcessor";
 
 export class ConfigAgent extends BaseAgent {
   name: string;

package/src/chat/modules/AgentModule.ts

@@ -37,7 +37,6 @@ import {
   agents,
 } from "../../agents";
 import { ToolCallEvent } from "../../agents/base/base";
-import { $Command } from "@aws-sdk/client-s3";
 import { KnowhowSimpleClient } from "../../services/KnowhowClient";
 
 export class AgentModule extends BaseChatModule {

package/src/chat/types.ts

@@ -3,7 +3,7 @@
  */
 import { ChatInteraction, Config } from "../types";
 import { BaseAgent } from "../agents/base/base";
-import { ToolsService } from "src/services";
+import { ToolsService } from "../services";
 import { AgentRenderer } from "./renderer/types";
 
 export interface ChatContext {

package/src/clients/gemini.ts

@@ -688,7 +688,7 @@ export class GenericGeminiClient implements GenericClient {
       const mimeType = audioPart.inlineData.mimeType || "audio/wav";
 
       // Gemini returns raw PCM (audio/L16) - convert to WAV format for playability
-      let audioBuffer = rawBuffer;
+      let audioBuffer: Buffer = rawBuffer;
       if (mimeType.includes("L16") || mimeType.includes("pcm")) {
         // Parse sample rate from mime type e.g. "audio/L16;codec=pcm;rate=24000"
         const rateMatch = mimeType.match(/rate=(\d+)/);
@@ -883,7 +883,7 @@ export class GenericGeminiClient implements GenericClient {
    */
   async uploadFile(options: FileUploadOptions): Promise<FileUploadResponse> {
     try {
-      const blob = new Blob([options.data], { type: options.mimeType });
+      const blob = new Blob([new Uint8Array(options.data)], { type: options.mimeType });
       const uploadedFile = await this.client.files.upload({
         file: blob,
         config: {

package/src/clients/openai.ts

@@ -398,7 +398,7 @@ export class GenericOpenAiClient implements GenericClient {
     if (!apiKey) throw new Error("OpenAI API key not set");
     const formData = new FormData();
     formData.append("purpose", "assistants");
-    const blob = new Blob([options.data], { type: options.mimeType || "application/octet-stream" });
+    const blob = new Blob([new Uint8Array(options.data)], { type: options.mimeType || "application/octet-stream" });
     formData.append("file", blob, options.fileName || "upload");
     const response = await fetch("https://api.openai.com/v1/files", {
       method: "POST",

package/src/clients/xai.ts

@@ -345,7 +345,7 @@ export class GenericXAIClient implements GenericClient {
 
     const formData = new FormData();
     formData.append("purpose", "assistants");
-    const blob = new Blob([options.data], { type: options.mimeType || "application/octet-stream" });
+    const blob = new Blob([new Uint8Array(options.data)], { type: options.mimeType || "application/octet-stream" });
     formData.append("file", blob, options.fileName || "upload");
 
     const response = await fetch("https://api.x.ai/v1/files", {

package/src/index.ts

@@ -105,7 +105,7 @@ export async function purge(globPath: string) {
 
 export async function upload() {
   const config = await getConfig();
-  const { AwsS3, knowhowApiClient } = services();
+  const { AwsS3, Embeddings, knowhowApiClient } = services();
 
   for (const source of config.embedSources) {
     const bucketName = source.remote;
@@ -125,16 +125,15 @@ export async function upload() {
       items,
     };
 
-    if (source.remoteType === "s3") {
+    if (Embeddings.hasResolver(source.remoteType) && source.remoteType !== "knowhow") {
       console.log(
         "Uploading",
         source.output,
         "to",
         `${bucketName}/${embeddingName}.json`
       );
-
-      const s3Key = `${embeddingName}.json`;
-      await AwsS3.uploadFile(source.output, bucketName, s3Key);
+      const remoteKey = `${embeddingName}.json`;
+      await Embeddings.upload(source.remoteType, source.output, bucketName, remoteKey);
     } else if (source.remoteType === "knowhow") {
       if (!source.remoteId) {
         throw new Error("remoteId is required for knowhow uploads");
@@ -357,7 +356,7 @@ export async function handleSingleOutputGeneration(
 
 export async function download() {
   const config = await getConfig();
-  const { AwsS3, GitHub, knowhowApiClient } = services();
+  const { AwsS3, Embeddings, knowhowApiClient } = services();
 
   for (const source of config.embedSources) {
     const { remote, remoteType } = source;
@@ -375,28 +374,17 @@ export async function download() {
     const fileName = `${name}.json`;
     const destinationPath = source.output;
 
-    if (remoteType === "s3") {
-      const bucketName = remote;
+    if (Embeddings.hasResolver(remoteType)) {
       console.log(
         "Downloading",
         fileName,
         `from ${remoteType}`,
-        bucketName,
-        "to",
-        destinationPath
-      );
-      await AwsS3.downloadFile(bucketName, fileName, destinationPath);
-    } else if (remoteType === "github") {
-      console.log(
-        "Downloading",
-        fileName,
-        "from GitHub repo",
         remote,
         "to",
         destinationPath
       );
       const embeddingPath = ".knowhow/embeddings/" + fileName;
-      await GitHub.downloadFile(remote, embeddingPath, destinationPath);
+      await Embeddings.download(remoteType, remote, embeddingPath, destinationPath);
     } else if (remoteType === "knowhow") {
       if (!source.remoteId) {
         throw new Error("remoteId is required for knowhow downloads");

package/src/services/EmbeddingsService.ts

@@ -0,0 +1,70 @@
+type DownloaderFn = (
+  remote: string,
+  filePath: string,
+  destinationPath: string
+) => Promise<void>;
+
+type UploaderFn = (
+  localPath: string,
+  remote: string,
+  remoteKey: string
+) => Promise<void>;
+
+export interface EmbeddingsResolver {
+  download: DownloaderFn;
+  upload?: UploaderFn;
+}
+
+/**
+ * EmbeddingsService manages pluggable resolvers for remote embedding sources.
+ * Modules can register a resolver for a given remoteType (e.g. "github", "s3")
+ * via registerResolver(), and the core upload()/download() functions delegate to it.
+ */
+export class EmbeddingsService {
+  private resolvers = new Map<string, EmbeddingsResolver>();
+
+  registerResolver(remoteType: string, resolver: EmbeddingsResolver): void {
+    this.resolvers.set(remoteType, resolver);
+  }
+
+  hasResolver(remoteType: string): boolean {
+    return this.resolvers.has(remoteType);
+  }
+
+  async download(
+    remoteType: string,
+    remote: string,
+    filePath: string,
+    destinationPath: string
+  ): Promise<void> {
+    const resolver = this.resolvers.get(remoteType);
+    if (!resolver) {
+      throw new Error(
+        `No resolver registered for remoteType: "${remoteType}". ` +
+          `Install and configure the appropriate knowhow module (e.g. @tyvm/knowhow-module-github).`
+      );
+    }
+    await resolver.download(remote, filePath, destinationPath);
+  }
+
+  async upload(
+    remoteType: string,
+    localPath: string,
+    remote: string,
+    remoteKey: string
+  ): Promise<void> {
+    const resolver = this.resolvers.get(remoteType);
+    if (!resolver) {
+      throw new Error(
+        `No resolver registered for remoteType: "${remoteType}". ` +
+          `Install and configure the appropriate knowhow module (e.g. @tyvm/knowhow-module-s3).`
+      );
+    }
+    if (!resolver.upload) {
+      throw new Error(
+        `Resolver for remoteType: "${remoteType}" does not support uploads.`
+      );
+    }
+    await resolver.upload(localPath, remote, remoteKey);
+  }
+}

package/src/services/KnowhowClient.ts

@@ -248,7 +248,7 @@ export class KnowhowSimpleClient {
     if (Buffer.isBuffer(options.file)) {
       formData.append(
         "file",
-        new Blob([options.file]),
+        new Blob([new Uint8Array(options.file)]),
         options.fileName || "audio.mp3"
       );
     } else {

package/src/services/Mcp.ts

@@ -23,11 +23,7 @@ export const knowhowMcpClient = {
   version: "1.0.0",
 };
 export const knowhowConfig = {
-  capabilities: {
-    prompts: {},
-    resources: {},
-    tools: {},
-  },
+  capabilities: {},
 };
 
 export * from "./McpServer";

package/src/services/S3.ts

@@ -1,86 +1,18 @@
-import {
-  S3Client,
-  HeadBucketCommand,
-  CreateBucketCommand,
-  GetObjectCommand,
-  PutObjectCommand,
-  GetObjectCommandInput,
-  PutObjectCommandInput,
-} from "@aws-sdk/client-s3";
-
 import * as fs from "fs";
-const fsPromises = fs.promises;
-import { createWriteStream } from "fs";
-import * as path from "path";
+import { createWriteStream, createReadStream } from "fs";
 import { pipeline, Readable } from "stream";
 import * as util from "util";
 
-import { createReadStream } from "fs";
 const pipelineAsync = util.promisify(pipeline);
 
 export class S3Service {
-  private s3: S3Client;
-
-  constructor() {
-    this.s3 = new S3Client();
-  }
-
-  async uploadFile(
-    filePath: string,
-    bucketName: string,
-    key: string
-  ): Promise<void> {
-    const fileContent = await fsPromises.readFile(filePath);
-
-    const params = {
-      Bucket: bucketName,
-      Key: key,
-      Body: fileContent,
-    };
-
-    // create bucket if it doesn't exist
-    try {
-      await this.s3.send(new HeadBucketCommand({ Bucket: bucketName }));
-    } catch (error) {
-      const statusCode = error.$metadata.httpStatusCode;
-      if (statusCode === 404) {
-        await this.s3.send(new CreateBucketCommand({ Bucket: bucketName }));
-        console.log(`Bucket ${bucketName} created successfully`);
-      } else {
-        throw error;
-      }
-    }
-
-    await this.s3.send(new PutObjectCommand(params));
-    console.log(`File uploaded successfully to ${bucketName}/${key}`);
-  }
-
-  async downloadFile(
-    bucketName: string,
-    key: string,
-    destinationPath: string
-  ): Promise<void> {
-    const params = {
-      Bucket: bucketName,
-      Key: key,
-    };
-    const { Body } = await this.s3.send(new GetObjectCommand(params));
-    const fileStream = createWriteStream(destinationPath);
-
-    await pipelineAsync(Body as NodeJS.ReadableStream, fileStream);
-
-    console.log(
-      `File downloaded successfully from ${bucketName}/${key} to ${destinationPath}`
-    );
-  }
-
   async uploadToPresignedUrl(
     presignedUrl: string,
     filePath: string
   ): Promise<void> {
     try {
       const fileStream = createReadStream(filePath);
-      const fileStats = await fsPromises.stat(filePath);
+      const fileStats = await fs.promises.stat(filePath);
 
       const response = await fetch(presignedUrl, {
         method: "PUT",

package/src/services/index.ts

@@ -2,7 +2,7 @@ import { AIClient, Clients } from "../clients";
 import { AgentService } from "./AgentService";
 import { EventService } from "./EventService";
 import { FlagsService } from "./flags";
-import { GitHubService } from "./GitHub";
+import { EmbeddingsService } from "./EmbeddingsService";
 import { KnowhowSimpleClient } from "./KnowhowClient";
 import { McpService } from "./Mcp";
 import { S3Service } from "./S3";
@@ -18,7 +18,7 @@ import { MediaProcessorService } from "./MediaProcessorService";
 export * from "./AgentService";
 export * from "./EventService";
 export * from "./flags";
-export * from "./GitHub";
+export * from "./EmbeddingsService";
 export * from "./S3";
 export * from "./Tools";
 export * from "./LazyToolsService";
@@ -38,8 +38,8 @@ let Singletons = {} as {
   Tools: ToolsService;
   Events: EventService;
   Agents: AgentService;
+  Embeddings: EmbeddingsService;
   Flags: FlagsService;
-  GitHub: GitHubService;
   Mcp: McpService;
   AwsS3: S3Service;
   Docker: DockerService;
@@ -67,8 +67,8 @@ export const services = (): typeof Singletons => {
       Clients,
       Docker: new DockerService(),
       Events,
+      Embeddings: new EmbeddingsService(),
       Flags: new FlagsService(),
-      GitHub: new GitHubService(),
       Mcp: new McpService(),
       MediaProcessor: new MediaProcessorService(Clients),
       Plugins,

package/src/services/modules/index.ts

@@ -10,9 +10,10 @@ export class ModulesService {
 
     // If no context provided, fall back to global singletons
     if (!context) {
-      const { Clients, Plugins, Agents, Tools, MediaProcessor } = services();
+      const { Clients, Plugins, Agents, Tools, Embeddings, MediaProcessor } = services();
       context = {
         Agents,
+        Embeddings,
         Plugins,
         Clients,
         Tools,
@@ -35,7 +36,7 @@ export class ModulesService {
 
     for (const modulePath of allModulePaths) {
       const importedModule = require(modulePath) as KnowhowModule;
-      await importedModule.init({ config, cwd: process.cwd() });
+      await importedModule.init({ config, cwd: process.cwd(), context });
 
       for (const agent of importedModule.agents) {
         agentService.registerAgent(agent);

package/src/services/modules/types.ts

@@ -4,6 +4,7 @@ import { Tool } from "../../clients/types";
 import { Config } from "../../types";
 import { GenericClient } from "../../clients/types";
 import { AgentService } from "../AgentService";
+import { EmbeddingsService } from "../EmbeddingsService";
 import { PluginService } from "../../plugins/plugins";
 import { AIClient } from "../../clients";
 import { ToolsService } from "../Tools";
@@ -42,10 +43,12 @@ export type ModuleClient = {
 export type InitParams = {
   config: Config;
   cwd: string;
+  context?: ModuleContext;
 };
 
 export interface ModuleContext {
   Agents: AgentService;
+  Embeddings: EmbeddingsService;
   Plugins: PluginService;
   Clients: AIClient;
   Tools: ToolsService;

package/tests/unit/modules/moduleLoading.test.ts

@@ -47,6 +47,11 @@ function makeContext(overrides?: Partial<ModuleContext>): ModuleContext {
       addTool: jest.fn(),
       setFunction: jest.fn(),
     } as any,
+    Embeddings: {
+      registerDownloader: jest.fn(),
+      hasDownloader: jest.fn(),
+      download: jest.fn(),
+    } as any,
     ...overrides,
   };
 }

package/ts_build/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@tyvm/knowhow",
-    "version": "0.0.91",
+    "version": "0.0.93",
     "description": "ai cli with plugins and agents",
     "main": "ts_build/src/index.js",
     "bin": {
@@ -13,7 +13,8 @@
         "start": "npm run compile && node --no-node-snapshot ts_build/src/server/index.js",
         "dataset:diffs:generate": "ts-node src/dataset/diffs/generate.ts",
         "dataset:diffs:jsonl": "ts-node src/dataset/diffs/jsonl.ts",
-        "prepublishOnly": "npm run compile",
+        "prepublishOnly": "npm run compile && bash scripts/check-isolated-deps.sh",
+        "check:isolated": "bash scripts/check-isolated-deps.sh",
         "lint": "tslint ./src/**/*.ts",
         "lint:deps": "depcheck --config=.depcheckrc",
         "lint:all": "npm run lint && npm run lint:deps"
@@ -23,6 +24,7 @@
     "license": "MIT",
     "devDependencies": {
         "@babel/preset-typescript": "^7.23.3",
+        "typescript": "^5.0.0",
         "@types/diff": "^5.2.1",
         "@types/express": "^4.17.13",
         "@types/jest": "^29.5.13",
@@ -39,7 +41,6 @@
     },
     "dependencies": {
         "@anthropic-ai/sdk": "^0.39.0",
-        "@aws-sdk/client-s3": "^3.588.0",
         "@google/genai": "^0.14.1",
         "@inquirer/editor": "^4.2.18",
         "@modelcontextprotocol/sdk": "^1.13.3",
@@ -58,9 +59,8 @@
         "node-jq": "^6.0.1",
         "openai": "4.89.1",
         "pdf-parse": "^1.1.1",
-        "typescript": "^4.6.3",
         "ws": "^8.18.1",
-        "zod": "^3.24.2"
+        "zod": "^3.25.0"
     },
     "directories": {
         "test": "tests"
@@ -73,5 +73,8 @@
     "bugs": {
         "url": "https://github.com/tyvm-ai/knowhow/issues"
     },
-    "homepage": "https://github.com/tyvm-ai/knowhow#readme"
+    "homepage": "https://github.com/tyvm-ai/knowhow#readme",
+    "optionalDependencies": {
+        "esbuild-register": "^3.0.0"
+    }
 }