@tyvm/knowhow 0.0.147 → 0.0.148

package/src/commands/processes.ts

@@ -0,0 +1,138 @@
+import { Command } from "commander";
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getProcessesDir, listManagedProcesses, ManagedProcess,
+  ManagedProcessInfo, processDirectory,
+} from "../processes/ProcessManager";
+import { runManagedProcessShim } from "../processes/managedProcessShim";
+
+const terminal = new Set(["exited", "failed", "stopped"]);
+function resolveProcess(value: string): ManagedProcess {
+  const root = getProcessesDir();
+  const matches = listManagedProcesses(root).filter((p) => p.id === value || p.id.includes(value));
+  if (!matches.length) throw new Error(`Managed process not found: ${value}`);
+  const exact = matches.find((p) => p.id === value);
+  if (!exact && matches.length > 1) throw new Error(`Ambiguous process id '${value}': ${matches.map((p) => p.id).join(", ")}`);
+  const item = exact || matches[0];
+  return new ManagedProcess(item.id, item.directory);
+}
+function commandOptions(options: any, command?: Command): any {
+  const fromOptions = typeof options?.optsWithGlobals === "function" ? options.optsWithGlobals() : options || {};
+  const fromCommand = typeof command?.optsWithGlobals === "function" ? command.optsWithGlobals() : {};
+  return { ...fromOptions, ...fromCommand };
+}
+function filtered(options: any): ManagedProcessInfo[] {
+  return listManagedProcesses().filter((item) => {
+    if (!options.all && terminal.has(item.status.state)) return false;
+    if (options.parent && item.status.parentProcessId !== options.parent) return false;
+    if (options.background !== undefined && item.status.background !== options.background) return false;
+    return true;
+  });
+}
+function printList(options: any): void {
+  const rows = filtered(options).map(({ id, status }) => ({
+    id, state: status.state, pid: status.pid || "-", background: status.background ? "yes" : "no",
+    parent: status.parentProcessId || "-", command: [status.command, ...status.args].join(" "),
+  }));
+  if (options.json) console.log(JSON.stringify(rows, null, 2));
+  else if (rows.length) console.table(rows);
+  else console.log("No managed processes.");
+}
+function addFilters(command: Command): Command {
+  return command.option("-a, --all", "include completed processes")
+    .option("--parent <id>", "filter by parent process/task id")
+    .option("--background", "show only background processes")
+    .option("--json", "emit JSON");
+}
+function tailText(file: string, lines: number): string {
+  if (!fs.existsSync(file)) return "";
+  return fs.readFileSync(file, "utf8").split("\n").slice(-lines - 1).join("\n");
+}
+async function followFiles(files: string[], fromEnd = true): Promise<void> {
+  const offsets = new Map<string, number>();
+  for (const file of files) offsets.set(file, fromEnd && fs.existsSync(file) ? fs.statSync(file).size : 0);
+  await new Promise<void>((resolve) => {
+    const poll = setInterval(() => {
+      for (const file of files) {
+        if (!fs.existsSync(file)) continue;
+        const size = fs.statSync(file).size; const offset = offsets.get(file) || 0;
+        if (size < offset) offsets.set(file, 0);
+        if (size > (offsets.get(file) || 0)) {
+          const start = offsets.get(file) || 0;
+          const fd = fs.openSync(file, "r"); const data = Buffer.alloc(size - start);
+          fs.readSync(fd, data, 0, data.length, start); fs.closeSync(fd);
+          process.stdout.write(data); offsets.set(file, size);
+        }
+      }
+    }, 150);
+    const done = () => { clearInterval(poll); resolve(); };
+    process.once("SIGINT", done); process.once("SIGTERM", done);
+  });
+}
+
+export function addProcessesCommand(program: Command): void {
+  const processes = addFilters(program.command("processes").description("inspect and control managed processes"));
+  processes.action((rawOptions, command) => printList(commandOptions(rawOptions, command)));
+  addFilters(processes.command("list").description("list managed processes"))
+    .action((rawOptions, command) => printList(commandOptions(rawOptions, command)));
+
+  processes.command("run").description("internal managed process shim").requiredOption("--config <path>")
+    .action(async ({ config }) => runManagedProcessShim(path.resolve(config)));
+
+  processes.command("logs <id>").alias("tail").option("-n, --lines <number>", "lines to show", "100")
+    .option("-f, --follow", "follow output").option("--stderr", "show stderr instead of stdout")
+    .option("--both", "show stdout and stderr").action(async (id, rawOptions, command) => {
+      const options = commandOptions(rawOptions, command);
+      const managed = resolveProcess(id);
+      const files = options.both ? [managed.stdoutPath, managed.stderrPath] : [options.stderr ? managed.stderrPath : managed.stdoutPath];
+      for (const file of files) process.stdout.write(tailText(file, Math.max(0, Number(options.lines) || 100)));
+      if (options.follow) await followFiles(files);
+    });
+
+  processes.command("send <id> [input...]").option("-n, --no-newline", "do not append newline")
+    .action(async (id, input: string[], rawOptions, command) => {
+      const options = commandOptions(rawOptions, command);
+      const managed = resolveProcess(id);
+      await managed.write((input || []).join(" ") + (options.newline ? "\n" : ""));
+    });
+
+  processes.command("signal <id> [signal]").action((id, signal = "SIGTERM") => resolveProcess(id).signal(signal.toUpperCase() as NodeJS.Signals));
+  processes.command("stop <id>").action((id) => resolveProcess(id).signal("SIGTERM"));
+  processes.command("kill <id>").action((id) => resolveProcess(id).signal("SIGKILL"));
+
+  processes.command("attach <id>").description("attach terminal (Ctrl-] to detach)").action(async (id) => {
+    const managed = resolveProcess(id); let detached = false;
+    const raw = !!process.stdin.isTTY; if (raw) process.stdin.setRawMode(true);
+    process.stdin.resume();
+    const onData = async (data: Buffer) => {
+      if (data.includes(0x1d)) { detached = true; return; }
+      try { await managed.write(data.toString()); } catch (error) { console.error(String(error)); detached = true; }
+    };
+    process.stdin.on("data", onData);
+    const offsets = [managed.stdoutPath, managed.stderrPath].map((f) => fs.existsSync(f) ? fs.statSync(f).size : 0);
+    await new Promise<void>((resolve) => {
+      const timer = setInterval(() => {
+        [managed.stdoutPath, managed.stderrPath].forEach((file, i) => {
+          if (!fs.existsSync(file)) return; const size = fs.statSync(file).size;
+          if (size > offsets[i]) { const fd = fs.openSync(file, "r"); const b = Buffer.alloc(size - offsets[i]); fs.readSync(fd, b, 0, b.length, offsets[i]); fs.closeSync(fd); process.stdout.write(b); offsets[i] = size; }
+        });
+        if (detached || terminal.has(managed.status.state)) { clearInterval(timer); resolve(); }
+      }, 100);
+    });
+    process.stdin.off("data", onData); process.stdin.pause(); if (raw) process.stdin.setRawMode(false);
+  });
+
+  processes.command("tree").option("-a, --all", "include completed processes").action((rawOptions, command) => {
+    const options = commandOptions(rawOptions, command);
+    const items = listManagedProcesses().filter((p) => options.all || !terminal.has(p.status.state));
+    const ids = new Set(items.map((p) => p.id));
+    const children = new Map<string | null, ManagedProcessInfo[]>();
+    for (const item of items) { const parent = item.status.parentProcessId && ids.has(item.status.parentProcessId) ? item.status.parentProcessId : null; children.set(parent, [...(children.get(parent) || []), item]); }
+    const render = (parent: string | null, prefix: string) => (children.get(parent) || []).forEach((item, index, array) => {
+      const last = index === array.length - 1; console.log(`${prefix}${last ? "└─" : "├─"}${item.id} [${item.status.state}] ${item.status.command}`);
+      render(item.id, prefix + (last ? "  " : "│ "));
+    });
+    render(null, "");
+  });
+}

package/src/commands/services.ts

@@ -3,7 +3,8 @@ import * as allTools from "../agents/tools";
 import { LazyToolsService, services, MinimalToolsService, TracingService } from "../services";
 import { agents } from "../agents";
 import { ModulesService } from "../services/modules";
-import { getConfig } from "../config";
+import { getConfig, getConfigSync } from "../config";
+import { authenticateWithKey } from "../auth/keyAuth";
 
 /**
  * Shared service setup used by commands that need full services (chat, agent, worker, etc.)
@@ -20,6 +21,7 @@ export async function setupServices() {
     MediaProcessor,
     Behaviors,
     RuntimeReload,
+    Extensions,
   } = services();
 
   await Plugins.refreshConfiguredState();
@@ -76,6 +78,25 @@ export async function setupServices() {
       `⚠ Some MCP servers failed to connect (continuing without them): ${msg}`
     );
   }
+  // Attempt silent JWT refresh via SSH identity before registering models.
+  // This handles the case where the JWT has expired but the user has a valid
+  // SSH identity registered — they shouldn't need to run `knowhow login` again
+  // unless they want to switch organizations.
+  try {
+    const startupConfig = getConfigSync();
+    if (startupConfig.orgId && !process.env.KNOWHOW_JWT) {
+      await authenticateWithKey(
+        startupConfig.orgId,
+        process.env.KNOWHOW_API_URL || "https://api.knowhow.tyvm.ai",
+        startupConfig.cliIdentityPath
+      );
+    }
+  } catch (_err) {
+    // Non-fatal: if SSH refresh fails (no key, revoked, network issue), we
+    // continue with the existing JWT (or no JWT). The user will see model
+    // warnings if no valid JWT is available.
+  }
+
   console.log("Connecting to clients...");
   await Clients.registerConfiguredModels();
   console.log("✓ Services are set up and ready to go!");
@@ -92,6 +113,7 @@ export async function setupServices() {
     Behaviors,
     Events,
     Tracing: TracingService,
+    Extensions,
   };
 
   // Call destroy() on all modules when the process is shutting down so they

package/src/index.ts

@@ -65,6 +65,7 @@ export * as embeddings from "./embeddings";
 export * as types from "./types";
 export * as processors from "./processors";
 export * as ai from "./ai";
+export * from "./processes/ProcessManager";
 
 // Export module system types for external modules
 export * from "./services/modules/types";

package/src/processes/ProcessManager.ts

@@ -0,0 +1,95 @@
+import { spawn } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { randomBytes } from "crypto";
+
+export type ManagedProcessState = "starting" | "running" | "exited" | "failed" | "stopped";
+export interface ManagedProcessStatus {
+  id: string; pid: number | null; shimPid: number | null; state: ManagedProcessState;
+  command: string; args: string[]; cwd: string; parentProcessId: string | null;
+  parentPid: number | null; background: boolean; startedAt: string; endedAt: string | null;
+  exitCode: number | null; signal: string | null; error?: string;
+}
+export interface SpawnManagedOptions {
+  id?: string; cwd?: string; env?: NodeJS.ProcessEnv; background?: boolean;
+  parentProcessId?: string; parentPid?: number; shell?: boolean; processesDir?: string;
+}
+export interface ManagedProcessInfo { id: string; directory: string; status: ManagedProcessStatus; }
+
+export function getProcessesDir(cwd = process.cwd()): string {
+  return process.env.KNOWHOW_PROCESSES_DIR || path.join(cwd, ".knowhow", "processes");
+}
+export function processDirectory(id: string, processesDir = getProcessesDir()): string {
+  if (!/^[a-zA-Z0-9._-]+$/.test(id)) throw new Error(`Invalid process id: ${id}`);
+  return path.join(processesDir, id);
+}
+export function readManagedStatus(id: string, processesDir = getProcessesDir()): ManagedProcessStatus {
+  return JSON.parse(fs.readFileSync(path.join(processDirectory(id, processesDir), "status.json"), "utf8"));
+}
+export function listManagedProcesses(processesDir = getProcessesDir()): ManagedProcessInfo[] {
+  if (!fs.existsSync(processesDir)) return [];
+  return fs.readdirSync(processesDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(processesDir, entry.name, "status.json")))
+    .flatMap((entry) => { try { return [{ id: entry.name, directory: path.join(processesDir, entry.name), status: readManagedStatus(entry.name, processesDir) }]; } catch { return []; } })
+    .sort((a, b) => b.status.startedAt.localeCompare(a.status.startedAt));
+}
+function makeId(command: string): string {
+  const name = path.basename(command).replace(/[^a-zA-Z0-9._-]/g, "-").slice(0, 28) || "process";
+  return `${name}-${Date.now()}-${randomBytes(3).toString("hex")}`;
+}
+function waitForFile(file: string, timeoutMs: number): Promise<void> {
+  const started = Date.now();
+  return new Promise((resolve, reject) => { const check = () => {
+    if (fs.existsSync(file)) return resolve();
+    if (Date.now() - started >= timeoutMs) return reject(new Error(`Managed process did not initialize: ${file}`));
+    setTimeout(check, 20);
+  }; check(); });
+}
+export class ManagedProcess {
+  constructor(public readonly id: string, public readonly directory: string) {}
+  get status(): ManagedProcessStatus { return readManagedStatus(this.id, path.dirname(this.directory)); }
+  get stdoutPath(): string { return path.join(this.directory, "stdout"); }
+  get stderrPath(): string { return path.join(this.directory, "stderr"); }
+  get inputLogPath(): string { return path.join(this.directory, "input.log"); }
+  get stdinPath(): string { return path.join(this.directory, "stdin"); }
+  async write(input: string): Promise<void> {
+    if (process.platform === "win32") {
+      await fs.promises.appendFile(this.stdinPath, input);
+      return;
+    }
+    // A non-blocking open fails promptly with ENXIO if the shim is gone instead
+    // of leaving callers hung forever waiting for a FIFO reader.
+    const handle = await fs.promises.open(this.stdinPath, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK);
+    try { await handle.writeFile(input); } finally { await handle.close(); }
+  }
+  signal(signal: NodeJS.Signals = "SIGTERM"): void {
+    const status = this.status;
+    if (!status.pid) throw new Error(`Process ${this.id} has no active pid`);
+    try { process.kill(-status.pid, signal); } catch { process.kill(status.pid, signal); }
+  }
+  async wait(timeoutMs?: number): Promise<ManagedProcessStatus> {
+    const started = Date.now();
+    while (true) {
+      const status = this.status;
+      if (!["starting", "running"].includes(status.state)) return status;
+      if (timeoutMs !== undefined && Date.now() - started >= timeoutMs) throw new Error(`Timed out waiting for managed process ${this.id} after ${timeoutMs}ms`);
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+  }
+}
+export async function spawnManaged(command: string, args: string[] = [], options: SpawnManagedOptions = {}): Promise<ManagedProcess> {
+  const cwd = path.resolve(options.cwd || process.cwd());
+  const processesDir = options.processesDir || getProcessesDir(cwd);
+  const id = options.id || makeId(command);
+  const directory = processDirectory(id, processesDir);
+  fs.mkdirSync(processesDir, { recursive: true });
+  fs.mkdirSync(directory);
+  const configPath = path.join(directory, "launch.json");
+  fs.writeFileSync(configPath, JSON.stringify({ id, command, args, cwd, env: options.env || {}, background: options.background === true, parentProcessId: options.parentProcessId || null, parentPid: options.parentPid ?? process.pid, shell: options.shell === true, processesDir }, null, 2));
+  const cliPath = path.resolve(__dirname, "..", "cli.js");
+  const shim = spawn(process.execPath, [cliPath, "processes", "run", "--config", configPath], { cwd, detached: true, stdio: "ignore", env: process.env });
+  shim.unref();
+  try { await waitForFile(path.join(directory, "status.json"), 5000); }
+  catch (error) { try { fs.rmSync(directory, { recursive: true, force: true }); } catch {} throw error; }
+  return new ManagedProcess(id, directory);
+}

package/src/processes/managedProcessShim.ts

@@ -0,0 +1,115 @@
+import { spawn, spawnSync, ChildProcess } from "child_process";
+import * as fs from "fs";
+import * as path from "path";
+import { ManagedProcessStatus } from "./ProcessManager";
+
+interface LaunchConfig {
+  id: string; command: string; args: string[]; cwd: string; env: NodeJS.ProcessEnv;
+  background: boolean; parentProcessId: string | null; parentPid: number | null;
+  shell: boolean; processesDir: string;
+}
+
+function atomicJson(file: string, value: unknown): void {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2));
+  fs.renameSync(tmp, file);
+}
+function alive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; } catch (error: any) { return error?.code === "EPERM"; }
+}
+function terminateGroup(child: ChildProcess, signal: NodeJS.Signals): void {
+  if (!child.pid) return;
+  try { process.kill(-child.pid, signal); } catch { try { child.kill(signal); } catch {} }
+}
+
+export async function runManagedProcessShim(configPath: string): Promise<void> {
+  const config: LaunchConfig = JSON.parse(fs.readFileSync(configPath, "utf8"));
+  const dir = path.dirname(configPath);
+  const startedAt = new Date().toISOString();
+  const statusPath = path.join(dir, "status.json");
+  const stdoutPath = path.join(dir, "stdout");
+  const stderrPath = path.join(dir, "stderr");
+  const inputLogPath = path.join(dir, "input.log");
+  const fifoPath = path.join(dir, "stdin");
+  fs.closeSync(fs.openSync(stdoutPath, "a"));
+  fs.closeSync(fs.openSync(stderrPath, "a"));
+  fs.closeSync(fs.openSync(inputLogPath, "a"));
+
+  if (process.platform !== "win32") {
+    const result = spawnSync("mkfifo", [fifoPath]);
+    if (result.status !== 0 && !fs.existsSync(fifoPath)) throw new Error(`Unable to create stdin FIFO: ${result.stderr?.toString()}`);
+  } else {
+    // Windows has no POSIX FIFO. Keep the same path as an append-only inbox fallback.
+    fs.closeSync(fs.openSync(fifoPath, "a"));
+  }
+
+  let status: ManagedProcessStatus = {
+    id: config.id, pid: null, shimPid: process.pid, state: "starting", command: config.command,
+    args: config.args, cwd: config.cwd, parentProcessId: config.parentProcessId,
+    parentPid: config.parentPid, background: config.background, startedAt, endedAt: null,
+    exitCode: null, signal: null,
+  };
+  const writeStatus = () => atomicJson(statusPath, status);
+  atomicJson(path.join(dir, "metadata.json"), {
+    id: config.id, command: config.command, args: config.args, cwd: config.cwd,
+    parentProcessId: config.parentProcessId, parentPid: config.parentPid,
+    background: config.background, createdAt: startedAt, shimPid: process.pid,
+  });
+  fs.writeFileSync(path.join(dir, "pid"), "");
+  writeStatus();
+
+  const stdoutFd = fs.openSync(stdoutPath, "a");
+  const stderrFd = fs.openSync(stderrPath, "a");
+  const child = spawn(config.command, config.args, {
+    cwd: config.cwd, shell: config.shell, detached: process.platform !== "win32",
+    stdio: ["pipe", stdoutFd, stderrFd],
+    env: { ...process.env, ...config.env, KNOWHOW_MANAGED_PROCESS_ID: config.id, KNOWHOW_MANAGED_PROCESS_DIR: dir },
+  });
+  fs.closeSync(stdoutFd); fs.closeSync(stderrFd);
+  status = { ...status, pid: child.pid || null, state: "running" };
+  fs.writeFileSync(path.join(dir, "pid"), child.pid ? `${child.pid}\n` : "");
+  writeStatus();
+
+  let fifoFd: number | undefined;
+  let fifoStream: fs.ReadStream | undefined;
+  if (process.platform !== "win32") {
+    // O_RDWR prevents transient writers disconnecting from delivering EOF to the shim.
+    fifoFd = fs.openSync(fifoPath, fs.constants.O_RDWR);
+    fifoStream = fs.createReadStream("", { fd: fifoFd, autoClose: false });
+    fifoStream.on("data", (chunk) => {
+      fs.appendFileSync(inputLogPath, chunk);
+      if (child.stdin?.writable) child.stdin.write(chunk);
+    });
+  }
+
+  let stoppingForParent = false;
+  const parentTimer = !config.background && config.parentPid
+    ? setInterval(() => {
+        if (!alive(config.parentPid!)) {
+          stoppingForParent = true;
+          terminateGroup(child, "SIGTERM");
+          setTimeout(() => { if (alive(child.pid || -1)) terminateGroup(child, "SIGKILL"); }, 3000).unref();
+        }
+      }, 500)
+    : undefined;
+  parentTimer?.unref();
+
+  const forward = (signal: NodeJS.Signals) => terminateGroup(child, signal);
+  process.once("SIGINT", () => forward("SIGINT"));
+  process.once("SIGTERM", () => forward("SIGTERM"));
+  process.once("SIGHUP", () => forward("SIGHUP"));
+
+  await new Promise<void>((resolve) => {
+    child.once("error", (error) => {
+      status = { ...status, state: "failed", error: error.message, endedAt: new Date().toISOString() };
+      writeStatus(); resolve();
+    });
+    child.once("exit", (code, signal) => {
+      status = { ...status, state: stoppingForParent || signal ? "stopped" : code === 0 ? "exited" : "failed", endedAt: new Date().toISOString(), exitCode: code, signal };
+      writeStatus(); resolve();
+    });
+  });
+  if (parentTimer) clearInterval(parentTimer);
+  fifoStream?.destroy();
+  if (fifoFd !== undefined) try { fs.closeSync(fifoFd); } catch {}
+}

package/src/services/AgentSyncFs.ts

@@ -124,7 +124,18 @@ export class AgentSyncFs {
 
     try {
       const metadataPath = path.join(this.taskPath, "metadata.json");
-      await fs.writeFile(metadataPath, JSON.stringify(data, null, 2), "utf8");
+      // Thread/status updates are partial snapshots. Merge them so stable
+      // orchestration identity written by createTask (taskId, pid and parent)
+      // is never discarded by a later update.
+      let existing: Record<string, unknown> = {};
+      try {
+        existing = JSON.parse(await fs.readFile(metadataPath, "utf8"));
+      } catch { /* first write or an interrupted legacy write */ }
+      await fs.writeFile(
+        metadataPath,
+        JSON.stringify({ ...existing, ...data }, null, 2),
+        "utf8"
+      );
     } catch (error) {
       console.error(`❌ Failed to write metadata:`, error);
     }

package/src/services/ExtensionsService.ts

@@ -0,0 +1,25 @@
+export interface ModuleExtension {
+  type: string;
+  [key: string]: unknown;
+}
+
+interface RegisteredExtension extends ModuleExtension {
+  owner: string;
+}
+
+/** Process-local registry for optional, consumer-defined module capabilities. */
+export class ExtensionsService {
+  private extensions: RegisteredExtension[] = [];
+
+  register(owner: string, extension: ModuleExtension): void {
+    this.extensions.push({ ...extension, owner });
+  }
+
+  list<T extends ModuleExtension>(type: T["type"]): readonly T[] {
+    return this.extensions.filter((item) => item.type === type) as unknown as readonly T[];
+  }
+
+  removeOwner(owner: string): void {
+    this.extensions = this.extensions.filter((item) => item.owner !== owner);
+  }
+}

package/src/services/LazyToolsService.ts

@@ -82,6 +82,15 @@ export class LazyToolsService extends ToolsService {
     return this.tools; // Returns filtered subset
   }
 
+  // Definitions remain resolvable even when omitted from the model prompt.
+  getTool(name: string): Tool {
+    return this.allTools.find(
+      (tool) =>
+        name &&
+        (tool.function.name === name || tool.function.name.endsWith(name))
+    );
+  }
+
   /** Rebuild the lazy catalog while preserving enable/disable preferences. */
   resetTools(): void {
     this.allTools = [];
@@ -155,32 +164,18 @@ export class LazyToolsService extends ToolsService {
     };
   }
 
-  // Override callTool to auto-enable tools that are in allTools but not yet enabled
+  // Prompt visibility is not authorization. Registered functions remain
+  // callable without changing which definitions are sent to the model.
   async callTool(
     toolCall: ToolCall,
     enabledTools?: string[],
     callContext?: ToolCallContext
   ) {
-    const functionName = toolCall.function.name;
-
-    // If the tool isn't currently visible but exists in allTools, auto-enable it.
-    // This handles the case where the agent explicitly calls a tool without first
-    // enabling it via listAvailableTools/enableTools.
-    const isCurrentlyEnabled = this.tools.some(
-      (t) => t.function.name === functionName
+    return super.callTool(
+      toolCall,
+      enabledTools ?? this.getFunctionNames(),
+      callContext
     );
-    const existsInAll = this.allTools.some(
-      (t) => t.function.name === functionName
-    );
-
-    if (!isCurrentlyEnabled && existsInAll) {
-      // Auto-enable by adding the tool name as an exact pattern
-      this.enableTools([functionName]);
-    }
-
-    // Always use the current enabled tool names after any auto-enable above,
-    // so the base class check sees the freshly-enabled tool in the allowed list.
-    return super.callTool(toolCall, this.getToolNames(), callContext);
   }
 
   // Internal: Update visible tools based on patterns

package/src/services/Tools.ts

@@ -135,6 +135,16 @@ export class ToolsService {
     return this.tools.map((tool) => tool.function.name);
   }
 
+  /**
+   * Return every registered function implementation. Unlike getToolNames(),
+   * this is not a prompt-visibility list; lazy tool services may intentionally
+   * hide definitions from the model while keeping their functions callable by
+   * trusted programmatic consumers such as the script runtime.
+   */
+  getFunctionNames(): string[] {
+    return Object.keys(this.functions).filter((name) => typeof this.functions[name] === "function");
+  }
+
   getTool(name: string): Tool {
     return this.tools.find(
       (tool) =>

package/src/services/index.ts

@@ -16,6 +16,7 @@ import { TaskRegistry } from "./TaskRegistry";
 import { MediaProcessorService } from "./MediaProcessorService";
 import { BehaviorsService } from "./BehaviorsService";
 import { RuntimeReloadService } from "./RuntimeReloadService";
+import { ExtensionsService } from "./ExtensionsService";
 
 import { ConversionService } from "./conversion/ConversionService";
 import { TracingService } from "./TracingService";
@@ -45,6 +46,7 @@ export { TracingService } from "./TracingService";
 export type { TracerImpl, SpanHandle } from "./TracingService";
 export * from "./conversion";
 export * from "./RuntimeReloadService";
+export * from "./ExtensionsService";
 export { BehaviorsService } from "./BehaviorsService";
 
 let Singletons = {} as {
@@ -64,6 +66,7 @@ let Singletons = {} as {
   Conversion: ConversionService;
   Behaviors: BehaviorsService;
   RuntimeReload: RuntimeReloadService;
+  Extensions: ExtensionsService;
 };
 
 export const services = (): typeof Singletons => {
@@ -98,6 +101,7 @@ export const services = (): typeof Singletons => {
       knowhowApiClient: new KnowhowSimpleClient(),
       Behaviors,
       RuntimeReload: new RuntimeReloadService(),
+      Extensions: new ExtensionsService(),
     };
 
     Singletons.Tools.setContext({

package/src/services/modules/index.ts

@@ -207,6 +207,11 @@ export class ModulesService {
       }
       this._loadedModules.push({ modulePath, resolvedPath, module: importedModule, params: initParams });
 
+      context.Extensions?.removeOwner(modulePath);
+      for (const extension of importedModule.extensions ?? []) {
+        context.Extensions?.register(modulePath, extension);
+      }
+
       // Only register tools/agents/plugins/clients if the relevant services
       // are available in context (they may not be during early CLI command registration)
       if (context.Agents) {
@@ -253,6 +258,7 @@ export class ModulesService {
     // Clear first so repeated shutdown/reload attempts cannot destroy twice.
     this._loadedModules = [];
     for (const { modulePath, resolvedPath, module: mod, params } of toDestroy) {
+      params.context?.Extensions?.removeOwner(modulePath);
       if (typeof mod.destroy === "function") {
         try {
           await mod.destroy(params);

package/src/services/modules/types.ts

@@ -15,6 +15,7 @@ import { EventService } from "../EventService";
 import { ConversionService } from "../conversion/ConversionService";
 import { BehaviorsService } from "../BehaviorsService";
 import { ComputerUseService } from "./computerUse";
+import { ExtensionsService, ModuleExtension } from "../ExtensionsService";
 
 import { TracingService as TracingServiceType } from "../TracingService";
 /*
@@ -66,6 +67,7 @@ export interface ModuleContext {
   Program?: Command;
   Behaviors?: BehaviorsService;
   ComputerUse?: ComputerUseService;
+  Extensions?: ExtensionsService;
   [key: string]: any;
   Tracing?: typeof TracingServiceType;
 }
@@ -98,6 +100,8 @@ export interface KnowhowModule {
    */
   destroy?: (params: InitParams) => Promise<void>;
   commands: ModuleChatCommand[];
+  /** Optional capabilities consumed by core or third-party services. */
+  extensions?: ModuleExtension[];
   tools: ModuleTool[];
   agents: ModuleAgent[];
   plugins: ModulePlugin[];