@aigne/ash 0.0.1

package/src/ai-dev-loop/meta-tools.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect } from "vitest";
+import {
+  ashRunToolDef,
+  ashValidateToolDef,
+  ashExplainErrorToolDef,
+  executeMetaTool,
+} from "./meta-tools.js";
+import type { WorldInterface, JobLogger } from "../compiler.js";
+
+function makeCtx() {
+  return {
+    world: {
+      read: () => [],
+      write: () => {},
+      publish: () => {},
+    } as WorldInterface,
+    caps: new Set(["*"]),
+    logger: { log() {} } as JobLogger,
+  };
+}
+
+describe("Meta Tools", () => {
+  // ── Tool Definitions ───────────────────────────────────
+
+  it("ash.run tool definition has correct inputSchema", () => {
+    expect(ashRunToolDef.name).toBe("ash_run");
+    expect(ashRunToolDef.parameters).toBeDefined();
+    const params = ashRunToolDef.parameters as any;
+    expect(params.properties.script).toBeDefined();
+    expect(params.properties.mode).toBeDefined();
+  });
+
+  it("ash.validate tool definition has correct inputSchema", () => {
+    expect(ashValidateToolDef.name).toBe("ash_validate");
+    const params = ashValidateToolDef.parameters as any;
+    expect(params.properties.script).toBeDefined();
+  });
+
+  it("ash.explain_error tool definition has correct inputSchema", () => {
+    expect(ashExplainErrorToolDef.name).toBe("ash_explain_error");
+    const params = ashExplainErrorToolDef.parameters as any;
+    expect(params.properties.error).toBeDefined();
+  });
+
+  // ── ash.run execution ──────────────────────────────────
+
+  it("ash.run execution with valid script → AshRunResult", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_run", {
+      script: 'job "test" { find /users }',
+      mode: "dry-run",
+    }, ctx);
+    expect(result).toBeDefined();
+    expect(result.status).toBeDefined();
+  });
+
+  it("ash.run default mode is dry-run", async () => {
+    const ctx = makeCtx();
+    // No mode specified → should default to dry-run
+    const result = await executeMetaTool("ash_run", {
+      script: 'output "hello"',
+    }, ctx);
+    expect(result).toBeDefined();
+  });
+
+  // ── ash.validate execution ─────────────────────────────
+
+  it("ash.validate execution with valid script → ParseError[]", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_validate", {
+      script: 'job "test" { find /users }',
+    }, ctx);
+    expect(Array.isArray(result)).toBe(true);
+    expect(result).toHaveLength(0);
+  });
+
+  // ── ash.explain_error ──────────────────────────────────
+
+  it("ash.explain_error with IntentDenied → human-readable explanation + suggestion", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_explain_error", {
+      error: { kind: "IntentDenied", invariant: "INV-2", message: "Action not allowed", suggestion: "Use dry-run" },
+    }, ctx);
+    expect(result.explanation).toContain("IntentDenied");
+    expect(result.suggestion).toBeDefined();
+  });
+
+  it("ash.explain_error with ToolNotFound → lists available tools", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_explain_error", {
+      error: { kind: "ToolNotFound", name: "foo", available: ["find", "where"], message: "not found" },
+    }, ctx);
+    expect(result.explanation).toContain("ToolNotFound");
+  });
+
+  it("ash.explain_error with non-AshTypedError → generic explanation", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_explain_error", {
+      error: "some random string",
+    }, ctx);
+    expect(result.explanation).toBeDefined();
+  });
+
+  // ── Bad Path ───────────────────────────────────────────
+
+  it("ash.run with missing script field → validation error", async () => {
+    const ctx = makeCtx();
+    await expect(executeMetaTool("ash_run", {}, ctx)).rejects.toThrow(/script/);
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("ash.run with no env → uses empty env", async () => {
+    const ctx = makeCtx();
+    const result = await executeMetaTool("ash_run", {
+      script: 'output "hello"',
+    }, ctx);
+    expect(result).toBeDefined();
+  });
+});

package/src/ai-dev-loop/meta-tools.ts

@@ -0,0 +1,142 @@
+/**
+ * Meta Tools — LLM-callable tool definitions for ASH AI Dev Loop.
+ *
+ * These tools are Proc-internal, not registered in Discovery.
+ */
+
+// Tool definition type inline (avoid circular dependency with kernel)
+interface LLMToolDef {
+  name: string;
+  description?: string;
+  parameters?: unknown;
+}
+import type { JobContext } from "../compiler.js";
+import { runStructured } from "./structured-runner.js";
+import { ashValidate } from "./ash-validate.js";
+import { isAshTypedError } from "./ash-typed-error.js";
+
+export const ashRunToolDef: LLMToolDef = {
+  name: "ash_run",
+  description: "Execute an ASH script. Default mode is dry-run (no side effects).",
+  parameters: {
+    type: "object",
+    properties: {
+      script: { type: "string", description: "ASH script source code" },
+      mode: { type: "string", enum: ["dry-run", "live"], description: "Execution mode. Default: dry-run" },
+      timeout_ms: { type: "number", description: "Timeout in milliseconds. Default: 30000" },
+    },
+    required: ["script"],
+  },
+};
+
+export const ashValidateToolDef: LLMToolDef = {
+  name: "ash_validate",
+  description: "Validate an ASH script for syntax and type errors without executing it.",
+  parameters: {
+    type: "object",
+    properties: {
+      script: { type: "string", description: "ASH script source code to validate" },
+    },
+    required: ["script"],
+  },
+};
+
+export const ashExplainErrorToolDef: LLMToolDef = {
+  name: "ash_explain_error",
+  description: "Get a human-readable explanation of an ASH error with repair suggestions.",
+  parameters: {
+    type: "object",
+    properties: {
+      error: { description: "The AshTypedError object to explain" },
+    },
+    required: ["error"],
+  },
+};
+
+export const META_TOOL_DEFS = [ashRunToolDef, ashValidateToolDef, ashExplainErrorToolDef];
+
+/**
+ * Execute a meta tool by name.
+ */
+export async function executeMetaTool(
+  name: string,
+  args: Record<string, unknown>,
+  ctx: JobContext,
+): Promise<any> {
+  switch (name) {
+    case "ash_run": {
+      if (!args.script || typeof args.script !== "string") {
+        throw new Error("ash_run: script field is required and must be a string");
+      }
+      return runStructured(args.script as string, ctx, {
+        mode: (args.mode as "dry-run" | "live") ?? "dry-run",
+        timeout_ms: (args.timeout_ms as number) ?? 30000,
+      });
+    }
+
+    case "ash_validate": {
+      if (!args.script || typeof args.script !== "string") {
+        throw new Error("ash_validate: script field is required and must be a string");
+      }
+      return ashValidate(args.script as string);
+    }
+
+    case "ash_explain_error": {
+      const error = args.error;
+      if (isAshTypedError(error)) {
+        return explainTypedError(error);
+      }
+      return { explanation: `Unknown error: ${JSON.stringify(error)}`, suggestion: "Check the error details." };
+    }
+
+    default:
+      throw new Error(`Unknown meta tool: ${name}`);
+  }
+}
+
+function explainTypedError(error: any): { explanation: string; suggestion?: string } {
+  switch (error.kind) {
+    case "IntentDenied":
+      return {
+        explanation: `IntentDenied: ${error.message}. Violated invariant: ${error.invariant}.`,
+        suggestion: error.suggestion ?? "Check the action permissions.",
+      };
+    case "CapabilityMissing":
+      return {
+        explanation: `CapabilityMissing: Required capability "${error.capability}" is not available.`,
+        suggestion: "Request the capability or use a different approach.",
+      };
+    case "ToolNotFound":
+      return {
+        explanation: `ToolNotFound: Tool "${error.name}" not found. Available: [${error.available?.join(", ")}].`,
+        suggestion: "Use one of the available tools.",
+      };
+    case "ValidationFailed":
+      return {
+        explanation: `ValidationFailed: Field "${error.field}" expected ${error.expected}, got ${error.got}.`,
+        suggestion: "Fix the field value to match the expected type.",
+      };
+    case "BudgetExceeded":
+      return {
+        explanation: `BudgetExceeded: Device "${error.device}" used ${error.used}/${error.limit}.`,
+        suggestion: "Reduce token usage or wait for budget reset.",
+      };
+    case "Timeout":
+      return {
+        explanation: `Timeout: Step "${error.step}" exceeded ${error.limit_ms}ms limit.`,
+        suggestion: "Simplify the query or increase the timeout.",
+      };
+    case "ParseError":
+      return {
+        explanation: `ParseError: ${error.message}${error.line ? ` at line ${error.line}` : ""}.`,
+        suggestion: "Fix the syntax error in the ASH script.",
+      };
+    case "RuntimeError":
+      return {
+        explanation: `RuntimeError: ${error.message}.`,
+        suggestion: "Check the runtime context and data.",
+      };
+    default:
+      return { explanation: `Error: ${error.message ?? JSON.stringify(error)}` };
+  }
+}

package/src/ai-dev-loop/structured-runner.test.ts

@@ -0,0 +1,159 @@
+import { describe, it, expect } from "vitest";
+import { runStructured } from "./structured-runner.js";
+import type { WorldInterface, JobLogger } from "../compiler.js";
+import { isAshRunSuccess, isAshRunFailure } from "./ash-run-result.js";
+
+function makeWorld(data: Record<string, unknown[]> = {}): WorldInterface & {
+  written: Record<string, unknown[]>;
+  published: Record<string, unknown[]>;
+} {
+  const written: Record<string, unknown[]> = {};
+  const published: Record<string, unknown[]> = {};
+  return {
+    read(path: string) { return data[path] ?? []; },
+    write(path: string, records: unknown[]) { written[path] = records; },
+    publish(topic: string, records: unknown[]) { published[topic] = records; },
+    written,
+    published,
+  };
+}
+
+function makeLogger(): JobLogger {
+  return { log() {} };
+}
+
+function makeCtx(data: Record<string, unknown[]> = {}) {
+  return {
+    world: makeWorld(data),
+    caps: new Set(["*"]),
+    logger: makeLogger(),
+  };
+}
+
+describe("Structured Runner", () => {
+  // ── Happy Path ─────────────────────────────────────────
+
+  it("run valid script → AshRunSuccess with correct step count", async () => {
+    const ctx = makeCtx({ "/users": [{ name: "Alice" }, { name: "Bob" }] });
+    const result = await runStructured('job "test" { find /users }', ctx);
+    expect(isAshRunSuccess(result)).toBe(true);
+    if (isAshRunSuccess(result)) {
+      expect(result.steps.length).toBeGreaterThanOrEqual(1);
+    }
+  });
+
+  it("run script with find + where + save → 3 steps in result", async () => {
+    const ctx = makeCtx({ "/users": [{ name: "Alice", age: 30 }, { name: "Bob", age: 20 }] });
+    const result = await runStructured(
+      'job "test" { find /users | where age > 25 | save /seniors }',
+      ctx,
+    );
+    expect(isAshRunSuccess(result)).toBe(true);
+    if (isAshRunSuccess(result)) {
+      expect(result.steps).toHaveLength(3);
+    }
+  });
+
+  it("each step has correct command name extracted", async () => {
+    const ctx = makeCtx({ "/data": [{ x: 1 }] });
+    const result = await runStructured('job "test" { find /data | map x }', ctx);
+    if (isAshRunSuccess(result)) {
+      expect(result.steps[0].command).toBe("find");
+      expect(result.steps[1].command).toBe("map");
+    }
+  });
+
+  it("duration_ms is positive number", async () => {
+    const ctx = makeCtx({ "/data": [{ x: 1 }] });
+    const result = await runStructured('job "test" { find /data }', ctx);
+    expect(result.duration_ms).toBeGreaterThanOrEqual(0);
+  });
+
+  // ── Bad Path ───────────────────────────────────────────
+
+  it("run script with syntax error → AshRunFailure with ParseError", async () => {
+    const ctx = makeCtx();
+    const result = await runStructured('job "test" { find }', ctx);
+    // find without path is a syntax error
+    expect(isAshRunFailure(result)).toBe(true);
+    if (isAshRunFailure(result)) {
+      expect(result.failedAt.kind).toBe("ParseError");
+    }
+  });
+
+  // ── Edge Cases ─────────────────────────────────────────
+
+  it("empty script → AshRunSuccess with 0 steps", async () => {
+    const ctx = makeCtx();
+    const result = await runStructured("", ctx);
+    expect(isAshRunSuccess(result)).toBe(true);
+    if (isAshRunSuccess(result)) {
+      expect(result.steps).toHaveLength(0);
+    }
+  });
+
+  it("script with only output → AshRunSuccess", async () => {
+    const ctx = makeCtx();
+    const result = await runStructured('output "hello"', ctx);
+    expect(isAshRunSuccess(result)).toBe(true);
+  });
+
+  // ── Security ───────────────────────────────────────────
+
+  it("raw error messages don't leak internal paths", async () => {
+    const ctx = makeCtx();
+    const result = await runStructured('job "test" { find }', ctx);
+    if (isAshRunFailure(result)) {
+      expect(result.failedAt.message).not.toContain("/Users/");
+      expect(result.failedAt.message).not.toContain("node_modules");
+    }
+  });
+
+  // ── timeout_ms ─────────────────────────────────────────
+
+  it("timeout_ms prevents side effects after timeout (cooperative cancellation)", async () => {
+    // Create a world where read takes 50ms, then save happens after
+    // If timeout fires at 10ms, save should NOT execute
+    const slowWorld: WorldInterface & { written: Record<string, unknown[]>; published: Record<string, unknown[]> } = {
+      async read() {
+        await new Promise((r) => setTimeout(r, 50));
+        return [{ x: 1 }];
+      },
+      write(path: string, records: unknown[]) { slowWorld.written[path] = records; },
+      publish(topic: string, records: unknown[]) { slowWorld.published[topic] = records; },
+      written: {},
+      published: {},
+    };
+    const ctx = { world: slowWorld, caps: new Set(["*"]), logger: makeLogger() };
+    const result = await runStructured(
+      'job "test" { find /data | save /output }',
+      ctx,
+      { timeout_ms: 10 },
+    );
+    expect(isAshRunFailure(result)).toBe(true);
+    // After timeout, the write side effect should NOT have happened
+    // Wait a bit to ensure any lingering execution would have completed
+    await new Promise((r) => setTimeout(r, 200));
+    expect(slowWorld.written["/output"]).toBeUndefined();
+  });
+
+  it("timeout_ms triggers error when execution exceeds limit", async () => {
+    // Create a world with a slow read that takes ~200ms
+    const slowWorld: WorldInterface & { written: Record<string, unknown[]>; published: Record<string, unknown[]> } = {
+      async read() {
+        await new Promise((r) => setTimeout(r, 200));
+        return [{ x: 1 }];
+      },
+      write(path: string, records: unknown[]) { slowWorld.written[path] = records; },
+      publish(topic: string, records: unknown[]) { slowWorld.published[topic] = records; },
+      written: {},
+      published: {},
+    };
+    const ctx = { world: slowWorld, caps: new Set(["*"]), logger: makeLogger() };
+    const result = await runStructured('job "test" { find /data }', ctx, { timeout_ms: 10 });
+    expect(isAshRunFailure(result)).toBe(true);
+    if (isAshRunFailure(result)) {
+      expect(result.failedAt.message).toContain("imeout");
+    }
+  });
+});

package/src/ai-dev-loop/structured-runner.ts

@@ -0,0 +1,209 @@
+/**
+ * Structured Runner — Wraps ASH compileSource() + execute() with step tracking.
+ *
+ * Produces AshRunResult from raw ASH execution.
+ */
+
+import { compileSource, type JobContext, type WorldInterface } from "../compiler.js";
+import type { AshRunResult, AshStepResult } from "./ash-run-result.js";
+import { fromJobError } from "./ash-typed-error.js";
+
+/**
+ * Wraps a WorldInterface to intercept all writes in dry-run mode.
+ * Reads pass through normally; write/publish are silently absorbed.
+ */
+function createDryRunWorld(real: WorldInterface): WorldInterface {
+  return {
+    read: (path, query) => real.read(path, query),
+    write: (_path, _data) => { /* no-op in dry-run */ },
+    publish: (_topic, _data) => { /* no-op in dry-run */ },
+  };
+}
+
+/**
+ * Wraps a WorldInterface to check an AbortSignal before every operation.
+ * Once aborted, all operations throw immediately — preventing side effects
+ * from continuing after a timeout.
+ */
+function createCancellableWorld(real: WorldInterface, signal: AbortSignal): WorldInterface {
+  function checkAborted() {
+    if (signal.aborted) throw new Error("Execution cancelled: timeout");
+  }
+  return {
+    read(path, query) {
+      checkAborted();
+      return real.read(path, query);
+    },
+    write(path, data) {
+      checkAborted();
+      real.write(path, data);
+    },
+    publish(topic, data) {
+      checkAborted();
+      real.publish(topic, data);
+    },
+    ...(real.exec ? {
+      exec(path: string, input: unknown[], params?: Record<string, unknown>) {
+        checkAborted();
+        return real.exec!(path, input, params);
+      },
+    } : {}),
+    ...(real.input ? {
+      input(prompt: string) {
+        checkAborted();
+        return real.input!(prompt);
+      },
+    } : {}),
+  };
+}
+
+export interface RunOptions {
+  mode?: "dry-run" | "live";
+  timeout_ms?: number;
+}
+
+export async function runStructured(
+  source: string,
+  ctx: JobContext,
+  options?: RunOptions,
+): Promise<AshRunResult> {
+  const startTime = performance.now();
+
+  // Empty source → success with no steps
+  if (!source.trim()) {
+    return {
+      status: "ok",
+      steps: [],
+      output: [],
+      duration_ms: Math.round(performance.now() - startTime),
+    };
+  }
+
+  // Compile
+  const compileResult = compileSource(source);
+
+  // Check for compile errors
+  const errors = compileResult.diagnostics.filter((d) => d.severity !== "warning");
+  if (errors.length > 0 || !compileResult.program) {
+    const firstError = errors[0] ?? compileResult.diagnostics[0];
+    return {
+      status: "error",
+      steps: [],
+      failedAt: {
+        kind: "ParseError",
+        line: firstError?.line,
+        message: firstError?.message ?? "Compilation failed",
+      },
+      duration_ms: Math.round(performance.now() - startTime),
+    };
+  }
+
+  const program = compileResult.program;
+  const allSteps: AshStepResult[] = [];
+
+  // Apply dry-run world wrapper if in dry-run mode
+  const mode = options?.mode ?? "live";
+  let execCtx: JobContext = mode === "dry-run"
+    ? { ...ctx, world: createDryRunWorld(ctx.world) }
+    : ctx;
+
+  // Wrap execution with timeout if specified
+  const timeoutMs = options?.timeout_ms;
+  if (timeoutMs != null && timeoutMs > 0) {
+    const controller = new AbortController();
+    // Wrap world with cancellation guard so operations throw after abort
+    execCtx = { ...execCtx, world: createCancellableWorld(execCtx.world, controller.signal) };
+
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    return Promise.race([
+      executeUnits(program, execCtx, allSteps, startTime),
+      new Promise<AshRunResult>((_, reject) => {
+        controller.signal.addEventListener("abort", () =>
+          reject(new Error(`Timeout: execution exceeded ${timeoutMs}ms`)),
+        );
+      }),
+    ]).catch((err: any) => ({
+      status: "error" as const,
+      steps: allSteps,
+      failedAt: fromJobError(err.message ?? String(err)),
+      duration_ms: Math.round(performance.now() - startTime),
+    })).finally(() => clearTimeout(timer));
+  }
+
+  return executeUnits(program, execCtx, allSteps, startTime);
+}
+
+async function executeUnits(
+  program: NonNullable<ReturnType<typeof compileSource>["program"]>,
+  execCtx: JobContext,
+  allSteps: AshStepResult[],
+  startTime: number,
+): Promise<AshRunResult> {
+  // Execute all units (skip route-target-only jobs)
+  for (const unit of program.units) {
+    if (unit.kind === "output") {
+      await unit.execute(execCtx);
+      continue;
+    }
+
+    // Skip route-target-only jobs — they execute only when dispatched by route
+    if (program.routeTargets?.has(unit.name)) continue;
+
+    // Job execution
+    try {
+      const jobResult = await unit.execute(execCtx);
+
+      // Extract step metrics from JobReport if available
+      const report = jobResult as any;
+      if (report.stages && Array.isArray(report.stages)) {
+        for (const stage of report.stages) {
+          allSteps.push({
+            step: stage.index ?? allSteps.length,
+            command: stage.name ?? "unknown",
+            status: stage.error ? "error" : "ok",
+            duration_ms: stage.durationMs ?? 0,
+            output: [],
+          });
+        }
+      } else {
+        // Fallback: single step from job
+        allSteps.push({
+          step: allSteps.length,
+          command: unit.name ?? "job",
+          status: jobResult.status === "ok" ? "ok" : "error",
+          duration_ms: 0,
+        });
+      }
+
+      if (jobResult.status === "error" && jobResult.errors.length > 0) {
+        return {
+          status: "error",
+          steps: allSteps,
+          failedAt: fromJobError(jobResult.errors[0]),
+          duration_ms: Math.round(performance.now() - startTime),
+        };
+      }
+    } catch (err: any) {
+      allSteps.push({
+        step: allSteps.length,
+        command: unit.name ?? "job",
+        status: "error",
+        duration_ms: 0,
+      });
+
+      return {
+        status: "error",
+        steps: allSteps,
+        failedAt: fromJobError(err.message ?? String(err)),
+        duration_ms: Math.round(performance.now() - startTime),
+      };
+    }
+  }
+
+  return {
+    status: "ok",
+    steps: allSteps,
+    output: [],
+    duration_ms: Math.round(performance.now() - startTime),
+  };
+}