@tyvm/knowhow 0.0.146 → 0.0.148

package/src/commands/misc.ts

@@ -23,8 +23,9 @@ export function addLoginCommand(program: Command): void {
     .command("login")
     .description("Login to knowhow")
     .option("--jwt", "Use manual JWT input instead of browser login")
-    .action(async (opts) => {
-      await login(opts.jwt);
+    .option("-i, --identity <path>", "Ed25519 private key to use for public-key login")
+    .action(async (options: { jwt?: boolean; identity?: string }) => {
+      await login(options.jwt, options.identity);
     });
 }
 

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

@@ -1,13 +1,28 @@
 import http from "./utils/http";
 import fs from "fs";
 import path from "path";
-import { chmod } from "fs/promises";
 import { ask } from "./utils";
 import { getConfig, updateConfig } from "./config";
 import { KNOWHOW_API_URL } from "./services/KnowhowClient";
 import { BrowserLoginService } from "./auth/browserLogin";
-
-export async function login(jwtFlag?: boolean): Promise<void> {
+import { authenticateWithKey, hasKeyPair, registerPublicKey } from "./auth/keyAuth";
+import { getOrCreatePublicKey } from "./auth/keyManager";
+
+/**
+ * Log in to Knowhow.
+ *
+ * Strategy (in order):
+ *   1. `--jwt`   flag: prompt for a raw JWT and write it to disk.
+ *   2. Key auth: if an Ed25519 key and configured organization exist, sign a
+ *                server challenge and exchange it for an organization-bound JWT.
+ *   3. Browser:  open the browser approval flow (first-time login or key not yet registered).
+ *
+ * After any successful login the local config is updated with the current user's orgId.
+ *
+ * @param jwtFlag      True when --jwt flag is passed.
+ * @param identityPath Optional path to a specific private key file (--identity flag).
+ */
+export async function login(jwtFlag?: boolean, identityPath?: string): Promise<void> {
   if (!KNOWHOW_API_URL) {
     throw new Error("Error: KNOWHOW_API_URL environment variable not set.");
   }
@@ -15,9 +30,8 @@ export async function login(jwtFlag?: boolean): Promise<void> {
   if (jwtFlag) {
     const jwt = await ask("Enter your JWT: ");
 
-    // Update the JWT file
     const configDir = path.join(process.cwd(), ".knowhow");
-    const jwtFile = path.join(process.cwd(), ".knowhow", ".jwt");
+    const jwtFile = path.join(configDir, ".jwt");
 
     if (!fs.existsSync(configDir)) {
       fs.mkdirSync(configDir, { recursive: true });
@@ -26,23 +40,69 @@ export async function login(jwtFlag?: boolean): Promise<void> {
     fs.chmodSync(jwtFile, 0o600);
     console.log("JWT updated successfully.");
   } else {
-    // Use browser login as default method
-    console.log("Starting browser-based authentication...");
+    const config = await getConfig();
+    const orgId = config.orgId;
+
+    // A local key is not proof of registration. Let the selected environment
+    // check it, but only when an organization is available to bind the attempt.
+    if (orgId && hasKeyPair(identityPath)) {
+      console.log("Found CLI identity — authenticating with public key...");
+      try {
+        const success = await authenticateWithKey(orgId, KNOWHOW_API_URL, identityPath);
+        if (success) {
+          console.log("✅ Successfully authenticated via public key!");
+          return await postLoginConfigUpdate(identityPath);
+        }
+        console.warn("Key authentication returned no JWT, falling back to browser login...");
+      } catch (error: unknown) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Key authentication failed (${message}), falling back to browser login...`);
+      }
+    }
+
+    // Fall back when no org/key is configured or when key auth is unavailable.
+    await doBrowserLogin(identityPath);
+  }
+
+  await postLoginConfigUpdate(identityPath);
+}
+
+/** Complete browser PKCE, then best-effort bootstrap the selected identity. */
+async function doBrowserLogin(identityPath?: string): Promise<void> {
+  console.log("Starting browser-based authentication...");
+  try {
+    const existingConfig = await getConfig();
+    const existingOrgId = existingConfig?.orgId;
+    const browserLoginService = new BrowserLoginService(undefined, existingOrgId);
+    await browserLoginService.login();
+    console.log("✅ Successfully authenticated via browser!");
+
     try {
-      // Pass existing orgId from config (if any) so the browser pre-selects the right org
-      const existingConfig = await getConfig();
-      const existingOrgId = existingConfig?.orgId;
-      const browserLoginService = new BrowserLoginService(undefined, existingOrgId);
-      await browserLoginService.login();
-      console.log("Successfully authenticated via browser!");
-    } catch (error) {
-      console.error("Browser authentication failed:", error.message);
-      console.log("You can try manual JWT login with: knowhow login --jwt");
-      throw error;
+      const keyPair = getOrCreatePublicKey(identityPath);
+      await registerPublicKey(
+        await loadJwt(),
+        keyPair.publicKeyBase64,
+        KNOWHOW_API_URL
+      );
+      console.log(`Registered CLI identity ${keyPair.fingerprint}`);
+    } catch (registrationError: unknown) {
+      // Browser login remains valid when key registration is unavailable (for
+      // example during a rolling backend deployment or for a partial identity).
+      const message = registrationError instanceof Error
+        ? registrationError.message
+        : String(registrationError);
+      console.warn(`Could not register CLI identity (${message}). Browser login is still active.`);
     }
+  } catch (error: unknown) {
+    const msg = error instanceof Error ? error.message : String(error);
+    console.error("Browser authentication failed:", msg);
+    console.log("You can try manual JWT login with: knowhow login --jwt");
+    throw error;
   }
+}
 
-  // Get current user/org information
+/** After any successful login, update the local config with the current user/org. */
+async function postLoginConfigUpdate(identityPath?: string): Promise<void> {
   try {
     const storedJwt = await loadJwt();
     const { user, currentOrg } = await checkJwt(storedJwt);
@@ -59,25 +119,26 @@ export async function login(jwtFlag?: boolean): Promise<void> {
     }
 
     const hasProvider = config.modelProviders.find(
-      (provider) => provider.provider === "knowhow"
+      (provider: { provider: string }) => provider.provider === "knowhow"
     );
     if (!hasProvider) {
-      config.modelProviders.push({
-        provider: "knowhow",
-      });
+      config.modelProviders.push({ provider: "knowhow" });
     }
-    // Save orgId to config so sync:remote and other features use the correct org
+
     if (orgId) {
       config.orgId = orgId;
     }
 
+    if (identityPath) {
+      config.cliIdentityPath = path.resolve(identityPath);
+    }
+
     await updateConfig(config);
-  } catch (error) {
+  } catch (error: unknown) {
     if (http.isHttpError(error) && error.response) {
-      // error.body is the parsed JSON response body (set by http.ts when response is not ok)
-      const errData = error.body ?? { message: "Unknown error" };
+      const errData = (error as any).body ?? { message: "Unknown error" };
       throw new Error(
-        `Error: ${error.status} - ${errData?.message || "Unknown error"}`
+        `Error: ${(error as any).status} - ${errData?.message || "Unknown error"}`
       );
     }
     console.log(
@@ -112,7 +173,7 @@ export async function checkJwt(storedJwt: string) {
   const orgs = user.orgs;
   const orgId = response.data.orgId;
 
-  const currentOrg = orgs.find((org) => {
+  const currentOrg = orgs.find((org: { organizationId: string }) => {
     return org.organizationId === orgId;
   });
 

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

@@ -3,8 +3,10 @@ import { IAgent } from "../agents/interface";
 import { EventService } from "./EventService";
 import { ToolsService } from "./Tools";
 import { ConfigAgent } from "../agents/configurable/ConfigAgent";
+import { TraceAll } from "../util/Trace";
 import { AgentContext } from "../agents/base/base";
 
+@TraceAll()
 export class AgentService {
   private agents: Map<string, IAgent> = new Map();
   private agentContext: AgentContext | null = null;