Tools

/**
 * A tool that runs on the user's machine. `I` is the validated input type.
 *
 * - **read / action** tools implement `execute` and run on arrival.
 * - **mutate** tools set `mutates: true` and implement BOTH `plan` (the dry-run → {@link Proposal})
 *   and `execute` (the apply). The runtime calls `plan` on a normal dispatch and `execute` only when
 *   the server re-dispatches in apply mode after approval.
 */
export interface LocalTool<I = unknown> {
	name: string;
	description: string;
	/** Zod schema for the input; the runtime validates the dispatched input against it. */
	input: z.ZodType<I>;
	/** True for tools that change the disk — gated behind propose/apply. */
	mutates?: boolean;
	/** Dry-run for a mutating tool: compute the proposal without touching disk. */
	plan?: (input: I, ctx: LocalToolContext) => Promise<Proposal> | Proposal;
	/** Run the tool (the apply, for a mutating tool). Returns JSON-serialisable output. */
	execute: (input: I, ctx: LocalToolContext) => Promise<unknown> | unknown;
}

import { defineLocalTool } from "@tikab-interactive/fusion-ai-host";
import { rename } from "node:fs/promises";
import { z } from "zod";
 
export const renameInPlace = defineLocalTool({
  name: "rename_in_place",
  description: "Rename a file within the same folder.",
  input: z.object({ path: z.string(), to: z.string() }),
  mutates: true,
  plan: async ({ path, to }, ctx) => ({
    summary: `Rename ${path} → ${to}`,
    paths: [await ctx.resolvePath(path), await ctx.resolvePath(to)],
  }),
  execute: async ({ path, to }, ctx) => {
    const from = await ctx.resolvePath(path);
    const dest = await ctx.resolvePath(to);
    await rename(from, dest);
    return { from, to: dest };
  },
});

/** The context a tool's handlers receive: the host's scope + a scope-checked path resolver. */
export interface LocalToolContext {
	/** The allowed root directories this host exposes. */
	roots: string[];
	/** Resolve a user-supplied path inside the configured roots (throws if it escapes). */
	resolvePath: (p: string) => Promise<string>;
}

/**
 * A proposal a mutating tool returns from its dry-run (`plan`). It describes the exact effect —
 * resolved paths, a human-readable diff where one applies, bytes affected — WITHOUT touching disk,
 * so a human can approve it before the apply is dispatched.
 */
export interface Proposal {
	/** One-line summary, e.g. "Overwrite report.txt (1.2 kB → 1.4 kB)". */
	summary: string;
	/** A unified-ish `+/-` diff or preview, where the change has one. */
	diff?: string;
	/** The absolute path(s) the apply will touch. */
	paths: string[];
	/** Bytes written / removed / copied, when meaningful. */
	bytes?: number;
}