@tyvm/knowhow 0.0.137 → 0.0.140

package/src/agents/tools/connectAgent.ts

@@ -0,0 +1,353 @@
+import * as fs from "fs";
+import * as path from "path";
+import { Tool } from "../../clients/types";
+import { ToolCallContext } from "../../services/Tools";
+
+/** Resolve the agents dir lazily so tests (and cwd changes) are respected. */
+function agentsDir(): string {
+  return path.join(process.cwd(), ".knowhow", "processes", "agents");
+}
+
+/**
+ * Active relays, keyed by connection id, so stopConnections can tear them down.
+ * A relay watches a speaker task's thread and appends new assistant messages to
+ * a listener task's input.txt.
+ */
+interface ActiveRelay {
+  id: string;
+  listener: string;
+  speaker: string;
+  timer: NodeJS.Timeout;
+  expiry?: NodeJS.Timeout;
+  seenAssistant: number;
+  updates: number;
+}
+
+const relays = new Map<string, ActiveRelay>();
+let relaySeq = 0;
+
+function readMeta(taskId: string): any | null {
+  try {
+    const metaPath = path.join(agentsDir(), taskId, "metadata.json");
+    if (!fs.existsSync(metaPath)) return null;
+    return JSON.parse(fs.readFileSync(metaPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Flatten a metadata.threads structure into a single message array. */
+function flattenThreads(threads: any): any[] {
+  if (!threads) return [];
+  if (Array.isArray(threads)) {
+    if (threads.length && Array.isArray(threads[0])) return threads.flat();
+    return threads;
+  }
+  return [];
+}
+
+/** Extract the text content of an assistant message. */
+function assistantText(msg: any): string | undefined {
+  if (!msg || msg.role !== "assistant") return undefined;
+  if (typeof msg.content === "string" && msg.content.trim()) {
+    return msg.content.trim();
+  }
+  if (Array.isArray(msg.content)) {
+    const text = msg.content
+      .filter((c: any) => c?.type === "text")
+      .map((c: any) => c.text)
+      .join("\n")
+      .trim();
+    if (text) return text;
+  }
+  return undefined;
+}
+
+function appendToInput(inputPath: string, line: string): void {
+  const existing = fs.existsSync(inputPath)
+    ? fs.readFileSync(inputPath, "utf8")
+    : "";
+  const next =
+    existing && !existing.endsWith("\n")
+      ? `${existing}\n${line}\n`
+      : `${existing}${line}\n`;
+  fs.writeFileSync(inputPath, next, "utf8");
+}
+
+const TERMINAL_STATUSES = new Set([
+  "completed",
+  "failed",
+  "killed",
+  "error",
+  "done",
+]);
+
+function isTerminal(meta: any | null): boolean {
+  if (!meta) return false;
+  if (meta.status && TERMINAL_STATUSES.has(meta.status)) return true;
+  if (meta.inProgress === false) return true;
+  return false;
+}
+
+export interface AgentConnection {
+  /** taskId of the agent that RECEIVES the speaker's messages. */
+  listener: string;
+  /** taskId of the agent whose output is relayed to the listener. */
+  speaker: string;
+}
+
+export interface ConnectAgentParams {
+  /**
+   * The connections to wire up. Each connection relays the speaker's new
+   * assistant messages into the listener's input queue.
+   *
+   * Topologies are expressed as arrays of connections, e.g.:
+   *   bidirectional(a,b): [{listener:a,speaker:b},{listener:b,speaker:a}]
+   *   pipeline(a,b,c):    [{listener:b,speaker:a},{listener:c,speaker:b}]
+   *   star(hub,[x,y]):    [{listener:hub,speaker:x},{listener:hub,speaker:y},...]
+   *   mesh([a,b,c]):      every ordered pair.
+   */
+  connections: AgentConnection[];
+  /** Poll interval in ms for reading speaker threads. Default 3000. */
+  intervalMs?: number;
+  /** Max relayed messages per connection before auto-stopping. Default 50. */
+  maxUpdates?: number;
+  /** Max total duration in ms before auto-stopping each relay. Default 30 min. */
+  maxDurationMs?: number;
+  _ctx?: ToolCallContext;
+}
+
+/**
+ * Wire agents together so they can communicate while working. Each connection
+ * relays a speaker agent's new assistant messages into a listener agent's input
+ * queue (via sendAgentMessage-style input.txt appends). Because it accepts an
+ * ARRAY of connections, any topology — bidirectional, pipeline, ring, star,
+ * mesh — is expressible in a single call.
+ *
+ * Relays run in the background on the orchestrating process, dedupe by thread
+ * position, and auto-expire after maxUpdates / maxDurationMs so they can't leak.
+ * Call stopConnections to tear them down early.
+ */
+export async function connectAgent(
+  params: ConnectAgentParams
+): Promise<string> {
+  const {
+    connections,
+    intervalMs = 3000,
+    maxUpdates = 50,
+    maxDurationMs = 30 * 60 * 1000,
+  } = params;
+
+  if (!Array.isArray(connections) || connections.length === 0) {
+    return "connectAgent: connections must be a non-empty array of { listener, speaker }.";
+  }
+
+  const interval = Math.max(1000, intervalMs);
+  const started: string[] = [];
+  const errors: string[] = [];
+
+  for (const conn of connections) {
+    const { listener, speaker } = conn || ({} as AgentConnection);
+    if (!listener || !speaker) {
+      errors.push(`skipped connection missing listener/speaker: ${JSON.stringify(conn)}`);
+      continue;
+    }
+    if (listener === speaker) {
+      errors.push(`skipped self-connection for ${listener}`);
+      continue;
+    }
+
+    const speakerDir = path.join(agentsDir(), speaker);
+    const listenerDir = path.join(agentsDir(), listener);
+    if (!fs.existsSync(speakerDir)) {
+      errors.push(`speaker task dir not found: ${speaker}`);
+      continue;
+    }
+    if (!fs.existsSync(listenerDir)) {
+      errors.push(`listener task dir not found: ${listener}`);
+      continue;
+    }
+
+    relaySeq += 1;
+    const id = `conn_${speaker.slice(0, 8)}_to_${listener.slice(0, 8)}_${relaySeq}`;
+    const listenerInput = path.join(listenerDir, "input.txt");
+
+    // Seed the seen-count to the CURRENT number of assistant messages so we
+    // only relay NEW output produced after the connection is established.
+    const seedMeta = readMeta(speaker);
+    const seedAssistants = flattenThreads(seedMeta?.threads).filter(
+      (m) => m?.role === "assistant"
+    ).length;
+
+    const relay: ActiveRelay = {
+      id,
+      listener,
+      speaker,
+      timer: undefined as any,
+      seenAssistant: seedAssistants,
+      updates: 0,
+    };
+
+    const tick = () => {
+      try {
+        const meta = readMeta(speaker);
+        const assistants = flattenThreads(meta?.threads).filter(
+          (m) => m?.role === "assistant"
+        );
+        // Relay any assistant messages beyond what we've seen.
+        for (let i = relay.seenAssistant; i < assistants.length; i++) {
+          const text = assistantText(assistants[i]);
+          if (text) {
+            appendToInput(
+              listenerInput,
+              `[from:${speaker}] ${text}`
+            );
+            relay.updates += 1;
+          }
+        }
+        relay.seenAssistant = assistants.length;
+
+        if (relay.updates >= maxUpdates || isTerminal(meta)) {
+          stopRelay(id);
+        }
+      } catch {
+        // ignore transient read/write errors; try again next tick
+      }
+    };
+
+    relay.timer = setInterval(tick, interval);
+    if (typeof (relay.timer as any).unref === "function") {
+      (relay.timer as any).unref();
+    }
+    if (maxDurationMs) {
+      relay.expiry = setTimeout(() => stopRelay(id), maxDurationMs);
+      if (typeof (relay.expiry as any).unref === "function") {
+        (relay.expiry as any).unref();
+      }
+    }
+
+    relays.set(id, relay);
+    started.push(id);
+  }
+
+  const parts = [
+    `Wired ${started.length} connection(s): ${started.join(", ") || "(none)"}.`,
+  ];
+  if (errors.length) {
+    parts.push(`Issues: ${errors.join("; ")}.`);
+  }
+  parts.push(
+    `Relays poll every ${interval}ms, up to ${maxUpdates} messages each. Call stopConnections to tear them down.`
+  );
+  return parts.join(" ");
+}
+
+function stopRelay(id: string): void {
+  const relay = relays.get(id);
+  if (!relay) return;
+  if (relay.timer) clearInterval(relay.timer);
+  if (relay.expiry) clearTimeout(relay.expiry);
+  relays.delete(id);
+}
+
+export interface StopConnectionsParams {
+  /** Connection id to stop. Omit to stop ALL active relays. */
+  id?: string;
+  _ctx?: ToolCallContext;
+}
+
+/** Tear down one relay (by id) or all of them. Companion to connectAgent. */
+export async function stopConnections(
+  params: StopConnectionsParams
+): Promise<string> {
+  const { id } = params;
+  if (id) {
+    const existed = relays.has(id);
+    stopRelay(id);
+    return existed
+      ? `Stopped connection ${id}.`
+      : `No active connection with id ${id}.`;
+  }
+  const count = relays.size;
+  for (const rid of [...relays.keys()]) stopRelay(rid);
+  return `Stopped ${count} active connection(s).`;
+}
+
+export const connectAgentDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "connectAgent",
+    description:
+      "Wire running agents together so they can communicate while working. Takes an ARRAY of " +
+      "{ listener, speaker } connections — each relays the speaker's new assistant messages into the " +
+      "listener's input queue. Because it accepts an array, ANY topology is one call: bidirectional " +
+      "([{listener:a,speaker:b},{listener:b,speaker:a}]), pipeline, ring, star (many speakers → one hub), " +
+      "or full mesh (every ordered pair). Relays run in the background, dedupe by thread position, and " +
+      "auto-expire (or stop when the speaker completes). Use stopConnections to tear them down early. " +
+      "Combine with startAgentTask (spawn) and waitForAgentCompleted (join).",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        connections: {
+          type: "array",
+          description:
+            "Array of connections to establish. Each is { listener, speaker } where speaker's output " +
+            "is relayed into listener's input queue.",
+          items: {
+            type: "object",
+            properties: {
+              listener: {
+                type: "string",
+                description: "taskId of the agent that receives messages.",
+              },
+              speaker: {
+                type: "string",
+                description:
+                  "taskId of the agent whose output is relayed to the listener.",
+              },
+            },
+          },
+        },
+        intervalMs: {
+          type: "number",
+          description:
+            "Poll interval in ms for reading speaker threads. Default: 3000.",
+        },
+        maxUpdates: {
+          type: "number",
+          description:
+            "Max relayed messages per connection before auto-stopping. Default: 50.",
+        },
+        maxDurationMs: {
+          type: "number",
+          description:
+            "Max total duration in ms before auto-stopping each relay. Default: 1800000 (30 min).",
+        },
+      },
+      required: ["connections"],
+    },
+  },
+};
+
+export const stopConnectionsDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "stopConnections",
+    description:
+      "Tear down agent connections established with connectAgent. Pass a connection id to stop a " +
+      "specific relay, or omit id to stop ALL active relays.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        id: {
+          type: "string",
+          description:
+            "The connection id returned by connectAgent. Omit to stop ALL active connections.",
+        },
+      },
+      required: [],
+    },
+  },
+};

package/src/agents/tools/index.ts

@@ -21,6 +21,12 @@ export * from "./aiClient";
 export * from "./googleSearch";
 export * from "./stringReplace";
 export * from "./startAgentTask";
+export * from "./replyToParent";
+export * from "./runGenerate";
+export * from "./sendAgentMessage";
+export * from "./connectAgent";
+export * from "./waitForAgentCompleted";
+export * from "./observe";
 export * from "./ycmd";
 export * from "./mcp";
 export * from "./skills";

package/src/agents/tools/list.ts

@@ -7,6 +7,18 @@ import * as language from "./language/definitions";
 import * as mcp from "./mcp/definitions";
 import { googleSearchDefinition } from "./googleSearch";
 import { startAgentTaskDefinition } from "./startAgentTask";
+import { replyToParentDefinition } from "./replyToParent";
+import { runGenerateDefinition } from "./runGenerate";
+import { sendAgentMessageDefinition } from "./sendAgentMessage";
+import {
+  connectAgentDefinition,
+  stopConnectionsDefinition,
+} from "./connectAgent";
+import { waitForAgentCompletedDefinition } from "./waitForAgentCompleted";
+import {
+  observeDefinition,
+  stopObservingDefinition,
+} from "./observe";
 import { skillsToolDefinitions } from "./skills";
 
 function getPluginNames(): string {
@@ -19,6 +31,34 @@ function getPluginNames(): string {
 }
 
 export const includedTools = [
+  {
+    type: "function",
+    function: {
+      name: "agentCall",
+      description:
+        "Run another registered agent in-process as a blocking call and get its final answer back as a string. Unlike a plain llm() call, the target agent can use tools, loop, and maintain its own context. Useful as a graph node that delegates to a specialized agent (e.g. Researcher, Patcher). For long-running / parallel / detached work prefer startAgentTask.",
+      parameters: {
+        type: "object",
+        positional: true,
+        properties: {
+          agentName: {
+            type: "string",
+            description:
+              "The name of the agent to call (e.g. Researcher, Developer, Patcher).",
+          },
+          query: {
+            type: "string",
+            description: "The query / task to send to the agent.",
+          },
+        },
+        required: ["agentName", "query"],
+      },
+      returns: {
+        type: "string",
+        description: "The agent's final answer text.",
+      },
+    },
+  },
   {
     type: "function",
     function: {
@@ -679,6 +719,14 @@ export const includedTools = [
   },
   googleSearchDefinition,
   startAgentTaskDefinition,
+  replyToParentDefinition,
+  runGenerateDefinition,
+  sendAgentMessageDefinition,
+  connectAgentDefinition,
+  stopConnectionsDefinition,
+  waitForAgentCompletedDefinition,
+  observeDefinition,
+  stopObservingDefinition,
   ...ycmd.definitions,
   ...language.definitions,
   ...mcp.definitions,

package/src/agents/tools/observe.ts

@@ -0,0 +1,245 @@
+import { Tool } from "../../clients/types";
+import { ToolCallContext } from "../../services/Tools";
+import { ObservationSource } from "../base/base";
+
+/**
+ * Build an `ObservationSource` that repeatedly invokes another tool on an
+ * interval and emits its (stringified) result. This is the "tool poll" adapter
+ * — the original behavior of `observe`, now expressed as a source so it plugs
+ * into the unified `agent.observe()` subscription primitive on BaseAgent.
+ */
+function toolSource(
+  toolName: string,
+  toolArgs: Record<string, any>,
+  intervalMs: number,
+  caller: any,
+  Tools: any,
+  label: string
+): ObservationSource {
+  return {
+    label,
+    start(emit) {
+      const enabledTools =
+        typeof caller.getEnabledToolNames === "function"
+          ? caller.getEnabledToolNames()
+          : undefined;
+      const interval = Math.max(500, intervalMs);
+      let seq = 0;
+
+      const runOnce = async () => {
+        let resultStr: string;
+        try {
+          const toolCall = {
+            id: `obs_${toolName}_${seq++}`,
+            type: "function",
+            function: {
+              name: toolName,
+              arguments: JSON.stringify(toolArgs),
+            },
+          } as any;
+          const raw = await Tools.callTool(toolCall, enabledTools, {
+            caller,
+            taskId: caller?.currentTaskId,
+          });
+          resultStr = typeof raw === "string" ? raw : JSON.stringify(raw);
+        } catch (e: any) {
+          resultStr = `[error] ${e?.message ?? String(e)}`;
+        }
+        emit(resultStr);
+      };
+
+      const timer = setInterval(() => {
+        runOnce().catch(() => {});
+      }, interval);
+      if (typeof (timer as any).unref === "function") (timer as any).unref();
+
+      // teardown
+      return () => clearInterval(timer);
+    },
+  };
+}
+
+export interface ObserveParams {
+  /** The name of a tool to invoke repeatedly. */
+  toolName: string;
+  /** Arguments to pass to that tool on each invocation. */
+  toolArgs?: Record<string, any>;
+  /** Interval between invocations in milliseconds. Default 5000ms. */
+  intervalMs?: number;
+  /** Maximum number of updates before auto-stopping. Default 20. */
+  maxUpdates?: number;
+  /** Maximum total duration in milliseconds before auto-stopping. Default 10 min. */
+  maxDurationMs?: number;
+  /** Optional human-friendly label describing what's being observed. */
+  label?: string;
+  /**
+   * When true, only deliver an update to the caller if the tool result changed
+   * since the last poll. Default true (reduces noise).
+   */
+  onlyOnChange?: boolean;
+  _ctx?: ToolCallContext;
+}
+
+/**
+ * Periodically invoke another tool and stream its results back to the calling
+ * agent as pending context messages. Returns an observation id that can be
+ * passed to `stopObserving` to cancel early.
+ *
+ * This is a self-referential tool: it reads the calling agent off `_ctx.caller`
+ * and the ToolsService off `_ctx.Tools`, captures both synchronously (so
+ * concurrent tool calls on a shared ToolsService can't clobber the reference),
+ * and delegates to the agent's own `observe()` method — so the observation is
+ * scoped to and owned by that agent instance (no cross-agent clobber, torn down
+ * on task boundaries).
+ */
+export async function observe(params: ObserveParams): Promise<string> {
+  const {
+    toolName,
+    toolArgs = {},
+    intervalMs = 5000,
+    maxUpdates = 20,
+    maxDurationMs = 10 * 60 * 1000,
+    label,
+    onlyOnChange = true,
+    _ctx,
+  } = params;
+
+  if (!toolName) {
+    return "observe: toolName is required.";
+  }
+
+  // Capture the caller + Tools synchronously — do NOT read them lazily inside
+  // the interval, since the shared per-call context may change by then.
+  const caller = _ctx?.caller;
+  const Tools = _ctx?.Tools;
+
+  if (!Tools || typeof Tools.callTool !== "function") {
+    return "observe: no ToolsService available on _ctx to invoke the observed tool.";
+  }
+  if (!caller || typeof caller.observe !== "function") {
+    return "observe: no calling agent available on _ctx to receive updates.";
+  }
+
+  const displayLabel = label || `${toolName}(${JSON.stringify(toolArgs)})`;
+  const source = toolSource(
+    toolName,
+    toolArgs,
+    intervalMs,
+    caller,
+    Tools,
+    displayLabel
+  );
+
+  const id = caller.observe(source, {
+    onlyOnChange,
+    maxUpdates,
+    maxDurationMs,
+  });
+
+  const interval = Math.max(500, intervalMs);
+  return (
+    `Started observing "${displayLabel}" (id: ${id}). ` +
+    `Polling every ${interval}ms, up to ${maxUpdates} updates or ${Math.round(
+      maxDurationMs / 1000
+    )}s. ` +
+    `Updates will be delivered to you as they arrive. Call stopObserving with this id to cancel early.`
+  );
+}
+
+export interface StopObservingParams {
+  /** The observation id returned by observe. Omit to stop ALL observers. */
+  id?: string;
+  _ctx?: ToolCallContext;
+}
+
+/**
+ * Cancel an active observer (or all of them). Companion to `observe`.
+ * Delegates to the calling agent's own `stopObserving()`.
+ */
+export async function stopObserving(
+  params: StopObservingParams
+): Promise<string> {
+  const { id, _ctx } = params;
+  const caller = _ctx?.caller;
+
+  if (!caller || typeof caller.stopObserving !== "function") {
+    return "stopObserving: no calling agent available on _ctx.";
+  }
+
+  return caller.stopObserving(id, "stopped by stopObserving");
+}
+
+export const observeDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "observe",
+    description:
+      "Periodically invoke another tool in the background and stream its results back to you as " +
+      "context updates, without blocking. Useful for watching a long-running process — e.g. observe " +
+      "waitForAgentCompleted, agents status, or execCommand tailing a log — and reacting when things " +
+      "change (by default only changed results are delivered). Returns an observation id; auto-expires " +
+      "after maxUpdates or maxDurationMs. Call stopObserving with the id to cancel early.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        toolName: {
+          type: "string",
+          description: "The name of the tool to invoke repeatedly.",
+        },
+        toolArgs: {
+          type: "object",
+          description:
+            "The arguments object to pass to the observed tool on each poll.",
+        },
+        intervalMs: {
+          type: "number",
+          description: "Interval between polls in milliseconds. Default: 5000.",
+        },
+        maxUpdates: {
+          type: "number",
+          description:
+            "Maximum number of updates before auto-stopping. Default: 20.",
+        },
+        maxDurationMs: {
+          type: "number",
+          description:
+            "Maximum total observation duration in milliseconds before auto-stopping. Default: 600000 (10 min).",
+        },
+        label: {
+          type: "string",
+          description:
+            "Optional human-friendly label describing what's being observed.",
+        },
+        onlyOnChange: {
+          type: "boolean",
+          description:
+            "When true (default), only deliver an update when the tool result changed since the last poll.",
+        },
+      },
+      required: ["toolName"],
+    },
+  },
+};
+
+export const stopObservingDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "stopObserving",
+    description:
+      "Cancel an active observer started with the observe tool. Pass the observation id to stop a " +
+      "specific one, or omit id to stop all active observers.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        id: {
+          type: "string",
+          description:
+            "The observation id returned by observe. Omit to stop ALL active observers.",
+        },
+      },
+      required: [],
+    },
+  },
+};