@tyvm/knowhow 0.0.158 → 0.0.160

package/src/agents/tools/readBlocks.ts

@@ -1,83 +0,0 @@
-import * as fs from "fs";
-import { services, ToolsService } from "../../services";
-import { FileBlock } from "./types/fileblock";
-
-const BLOCK_SIZE = 500;
-export async function readBlocks(
-  filePath: string,
-  blockNumbers: number[] = []
-) {
-  // Get context from bound ToolsService
-  const toolService = (
-    this instanceof ToolsService ? this : services().Tools
-  ) as ToolsService;
-
-  const context = toolService.getContext();
-
-  // Emit pre-read blocking event
-  if (context.Events) {
-    await context.Events.emitBlocking("file:pre-read", {
-      filePath,
-      blockNumbers,
-    });
-  }
-
-  const text = fs.readFileSync(filePath, "utf8");
-
-  const lines = text.split("");
-  const blocks = [] as FileBlock[];
-
-  let index = 0;
-  let lineCount = 0;
-  while (lines.length > 0) {
-    const block = lines.splice(0, BLOCK_SIZE).join("");
-    blocks.push({
-      blockNumber: index,
-      content: block,
-      startLine: lineCount + 1,
-    });
-    index++;
-    lineCount += block.split("\n").length;
-
-    if (blocks.length > 20 && lines.length > 160000) {
-      blocks.push({
-        blockNumber: index,
-        content: "File trimmed. Too large to display",
-        startLine: lineCount + 1,
-      });
-      break;
-    }
-  }
-
-  if (blockNumbers.length === 0) {
-    // Emit post-read non-blocking event
-    if (context.Events) {
-      await context.Events.emitNonBlocking("file:post-read", {
-        filePath,
-        blockNumbers,
-        content: blocks.map((block) => block.content).join(""),
-      });
-    }
-
-    return blocks;
-  }
-
-  const filtered = blocks.filter((block) =>
-    blockNumbers.includes(block.blockNumber)
-  );
-
-  if (filtered.length === 0) {
-    return blocks;
-  }
-
-  // Emit post-read non-blocking event
-  if (context.Events) {
-    await context.Events.emitNonBlocking("file:post-read", {
-      filePath,
-      blockNumbers,
-      content: filtered.map((block) => block.content).join(""),
-    });
-  }
-
-  return filtered;
-}

package/src/agents/tools/readFile.ts

@@ -1,105 +0,0 @@
-import * as fs from "fs";
-import { fileExists } from "../../utils";
-import { services, ToolsService } from "../../services";
-import { getConfiguredEmbeddings } from "../../embeddings";
-import { fileSearch } from "./fileSearch";
-
-/*
- *export function readFile(filePath: string): string {
- *  try {
- *    const text = fs.readFileSync(filePath, "utf8");
- *    return JSON.stringify(
- *      text.split("\n").map((line, index) => [index + 1, line])
- *    );
- *  } catch (e) {
- *    return e.message;
- *  }
- *}
- */
-
-/**
- * Reads the contents of a file and returns them as plain text.
- *
- * Optionally accepts a 1-based, inclusive line range so callers can pull just
- * the region they care about in a single call. When a range is supplied the
- * returned content is prefixed with real source line numbers so the output can
- * be mapped straight back to an editable location.
- *
- * @param filePath The path to the file to read
- * @param fromLine Optional 1-based start line (inclusive)
- * @param toLine Optional 1-based end line (inclusive)
- */
-export async function readFile(
-  filePath: string,
-  fromLine?: number,
-  toLine?: number
-): Promise<string> {
-  // Get context from bound ToolsService
-  const toolService = (
-    this instanceof ToolsService ? this : services().Tools
-  ) as ToolsService;
-
-  const context = toolService.getContext();
-
-  // Emit pre-read blocking event
-  if (context.Events) {
-    await context.Events.emitBlocking("file:pre-read", {
-      filePath,
-    });
-  }
-
-  const exists = await fileExists(filePath);
-
-  if (!exists) {
-    const fileName = filePath.split("/").pop().split(".")[0];
-    const maybeRelated = await fileSearch(fileName);
-    if (maybeRelated.length > 0) {
-      throw new Error(
-        `File not found: ${filePath}. Maybe you meant one of these files: ${maybeRelated}`
-      );
-    }
-
-    throw new Error(`File not found: ${filePath}`);
-  }
-
-  const text = fs.readFileSync(filePath, "utf8");
-
-  // Emit post-read non-blocking event with the full file content so listeners
-  // (e.g. indexers) always see the complete file regardless of any range slice.
-  if (context.Events) {
-    await context.Events.emitNonBlocking("file:post-read", {
-      filePath,
-      content: text,
-    });
-  }
-
-  const hasRange =
-    typeof fromLine === "number" || typeof toLine === "number";
-
-  if (!hasRange) {
-    return text;
-  }
-
-  // Build a ranged read with real, 1-based source line numbers.
-  const lines = text.split("\n");
-  const totalLines = lines.length;
-
-  const start = Math.max(1, typeof fromLine === "number" ? fromLine : 1);
-  const end = Math.min(
-    totalLines,
-    typeof toLine === "number" ? toLine : totalLines
-  );
-
-  if (start > end) {
-    throw new Error(
-      `Invalid line range for ${filePath}: fromLine (${start}) is greater than toLine (${end}). File has ${totalLines} lines.`
-    );
-  }
-
-  const numbered = [];
-  for (let i = start; i <= end; i++) {
-    numbered.push(`${i}: ${lines[i - 1]}`);
-  }
-
-  return numbered.join("\n");
-}

package/src/agents/tools/replyToParent.ts

@@ -1,123 +0,0 @@
-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");
-}
-
-/**
- * Resolve the parent taskId for the calling agent.
- *
- * Order of resolution:
- *  1. `_ctx.parentTaskId` if the caller carries it directly
- *  2. `_ctx.caller.parentTaskId` if the agent instance exposes it
- *  3. The `parentTaskId` field of the caller's own metadata.json (looked up by
- *     `_ctx.taskId`)
- */
-function resolveParentTaskId(ctx?: ToolCallContext): string | undefined {
-  if (!ctx) return undefined;
-
-  if (ctx.parentTaskId) return ctx.parentTaskId as string;
-  const callerParent = (ctx.caller as any)?.parentTaskId;
-  if (callerParent) return callerParent as string;
-
-  // Fall back to reading our own metadata.json for the parentTaskId field.
-  const ownTaskId = ctx.taskId ?? (ctx.caller as any)?.currentTaskId;
-  if (!ownTaskId) return undefined;
-
-  try {
-    const metaPath = path.join(agentsDir(), ownTaskId, "metadata.json");
-    if (fs.existsSync(metaPath)) {
-      const meta = JSON.parse(fs.readFileSync(metaPath, "utf8"));
-      return meta.parentTaskId;
-    }
-  } catch {
-    // ignore — no parent metadata available
-  }
-  return undefined;
-}
-
-/**
- * Send a message back to the parent agent that spawned this task.
- *
- * This is a self-referential tool: it uses the per-call context (`_ctx`) to
- * discover which agent is calling it and which parent task spawned it, then
- * appends the message to the parent's `input.txt` so the parent picks it up on
- * its next sync cycle.
- *
- * `_ctx` is threaded in by ToolsService.callTool as the LAST positional
- * argument. The agent effectively passes *itself* in via `_ctx.caller`.
- */
-export async function replyToParent(
-  message: string,
-  _ctx?: ToolCallContext
-): Promise<string> {
-  if (!message || !message.trim()) {
-    return "No message provided to replyToParent.";
-  }
-
-  const parentTaskId = resolveParentTaskId(_ctx);
-  if (!parentTaskId) {
-    return (
-      "No parent task found — this agent was not spawned with a parent taskId, " +
-      "so there is no one to reply to."
-    );
-  }
-
-  const parentDir = path.join(agentsDir(), parentTaskId);
-  const parentInputPath = path.join(parentDir, "input.txt");
-
-  if (!fs.existsSync(parentDir)) {
-    return `Parent task directory not found: ${parentDir}`;
-  }
-
-  const fromTaskId =
-    _ctx?.taskId ?? (_ctx?.caller as any)?.currentTaskId ?? "unknown";
-  const fromAgent = (_ctx?.caller as any)?.name ?? "child";
-
-  // Envelope with sender identity so the parent knows who is replying.
-  const envelope = `[from:${fromTaskId}] [agent:${fromAgent}] ${message}`;
-
-  try {
-    // Append rather than overwrite so we don't clobber other pending messages.
-    const existing = fs.existsSync(parentInputPath)
-      ? fs.readFileSync(parentInputPath, "utf8")
-      : "";
-    const next = existing && !existing.endsWith("\n")
-      ? `${existing}\n${envelope}\n`
-      : `${existing}${envelope}\n`;
-    fs.writeFileSync(parentInputPath, next, "utf8");
-  } catch (e: any) {
-    return `Failed to write to parent input.txt: ${e?.message ?? String(e)}`;
-  }
-
-  return `Sent message to parent task ${parentTaskId}.`;
-}
-
-export const replyToParentDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "replyToParent",
-    description:
-      "Send a message back to the parent agent that spawned this task. Use this " +
-      "to report progress, ask a question, or alert the parent to something. The " +
-      "message is delivered to the parent's input queue and picked up on its next " +
-      "sync cycle. Only works when this agent was spawned by another agent (i.e. " +
-      "it has a parent taskId).",
-    parameters: {
-      type: "object",
-      positional: true,
-      usesContext: true,
-      properties: {
-        message: {
-          type: "string",
-          description: "The message to send back to the parent agent",
-        },
-      },
-      required: ["message"],
-    },
-  },
-};

package/src/agents/tools/runGenerate.ts

@@ -1,210 +0,0 @@
-import { Tool } from "../../clients/types";
-import { GenerationSource } from "../../types";
-import { generate, GenerateOptions, buildWaves } from "../../generate";
-
-export interface RunGenerateParams {
-  /**
-   * In-memory generation sources defining the pipeline. When provided, these
-   * are used INSTEAD of the sources in .knowhow/knowhow.json. Each source can
-   * declare `dependsOn` for explicit ordering, an `agent` for agent-driven
-   * generation, and input/output/prompt for the work itself.
-   */
-  sources?: GenerationSource[];
-  /** Only run sources whose `name` matches exactly this value (config mode). */
-  name?: string;
-  /** Only run sources whose name/input/output contains this substring. */
-  filter?: string;
-  /** Skip hash checks and regenerate all matching sources regardless of changes. */
-  force?: boolean;
-  /** Max sources to run in parallel within a dependency wave. Default: 3. */
-  concurrency?: number;
-  /**
-   * When true, agent-driven sources create .knowhow/processes/agents/<taskId>/
-   * so they appear in `knowhow agents list`.
-   */
-  syncFs?: boolean;
-  /**
-   * When true, agent-driven sources push their work to a remote Knowhow task
-   * (identified by the source's taskId).
-   */
-  syncRemote?: boolean;
-  /** When true, only compute and return the execution plan (waves) without running. */
-  planOnly?: boolean;
-  /** Per-call context injected by ToolsService.callTool. */
-  _ctx?: { caller?: any; taskId?: string; [key: string]: any };
-}
-
-/**
- * runGenerate — expose `knowhow generate` as an agent tool.
- *
- * This lets an agent orchestrate complex, multi-step pipelines at runtime
- * without needing them defined in the config. It supports:
- *   - `dependsOn` for explicit ordering (topological waves)
- *   - automatic I/O overlap detection (source B reading source A's output runs after A)
- *   - per-source `agent` for agent-driven generation (map/reduce fan-out)
- *   - concurrency control within each dependency wave
- *   - plain summarization/analysis sources (no agent)
- *
- * With `planOnly: true`, it returns the computed wave plan so the agent can
- * inspect ordering/parallelism before committing to a run.
- */
-export async function runGenerate(params: RunGenerateParams): Promise<string> {
-  const {
-    sources,
-    name,
-    filter,
-    force,
-    concurrency,
-    syncFs,
-    syncRemote,
-    planOnly,
-  } = params ?? {};
-
-  // Default filesystem sync ON for agent-driven sources so they show up in
-  // `knowhow agents list` and can be attached/tailed. Pass syncFs: false to opt out.
-  const effectiveSyncFs = syncFs !== false;
-
-  const options: GenerateOptions = {
-    sources,
-    name,
-    filter,
-    force,
-    concurrency,
-    syncFs: effectiveSyncFs,
-    syncRemote,
-  };
-
-  // Resolve the source set for planning output.
-  const effectiveSources = sources ?? [];
-
-  if (planOnly) {
-    if (effectiveSources.length === 0) {
-      return (
-        "planOnly requires in-memory `sources` to build a plan. " +
-        "Provide sources to see how they'd be grouped into dependency waves."
-      );
-    }
-    const filtered = effectiveSources.filter((s) => {
-      if (name) return s.name === name;
-      if (filter) {
-        const needle = filter.toLowerCase();
-        return [s.name, s.input, s.output]
-          .filter(Boolean)
-          .some((v) => v!.toLowerCase().includes(needle));
-      }
-      return true;
-    });
-    const waves = buildWaves(filtered);
-    const lines: string[] = [];
-    lines.push(
-      `📋 Generation Plan (concurrency: ${concurrency ?? 3}, ${filtered.length} sources, ${waves.length} wave${waves.length !== 1 ? "s" : ""})`
-    );
-    waves.forEach((wave, i) => {
-      lines.push(`\n┌─ Wave ${i + 1}/${waves.length} (${wave.length} in parallel)`);
-      for (const s of wave) {
-        const label = s.name || "(unnamed)";
-        const io = `${s.input || "-"} → ${s.output || "-"}`;
-        const agentPart = s.agent ? `  [agent: ${s.agent}]` : "";
-        lines.push(`│  • ${label}  ${io}${agentPart}`);
-      }
-      lines.push("└────────────────────────────────────────────────");
-    });
-    return lines.join("\n");
-  }
-
-  try {
-    await generate(options);
-  } catch (e: any) {
-    return `Generation failed: ${e?.message ?? String(e)}`;
-  }
-
-  const count = effectiveSources.length;
-  const mode = count > 0 ? `${count} in-memory source(s)` : "config sources";
-  return (
-    `Generation complete for ${mode}` +
-    (name ? ` (name="${name}")` : filter ? ` (filter="${filter}")` : "") +
-    `. Outputs written to their configured paths. ` +
-    `If agent-driven sources used syncFs, inspect them with \`knowhow agents list\`.`
-  );
-}
-
-export const runGenerateDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "runGenerate",
-    description:
-      "Run the `knowhow generate` pipeline. Accepts in-memory `sources` so you can define arbitrary " +
-      "task orchestration at runtime WITHOUT editing the config file. Supports dependency ordering via " +
-      "`dependsOn`, automatic I/O overlap detection (a source reading another's output runs after it), " +
-      "per-source `agent` for agent-driven generation (map/reduce fan-out — one agent per input), " +
-      "concurrency control within each dependency wave, and plain summarization/analysis sources. " +
-      "Use `planOnly: true` to preview how sources group into concurrent dependency waves before running. " +
-      "When `sources` is omitted, it runs the sources defined in .knowhow/knowhow.json (optionally scoped by name/filter).",
-    parameters: {
-      type: "object",
-      usesContext: true,
-      properties: {
-        sources: {
-          type: "array",
-          description:
-            "In-memory generation sources. Each item: { name?, input, output, prompt, agent?, model?, " +
-            "kind?, outputExt?, outputName?, dependsOn?: string[], syncFs?, maxTimeLimit?, maxSpendLimit? }. " +
-            "`input` is a glob or comma-separated file list; `output` is the target file/dir; `prompt` is the " +
-            "generation instruction; `agent` (optional) runs an agent per input instead of a summarization call; " +
-            "`dependsOn` lists names of sources that must finish first.",
-          items: {
-            type: "object",
-            properties: {
-              name: { type: "string" },
-              input: { type: "string" },
-              output: { type: "string" },
-              prompt: { type: "string" },
-              agent: { type: "string" },
-              model: { type: "string" },
-              kind: { type: "string" },
-              outputExt: { type: "string" },
-              outputName: { type: "string" },
-              dependsOn: { type: "array", items: { type: "string" } },
-              syncFs: { type: "boolean" },
-              maxTimeLimit: { type: "number" },
-              maxSpendLimit: { type: "number" },
-            },
-          },
-        },
-        name: {
-          type: "string",
-          description: "Only run sources whose `name` matches exactly (config mode).",
-        },
-        filter: {
-          type: "string",
-          description: "Only run sources whose name/input/output contains this substring.",
-        },
-        force: {
-          type: "boolean",
-          description: "Skip hash checks and regenerate all matching sources.",
-        },
-        concurrency: {
-          type: "number",
-          description: "Max sources to run in parallel within a dependency wave. Default: 3.",
-        },
-        syncFs: {
-          type: "boolean",
-          description:
-            "For agent-driven sources, create .knowhow/processes/agents/<taskId>/ so they appear in `knowhow agents list`. " +
-            "Defaults to true (enabled). Pass false to opt out.",
-        },
-        syncRemote: {
-          type: "boolean",
-          description:
-            "For agent-driven sources, push their work to a remote Knowhow task (identified by the source's taskId), " +
-            "in addition to fs sync.",
-        },
-        planOnly: {
-          type: "boolean",
-          description: "Return the wave execution plan without running anything (requires `sources`).",
-        },
-      },
-      required: [],
-    },
-  },
-};

package/src/agents/tools/scanFile.ts

@@ -1,16 +0,0 @@
-import * as fs from "fs";
-
-// Tool to scan a file from line A to line B
-export function scanFile(
-  filePath: string,
-  startLine: number,
-  endLine: number
-): string {
-  const fileContent = fs.readFileSync(filePath, "utf8");
-  const lines = fileContent.split("\n");
-  const start = Math.max(0, startLine - 5);
-  const end = Math.min(lines.length, endLine + 5);
-  return JSON.stringify(
-    lines.map((line, index) => [index + 1, line]).slice(start, end)
-  );
-}

package/src/agents/tools/sendAgentMessage.ts

@@ -1,139 +0,0 @@
-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");
-}
-
-/**
- * Append a line to a task's input.txt without clobbering other pending
- * messages. AgentSyncFs.checkForChanges reads input.txt and turns non-slash
- * content into a pending user message on the target agent (and honors /poke to
- * interrupt).
- */
-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");
-}
-
-export interface SendAgentMessageParams {
-  /** The taskId of the agent to send a message to. */
-  taskId: string;
-  /** The message body to deliver. */
-  message: string;
-  /**
-   * Optional sender identifier. If omitted, resolved from the calling agent's
-   * own taskId via _ctx. Included as a `[from:...]` envelope so the recipient
-   * knows who to reply to.
-   */
-  from?: string;
-  /**
-   * When true, deliver as a `/poke` (interrupts the recipient's current step)
-   * rather than a queued user message. Default false.
-   */
-  poke?: boolean;
-  _ctx?: ToolCallContext;
-}
-
-/**
- * Send a message to another running agent (a child, a peer, or the parent) by
- * appending it to that agent's input.txt. This is the "down/lateral edge" of
- * agent-to-agent communication — the complement to replyToParent (the up edge).
- *
- * The recipient's AgentSyncFs picks up the message on its next sync cycle and
- * adds it as a pending user message. If `poke` is true, it is delivered as a
- * `/poke` command which interrupts the recipient's current step.
- *
- * Self-referential: the sender identity is resolved from `_ctx` (the calling
- * agent) when `from` isn't supplied.
- */
-export async function sendAgentMessage(
-  params: SendAgentMessageParams
-): Promise<string> {
-  const { taskId, message, from, poke = false, _ctx } = params;
-
-  if (!taskId) {
-    return "sendAgentMessage: taskId is required.";
-  }
-  if (!message || !message.trim()) {
-    return "sendAgentMessage: message is required.";
-  }
-
-  const targetDir = path.join(agentsDir(), taskId);
-  const inputPath = path.join(targetDir, "input.txt");
-
-  if (!fs.existsSync(targetDir)) {
-    return `sendAgentMessage: target task directory not found: ${targetDir}`;
-  }
-
-  const fromId =
-    from ??
-    _ctx?.taskId ??
-    (_ctx?.caller as any)?.currentTaskId ??
-    "unknown";
-  const fromAgent = (_ctx?.caller as any)?.name;
-  const fromLabel = fromAgent ? `${fromId}/${fromAgent}` : fromId;
-
-  try {
-    if (poke) {
-      // /poke [message] — interrupts the recipient's current step.
-      appendToInput(inputPath, `/poke [from:${fromLabel}] ${message}`);
-    } else {
-      appendToInput(inputPath, `[from:${fromLabel}] ${message}`);
-    }
-  } catch (e: any) {
-    return `sendAgentMessage: failed to write to ${inputPath}: ${
-      e?.message ?? String(e)
-    }`;
-  }
-
-  return `Sent message to task ${taskId}${poke ? " (as /poke)" : ""}.`;
-}
-
-export const sendAgentMessageDefinition: Tool = {
-  type: "function",
-  function: {
-    name: "sendAgentMessage",
-    description:
-      "Send a message to another running agent (a child you spawned, a peer, or your parent) by " +
-      "appending it to that agent's input queue. The recipient picks it up on its next sync cycle " +
-      "as a user message. This is the down/lateral communication edge (complement to replyToParent). " +
-      "Set poke:true to interrupt the recipient's current step (delivered as /poke). Your sender " +
-      "identity is attached automatically so the recipient can reply back to you.",
-    parameters: {
-      type: "object",
-      positional: false,
-      usesContext: true,
-      properties: {
-        taskId: {
-          type: "string",
-          description: "The taskId of the agent to send the message to.",
-        },
-        message: {
-          type: "string",
-          description: "The message to deliver to the recipient agent.",
-        },
-        from: {
-          type: "string",
-          description:
-            "Optional sender id. Defaults to the calling agent's own taskId.",
-        },
-        poke: {
-          type: "boolean",
-          description:
-            "When true, deliver as a /poke that interrupts the recipient's current step. Default false.",
-        },
-      },
-      required: ["taskId", "message"],
-    },
-  },
-};