@tyvm/knowhow 0.0.147 → 0.0.149

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,127 @@
+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 fifoStream: fs.ReadStream | undefined;
+  if (process.platform !== "win32") {
+    // O_RDWR prevents transient writers disconnecting from delivering EOF to the shim.
+    const fifoFd = fs.openSync(fifoPath, fs.constants.O_RDWR);
+    fifoStream = fs.createReadStream("", { fd: fifoFd, autoClose: true });
+    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);
+  if (fifoStream && !fifoStream.closed) {
+    // A FIFO read cannot always be cancelled by closing its descriptor (notably
+    // on macOS). Wake the pending read before asking ReadStream to close it;
+    // otherwise each completed command can leave its shim wedged in close(2).
+    const wakeFd = fs.openSync(fifoPath, fs.constants.O_WRONLY | fs.constants.O_NONBLOCK);
+    try {
+      fs.writeSync(wakeFd, Buffer.from([0]));
+    } finally {
+      fs.closeSync(wakeFd);
+    }
+    await new Promise<void>((resolve) => {
+      fifoStream!.once("close", resolve);
+      fifoStream!.destroy();
+    });
+  }
+}

package/src/processors/Base64ImageDetector.ts

@@ -251,6 +251,24 @@ export class Base64ImageProcessor {
     }
   }
 
+  private isUsableImageUrl(url: unknown): url is string {
+    if (typeof url !== "string") return false;
+
+    // Data URLs are only usable when they contain an image format this processor
+    // recognizes. In particular, reject TokenCompressor placeholders that happen
+    // to be located inside an otherwise valid-looking image_url content part.
+    if (url.startsWith("data:")) {
+      return this.isBase64Image(url).isImage;
+    }
+
+    try {
+      const parsed = new URL(url);
+      return parsed.protocol === "http:" || parsed.protocol === "https:";
+    } catch {
+      return false;
+    }
+  }
+
   private processToolMessageContent(message: Message): void {
     // Tool messages have string content that might be a JSON string containing image data
     if (typeof message.content === "string" && message.content.trim()) {
@@ -267,13 +285,19 @@ export class Base64ImageProcessor {
         //  model to see a raw base64 JSON string instead of an actual image.)
         const candidates = Array.isArray(parsed) ? parsed : [parsed];
         const isImagePart = (p: any) =>
-          p && p.type === "image_url" && p.image_url?.url;
+          p &&
+          p.type === "image_url" &&
+          this.isUsableImageUrl(p.image_url?.url);
         const isTextPart = (p: any) =>
           p && p.type === "text" && typeof p.text === "string";
+        const hasInvalidImagePart = candidates.some(
+          (p: any) => p?.type === "image_url" && !isImagePart(p)
+        );
 
-        // Only rewrite the content if it actually contains at least one image
-        // part; otherwise leave the original tool text untouched.
-        if (candidates.some(isImagePart)) {
+        // Only rewrite content containing valid provider-ready images. If an
+        // image URL was compressed or is malformed, preserve the JSON as text so
+        // the agent can inspect/expand it instead of failing the next API call.
+        if (!hasInvalidImagePart && candidates.some(isImagePart)) {
           message.content = candidates.filter(
             (p) => isImagePart(p) || isTextPart(p)
           );

package/src/processors/JsonCompressor.ts

@@ -398,6 +398,20 @@ export class JsonCompressor {
     }
 
 
+    // Image content parts must remain atomic. Compressing a data URL independently
+    // leaves a valid-looking image_url object whose URL is only a placeholder.
+    // The containing response can still be compressed, but expanding it must
+    // restore an image part with its usable URL intact.
+    if (
+      obj &&
+      typeof obj === "object" &&
+      !Array.isArray(obj) &&
+      obj.type === "image_url" &&
+      typeof obj.image_url?.url === "string"
+    ) {
+      return obj;
+    }
+
     // Handle objects - try low-signal detection first, then process properties (depth-first)
     if (obj && typeof obj === "object") {
       // Check if this exact object (by original content) is a duplicate

package/src/processors/TokenCompressor.ts

@@ -45,6 +45,22 @@ export class TokenCompressor implements JsonCompressorStorage {
   // JSON compression handler
   private jsonCompressor: JsonCompressor;
 
+
+  /**
+   * Tool names whose responses should never be compressed.
+   * These are compression/retrieval tools themselves - compressing their output
+   * would prevent the agent from seeing the uncompressed data it just retrieved.
+   */
+  static DO_NOT_COMPRESS: ReadonlySet<string> = new Set([
+    "expandTokens",
+    "grepToolResponse",
+    "jqToolResponse",
+    "tailToolResponse",
+    "listStoredToolResponses",
+    "loadImageAsBase64" // need a proper way to do this
+  ]);
+
+
   constructor(toolsService?: ToolsService) {
     this.jsonCompressor = new JsonCompressor(
       this,
@@ -290,19 +306,6 @@ export class TokenCompressor implements JsonCompressorStorage {
     }
   }
 
-  /**
-   * Tool names whose responses should never be compressed.
-   * These are compression/retrieval tools themselves - compressing their output
-   * would prevent the agent from seeing the uncompressed data it just retrieved.
-   */
-  static readonly COMPRESSION_TOOL_NAMES: ReadonlySet<string> = new Set([
-    "expandTokens",
-    "grepToolResponse",
-    "jqToolResponse",
-    "tailToolResponse",
-    "listStoredToolResponses",
-  ]);
-
   createProcessor(
     filterFn?: (msg: Message) => boolean
   ): MessageProcessorFunction {
@@ -344,7 +347,7 @@ export class TokenCompressor implements JsonCompressorStorage {
         if (
           message.role === "tool" &&
           message.name &&
-          TokenCompressor.COMPRESSION_TOOL_NAMES.has(message.name)
+          TokenCompressor.DO_NOT_COMPRESS.has(message.name)
         ) {
           continue;
         }

package/src/services/AgentService.ts

@@ -76,14 +76,14 @@ export class AgentService {
     return this.agentContext ?? { Tools: this.tools, Events: this.events };
   }
 
-  public getAgent(name: string): IAgent {
+  public getAgent<T extends IAgent = IAgent>(name: string): T {
     const agent = this.agents.get(name);
     if (!agent) {
       throw new Error(
         `Agent ${name} not found. Options are: ${this.listAgents()}`
       );
     }
-    return agent;
+    return agent as T;
   }
 
   public listAgents(): string[] {

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/computerUse.ts

@@ -26,13 +26,15 @@ export interface Region extends Point, Size {}
 export type MouseButton = "left" | "right" | "middle";
 
 export interface OverlayPrimitive {
-  kind: "rect" | "circle" | "line" | "point";
+  kind: "rect" | "circle" | "line" | "point" | "text";
   x: number;
   y: number;
   width?: number;
   height?: number;
   x2?: number;
   y2?: number;
+  text?: string;
+  fontSize?: number;
   color?: string;
   lineWidth?: number;
 }

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[];