@tyvm/knowhow 0.0.147 → 0.0.148

package/src/agents/tools/startAgentTask.ts

@@ -34,6 +34,20 @@ export interface StartAgentTaskParams {
   _ctx?: { caller?: any; taskId?: string; [key: string]: any };
 }
 
+export interface StartAgentTaskResult {
+  success: boolean;
+  status: "started" | "completed" | "failed";
+  taskId: string;
+  pid?: number;
+  syncFs: boolean;
+  syncReady: boolean;
+  agentDir?: string;
+  logPath: string;
+  parentTaskId?: string;
+  exitCode?: number | null;
+  error?: string;
+}
+
 const PROCESSES_DIR = path.join(process.cwd(), ".knowhow", "processes");
 const AGENTS_DIR = path.join(process.cwd(), ".knowhow", "processes", "agents");
 
@@ -100,7 +114,7 @@ function subagentCapabilitiesNote(): string {
  *   .knowhow/processes/agents/{taskId}/input.txt
  * The agent will pick up the new content and process it as a new message.
  */
-export async function startAgentTask(params: StartAgentTaskParams): Promise<string> {
+export async function startAgentTask(params: StartAgentTaskParams): Promise<StartAgentTaskResult> {
   const {
     messageId,
     prompt,
@@ -235,43 +249,54 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
   child.stdin!.write(promptWithCaps, "utf8");
   child.stdin!.end();
 
-  return new Promise<string>((resolve) => {
+  return new Promise<StartAgentTaskResult>((resolve) => {
     let settled = false;
-    const done = (msg: string) => {
+    let exited = false;
+    const done = (result: StartAgentTaskResult) => {
       if (settled) return;
       settled = true;
       try { fs.closeSync(fd); } catch {}
-      resolve(msg);
+      resolve(result);
     };
 
     child.once("error", (e) => {
-      done(`Failed to start agent: ${String(e)}\nLogs: ${logPath}`);
+      done({
+        success: false, status: "failed", taskId, pid, syncFs: useSyncFs,
+        syncReady: false, agentDir: useSyncFs ? agentTaskDir : undefined,
+        logPath, parentTaskId, error: String(e),
+      });
     });
 
-    const syncFsNote = useSyncFs
-      ? `\nTask ID: ${taskId}\nAgent dir: ${agentTaskDir}\n` +
-        `To send agent messages, write to: ${agentTaskDir}/input.txt\n` +
-        `To check status, read: ${agentTaskDir}/status.txt\n`
-      : "";
-
     child.once("exit", (code) => {
-      done(
-        `Agent finished with exit code ${code}.\nLogs: ${logPath}\n` +
-        syncFsNote
-      );
+      exited = true;
+      done({
+        success: code === 0, status: code === 0 ? "completed" : "failed",
+        taskId, pid, syncFs: useSyncFs,
+        syncReady: useSyncFs && fs.existsSync(path.join(agentTaskDir, "metadata.json")),
+        agentDir: useSyncFs ? agentTaskDir : undefined, logPath, parentTaskId,
+        exitCode: code, ...(code === 0 ? {} : { error: `Agent exited with code ${code}` }),
+      });
     });
 
     if (!waitForCompletion) {
-      // Give the agent 5 seconds to finish before detaching (fire-and-forget mode)
-      const detachTime = 5 * 1000;
-      setTimeout(() => {
-        try { child.unref(); } catch {}
-        done(
-          `Agent started (pid=${pid}), running in background.\n` +
-          `Logs: ${logPath}\n` +
-          syncFsNote
-        );
-      }, detachTime);
+      // A spawn is not the same as an initialized fs-sync agent. Poll briefly
+      // so callers can distinguish those states without parsing log prose.
+      const deadline = Date.now() + (useSyncFs ? 5000 : 100);
+      const acknowledge = () => {
+        if (settled || exited) return;
+        const syncReady = useSyncFs && fs.existsSync(path.join(agentTaskDir, "metadata.json"));
+        if (!useSyncFs || syncReady || Date.now() >= deadline) {
+          try { child.unref(); } catch {}
+          done({
+            success: true, status: "started", taskId, pid, syncFs: useSyncFs,
+            syncReady, agentDir: useSyncFs ? agentTaskDir : undefined,
+            logPath, parentTaskId,
+          });
+          return;
+        }
+        setTimeout(acknowledge, 100);
+      };
+      setTimeout(acknowledge, 50);
     }
   });
 }

package/src/ai.ts

@@ -65,13 +65,16 @@ export async function singlePrompt(
     // This ensures generate agent runs produce readable output and are observable
     // via `knowhow agents list/tail/status`, matching `knowhow agent --input` behaviour.
     const { startAgentTask } = await import("./agents/tools/startAgentTask");
-    return startAgentTask({
+    const result = await startAgentTask({
       agentName: agent,
       prompt: userPrompt,
       model: model || undefined,
       waitForCompletion: true,
       ...(agentOptions ?? {}),
     });
+    // singlePrompt is a text API; keep generation pipelines compatible while
+    // the tool itself exposes a structured orchestration result.
+    return JSON.stringify(result);
   }
 
   if (!model) {

package/src/chat/CliChatService.ts

@@ -20,6 +20,12 @@ import fs from "fs";
 import path from "path";
 import { services } from "../services";
 import { logger } from "../logger";
+import { ModuleExtension } from "../services/ExtensionsService";
+
+export interface ChatExtension extends ModuleExtension {
+  type: "chat";
+  commands: ChatCommand[];
+}
 
 export class CliChatService implements ChatService {
   private context: ChatContext;
@@ -59,6 +65,7 @@ export class CliChatService implements ChatService {
         }
       },
     });
+    this.refreshExtensions();
     this.loadInputHistory();
 
     // Set up callback to add entries to inputHistory immediately when user presses Enter
@@ -151,7 +158,12 @@ export class CliChatService implements ChatService {
   }
 
   registerCommand(command: ChatCommand): void {
-    this.commands.push(command);
+    const existing = this.commands.findIndex((item) => item.name === command.name);
+    if (existing >= 0) {
+      this.commands[existing] = command;
+    } else {
+      this.commands.push(command);
+    }
   }
 
   registerMode(mode: ChatMode): void {
@@ -163,9 +175,17 @@ export class CliChatService implements ChatService {
   }
 
   getCommands(): ChatCommand[] {
+    this.refreshExtensions();
     return this.commands;
   }
 
+  /** Re-read the registry so services created before module setup still work. */
+  refreshExtensions(): void {
+    for (const extension of services().Extensions.list<ChatExtension>("chat")) {
+      for (const command of extension.commands ?? []) this.registerCommand(command);
+    }
+  }
+
   /**
    * Get commands available in the current mode
    */
@@ -176,6 +196,7 @@ export class CliChatService implements ChatService {
   }
 
   getCommandsForActiveModes(): ChatCommand[] {
+    this.refreshExtensions();
     const activeModes = this.modes
       .filter((mode) => mode.active)
       .map((mode) => mode.name);
@@ -216,7 +237,7 @@ export class CliChatService implements ChatService {
       const command = availableCommands.find((cmd) => cmd.name === commandName);
 
       if (command) {
-        const result = await command.handler(args);
+        const result = await command.handler(args, this);
 
         // If handler returns a CommandResult and it's not handled, pass to modules
         if (result && typeof result === "object" && "handled" in result) {

package/src/chat/modules/InternalChatModule.ts

@@ -10,6 +10,7 @@ import { SystemModule } from "./SystemModule";
 import { SetupModule } from "./SetupModule";
 import { CustomCommandsModule } from "./CustomCommandsModule";
 import { ShellCommandModule } from "./ShellCommandModule";
+import { ToolCommandModule } from "./ToolCommandModule";
 import { RendererModule } from "./RendererModule";
 import { SessionsModule } from "./SessionsModule";
 import { RemoteSyncModule } from "./RemoteSyncModule";
@@ -32,6 +33,7 @@ export class InternalChatModule implements ChatModule {
   private setupModule: SetupModule;
   private customCommandsModule = new CustomCommandsModule();
   private shellCommandModule = new ShellCommandModule();
+  private toolCommandModule = new ToolCommandModule();
   private rendererModule: RendererModule;
   private remoteSyncModule: RemoteSyncModule;
 
@@ -61,6 +63,7 @@ export class InternalChatModule implements ChatModule {
     await this.customCommandsModule.initialize(chatService);
     await this.remoteSyncModule.initialize(chatService);
     await this.shellCommandModule.initialize(chatService);
+    await this.toolCommandModule.initialize(chatService);
     await this.clipboardImageModule.initialize(chatService);
     
     // Register our own commands (exit and multi) - not duplicated by BaseChatModule
@@ -93,6 +96,7 @@ export class InternalChatModule implements ChatModule {
       ...this.setupModule.getCommands(),
       ...this.customCommandsModule.getCommands(),
       ...this.shellCommandModule.getCommands(),
+      ...this.toolCommandModule.getCommands(),
       ...this.rendererModule.getCommands(),
       ...this.remoteSyncModule.getCommands(),
       {
@@ -120,6 +124,7 @@ export class InternalChatModule implements ChatModule {
       ...this.setupModule.getModes(),
       ...this.customCommandsModule.getModes(),
       ...this.shellCommandModule.getModes(),
+      ...this.toolCommandModule.getModes(),
       ...this.rendererModule.getModes(),
     ];
   }

package/src/chat/modules/ToolCommandModule.ts

@@ -0,0 +1,102 @@
+import { ToolCall } from "../../clients/types";
+import { services } from "../../services";
+import { BaseChatModule } from "./BaseChatModule";
+import { ChatCommand, ChatContext, CommandResult } from "../types";
+
+/** Execute registered tools directly from interactive chat. */
+export class ToolCommandModule extends BaseChatModule {
+  name = "tool-command";
+  description = "Execute a tool with /tool";
+
+  public getCommands(): ChatCommand[] {
+    return [
+      {
+        name: "tool",
+        description: "Execute a tool call from JSON",
+        handler: (args: string[]) => this.handleToolCommand(args),
+      },
+    ];
+  }
+
+  private async handleToolCommand(args: string[]): Promise<CommandResult> {
+    const input = args.join(" ").trim();
+    if (!input) {
+      console.log('Usage: /tool {"name":"toolName","arguments":{"key":"value"}}');
+      return { handled: true };
+    }
+
+    let toolCall: ToolCall;
+    try {
+      toolCall = this.parseToolCall(input);
+    } catch (error: any) {
+      console.error(`Invalid tool call JSON: ${error.message}`);
+      return { handled: true };
+    }
+
+    const tools = this.chatService.getTools() || services().Tools;
+    if (!tools) {
+      console.error("Tool execution failed: no tool service is available");
+      return { handled: true };
+    }
+
+    try {
+      const context = this.chatService.getContext();
+      const result = await tools.callTool(
+        toolCall,
+        tools.getFunctionNames(),
+        {
+          caller: context.selectedAgent,
+          taskId: context.activeAgentTaskId,
+        }
+      );
+
+      const toolError = result.toolMessages?.find(
+        (message: any) => message.name === "error"
+      );
+      if (toolError) {
+        console.error(`Tool execution failed: ${toolError.content}`);
+      } else {
+        const output = result.functionResp;
+        console.log(
+          typeof output === "object"
+            ? JSON.stringify(output, null, 2)
+            : String(output)
+        );
+      }
+    } catch (error: any) {
+      console.error(`Tool execution failed: ${error.message || String(error)}`);
+    }
+
+    return { handled: true };
+  }
+
+  private parseToolCall(input: string): ToolCall {
+    const parsed = JSON.parse(input);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      throw new Error("expected a JSON object");
+    }
+
+    const fn = parsed.function || parsed;
+    if (!fn || typeof fn.name !== "string" || !fn.name.trim()) {
+      throw new Error('expected a non-empty "name" (or "function.name")');
+    }
+
+    const args = fn.arguments === undefined ? {} : fn.arguments;
+    if (typeof args !== "string" && (args === null || typeof args !== "object")) {
+      throw new Error('"arguments" must be a JSON object, array, or JSON string');
+    }
+
+    return {
+      id: typeof parsed.id === "string" ? parsed.id : `chat_tool_${Date.now()}`,
+      type: "function",
+      function: {
+        name: fn.name,
+        arguments: typeof args === "string" ? args : JSON.stringify(args),
+      },
+    };
+  }
+
+  async handleInput(input: string, context: ChatContext): Promise<boolean> {
+    return false;
+  }
+}

package/src/chat/modules/index.ts

@@ -4,4 +4,5 @@ export { AgentModule } from './AgentModule';
 export { VoiceModule } from './VoiceModule';
 export { InternalChatModule } from './InternalChatModule';
 export { ShellCommandModule } from './ShellCommandModule';
+export { ToolCommandModule } from './ToolCommandModule';
 export { RendererModule } from './RendererModule';

package/src/chat/types.ts

@@ -45,7 +45,7 @@ export interface CommandResult {
 export interface ChatCommand {
   name: string;
   description: string;
-  handler: (args: string[]) => Promise<void | CommandResult>;
+  handler: (args: string[], chatService?: ChatService) => Promise<void | CommandResult>;
   modes?: string[]; // Commands can specify which modes they're available in
 }
 

package/src/cli.ts

@@ -62,6 +62,7 @@ import { addSkillsCommand } from "./commands/skills";
 import { addAgentsCommand } from "./commands/agents";
 import { addHashCommand } from "./commands/hash";
 import { addSandboxCommand } from "./commands/sandbox";
+import { addProcessesCommand } from "./commands/processes";
 
 // Handle unhandled promise rejections gracefully — particularly from MCP SDK
 // which fires errors via event emitters that can bypass Promise.allSettled.
@@ -131,15 +132,21 @@ async function main() {
   addAgentsCommand(program, getChatService);
   addHashCommand(program);
   addSandboxCommand(program);
+  addProcessesCommand(program);
 
   // Load global modules early (before parse) so they can register CLI subcommands.
   // We pass only the Program in context — no services are spun up at this stage.
   // Each module's command action is responsible for calling setupServices() as needed.
   try {
     const globalConfig = await getGlobalConfig();
+    const globalModules = [...new Set(globalConfig.modules || [])];
+    const localModules = [...new Set(config.modules || [])];
+    // Local modules take precedence: if a module appears in both global and
+    // local configs, use the local version so it resolves against local
+    // node_modules first. This prevents duplicate command registration errors.
     const allModulePaths = [
-      ...(globalConfig.modules || []),
-      ...(config.modules || []),
+      ...globalModules.filter((m) => !localModules.includes(m)),
+      ...localModules,
     ];
     if (allModulePaths.length) {
       const earlyModulesService = new ModulesService();

package/src/clients/http.ts

@@ -1,4 +1,4 @@
-import http from "../utils/http";
+import http, { HTTP_UNAUTHORIZED_HANDLER, RefreshableHeaders } from "../utils/http";
 import {
   GenericClient,
   CompletionOptions,
@@ -17,16 +17,72 @@ export interface HttpClientOptions {
   extra_body?: Record<string, any>;
 }
 
+/**
+ * Optional callback that, when set, is called whenever a 401 is received
+ * (reactive refresh) or whenever `needsRefresh()` returns true before a
+ * request (proactive refresh).  Override this in a subclass or set it
+ * directly on an instance:
+ *
+ *   client.refreshToken = async () => { const newJwt = await ...; client.setJwt(newJwt); };
+ */
+export type RefreshTokenFn = () => Promise<void>;
+
 export class HttpClient implements GenericClient {
   /** Timeout in milliseconds for HTTP requests. Default: 30000 (30s). Use 0 to disable. */
   private timeout: number;
-  private headers: Record<string, string>;
+  private headers: RefreshableHeaders;
   private extra_body: Record<string, any>;
   /** Optional pricing table: model id → per-million-token prices */
   private pricingMap: Record<string, ModelPricing> = {};
 
+  /**
+   * Override this to provide automatic token refresh.  Called reactively on
+   * 401 responses (via HTTP_UNAUTHORIZED_HANDLER) and proactively before
+   * each request when `needsRefresh()` returns true.
+   *
+   * The implementation should obtain a new token and call `this.setJwt()`
+   * (or `this.setKey()`) before returning.
+   */
+  refreshToken: RefreshTokenFn | undefined = undefined;
+
+  /**
+   * Override this to provide proactive expiry detection.  When it returns
+   * `true`, `refreshToken()` is called before the next outgoing request.
+   * The default implementation decodes the JWT `exp` claim (< 5 min window).
+   */
+  needsRefresh(): boolean {
+    const authHeader = (this.headers as Record<string, string>)["Authorization"];
+    if (!authHeader) return false;
+    const token = authHeader.startsWith("Bearer ") ? authHeader.slice(7) : authHeader;
+    try {
+      const parts = token.split(".");
+      if (parts.length !== 3) return false;
+      const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+      return typeof payload.exp === "number" && payload.exp * 1000 - Date.now() < 5 * 60 * 1000;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Call before each outgoing request to proactively refresh an expiring
+   * token.  No-ops when no `refreshToken` hook is set.
+   */
+  private async refreshIfNeeded(): Promise<void> {
+    if (this.refreshToken && this.needsRefresh()) {
+      await this.refreshToken();
+    }
+  }
+
   constructor(private baseUrl: string, options: HttpClientOptions = {}) {
     this.headers = options.headers ?? {};
+    // Wire the reactive 401 handler so the low-level http util can retry once
+    // after a token refresh without callers needing to do anything extra.
+    Object.defineProperty(this.headers, HTTP_UNAUTHORIZED_HANDLER, {
+      enumerable: false,
+      configurable: true,
+      get: () => this.refreshToken ? () => this.refreshToken!() : undefined,
+    });
     this.timeout = options.timeout ?? 30000;
     this.extra_body = options.extra_body ?? {};
   }
@@ -69,10 +125,8 @@ export class HttpClient implements GenericClient {
   }
 
   setJwt(jwt: string) {
-    this.headers = {
-      ...this.headers,
-      Authorization: `Bearer ${jwt}`,
-    };
+    // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
+    this.headers.Authorization = `Bearer ${jwt}`;
   }
 
   setBaseUrl(baseUrl: string) {
@@ -163,7 +217,8 @@ export class HttpClient implements GenericClient {
     if (options.timeout !== undefined) this.timeout = options.timeout;
     if (options.extra_body !== undefined) this.extra_body = options.extra_body;
     if (options.headers) {
-      this.headers = { ...this.headers, ...options.headers };
+      // Mutate in-place to preserve the HTTP_UNAUTHORIZED_HANDLER symbol property.
+      Object.assign(this.headers, options.headers);
     }
   }
 
@@ -183,6 +238,7 @@ export class HttpClient implements GenericClient {
   async createChatCompletion(
     options: CompletionOptions
   ): Promise<CompletionResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const body = {
         ...options,
@@ -232,6 +288,7 @@ export class HttpClient implements GenericClient {
   async *createChatCompletionStream(
     options: CompletionOptions
   ): AsyncGenerator<StreamChunk> {
+    await this.refreshIfNeeded();
     const body = {
       ...options,
       model: options.model,
@@ -316,6 +373,7 @@ export class HttpClient implements GenericClient {
     options: CompletionOptions,
     store = false
   ): Promise<CompletionResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       // Extract system messages as instructions
       const systemMessages = options.messages.filter((m) => m.role === "system");
@@ -484,6 +542,7 @@ export class HttpClient implements GenericClient {
   }
 
   async createEmbedding(options: EmbeddingOptions): Promise<EmbeddingResponse> {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const response = await http.post(
         `${this.baseUrl}/v1/embeddings`,
@@ -511,6 +570,7 @@ export class HttpClient implements GenericClient {
   }
 
   async getModels(type = "all") {
+    await this.refreshIfNeeded();
     return this.withRetry(async () => {
       const response = await http.get(`${this.baseUrl}/v1/models?type=${type}`, {
         headers: this.headers as Record<string, string>,

package/src/clients/index.ts

@@ -528,12 +528,14 @@ export class AIClient {
   }
 
   providerHasModel(provider: string, model: string): boolean {
+    if (!provider) return false;
     const models = this.clientModels[provider];
     if (!models) return false;
     return models.includes(model);
   }
 
   findModel(modelPrefix: string) {
+    if (!modelPrefix) return undefined;
     for (const provider of Object.keys(this.clientModels)) {
       const models = this.clientModels[provider] as string[];
       const foundModel = models.find((m) => m.startsWith(modelPrefix));

package/src/commands/agents.ts

@@ -35,6 +35,18 @@ import { getConfig } from "../config";
 const AGENTS_DIR = path.join(".knowhow", "processes", "agents");
 const SESSIONS_DIR = path.join(".knowhow", "chats", "sessions");
 
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "error",
+  "done",
+]);
+const ACTIVE_STATUSES = new Set(["running", "paused"]);
+// Older task records did not persist a pid. After this grace period, report
+// them as unverifiable rather than continuing to claim they are running.
+const UNVERIFIED_TASK_GRACE_MS = 5 * 60 * 1000;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -68,11 +80,42 @@ function loadStatus(taskId: string): string {
   }
 }
 
-/** Get the canonical status — meta.status is live/preferred; status.txt is fallback */
-function getStatus(taskId: string, meta: any | null): string {
-  if (meta?.status) return meta.status;
-  const fromFile = loadStatus(taskId);
-  return fromFile ?? "unknown";
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error: any) {
+    // EPERM means the process exists but cannot be signalled by this user.
+    return error?.code === "EPERM";
+  }
+}
+
+/**
+ * Get the effective status, reconciling persisted state with process liveness.
+ * An agent can be terminated before AgentSyncFs gets a chance to finalize its
+ * files; those records must not remain "running" forever.
+ */
+export function getStatus(taskId: string, meta: any | null): string {
+  const persisted = meta?.status || loadStatus(taskId) || "unknown";
+  if (TERMINAL_STATUSES.has(persisted)) return persisted;
+  if (meta?.inProgress === false) return "completed";
+  if (!ACTIVE_STATUSES.has(persisted)) return persisted;
+
+  const pid = meta?.pid ?? meta?.processId;
+  if (typeof pid === "number") {
+    return pidAlive(pid) ? persisted : "failed";
+  }
+
+  const lastKnownTime = meta?.lastUpdate ?? meta?.startTime;
+  const lastKnownMs = lastKnownTime ? new Date(lastKnownTime).getTime() : NaN;
+  if (
+    !Number.isFinite(lastKnownMs) ||
+    Date.now() - lastKnownMs > UNVERIFIED_TASK_GRACE_MS
+  ) {
+    return "stale";
+  }
+
+  return persisted;
 }
 
 function elapsedStr(startIso: string | undefined, endIso?: string): string {
@@ -203,9 +246,9 @@ function buildRows(includeAll: boolean): Row[] {
 
   for (const taskId of taskIds) {
     const meta = loadMeta(taskId);
-    const status = meta?.status ?? loadStatus(taskId);
+    const status = getStatus(taskId, meta);
 
-    if (!includeAll && (status === "completed" || status === "killed")) {
+    if (!includeAll && (TERMINAL_STATUSES.has(status) || status === "stale")) {
       const lastUpdate = meta?.lastUpdate ?? "";
       if (lastUpdate) {
         const age = Date.now() - new Date(lastUpdate).getTime();
@@ -221,7 +264,9 @@ function buildRows(includeAll: boolean): Row[] {
         : "";
     const elapsed = elapsedStr(
       meta?.startTime,
-      meta?.status === "completed" ? meta?.lastUpdate : undefined
+      TERMINAL_STATUSES.has(status) || status === "stale"
+        ? meta?.lastUpdate
+        : undefined
     );
     const lastUpdate = meta?.lastUpdate
       ? new Date(meta.lastUpdate).toLocaleString()