@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/packages/local-runtime/src/manifest-runs.ts

@@ -0,0 +1,204 @@
+import type { InvocationSummaryV1 } from "@zaip-ai/costs";
+import type { RunProjection } from "@zaip-ai/dashboard-operations/contracts";
+
+/** Merge authoritative invocation manifests without discarding lifecycle timing. */
+export function mergeManifestRuns(
+  legacyRuns: readonly RunProjection[],
+  summaries: readonly InvocationSummaryV1[],
+): RunProjection[] {
+  const runs = new Map<string, RunProjection>(legacyRuns.map((run) => [run.id, run]));
+  for (const run of summaries.map((summary) => manifestRun(summary, summaries))) {
+    const legacy = runs.get(run.id);
+    const preserveObservedSourceTiming =
+      run.source_duration_ms === null &&
+      legacy !== undefined &&
+      legacy.source_duration_ms !== null &&
+      (legacy.source_duration_ms ?? 0) > 0 &&
+      legacy.duration_ms !== null;
+    const preserveLegacyDuration =
+      run.source_duration_ms === null &&
+      legacy !== undefined &&
+      (legacy.source_duration_ms === null || legacy.source_duration_ms === 0) &&
+      legacy.duration_ms !== null;
+    runs.set(
+      run.id,
+      preserveObservedSourceTiming
+        ? { ...legacy, ...run, ...observedTiming(legacy) }
+        : preserveLegacyDuration
+          ? {
+              ...legacy,
+              ...run,
+              duration_ms: legacy.duration_ms,
+              source_duration_ms: null,
+              source_started_at: null,
+              source_finished_at: null,
+              capture_lag_ms: null,
+            }
+          : {
+              ...(legacy ?? {}),
+              ...run,
+              ...(legacy !== undefined && run.duration_ms === null
+                ? { started_at: legacy.started_at, finished_at: legacy.finished_at }
+                : {}),
+            },
+    );
+  }
+  return [...runs.values()];
+}
+
+function observedTiming(
+  run: RunProjection,
+): Pick<
+  RunProjection,
+  | "duration_ms"
+  | "duration_provenance"
+  | "estimation_basis"
+  | "source_duration_ms"
+  | "source_started_at"
+  | "source_finished_at"
+  | "capture_lag_ms"
+> {
+  return {
+    duration_ms: run.duration_ms,
+    ...(typeof run.source_duration_ms === "number"
+      ? { duration_provenance: "observed" as const }
+      : run.duration_provenance === undefined
+        ? {}
+        : { duration_provenance: run.duration_provenance }),
+    estimation_basis:
+      typeof run.source_duration_ms === "number" ? null : (run.estimation_basis ?? null),
+    source_duration_ms: run.source_duration_ms ?? null,
+    source_started_at: run.source_started_at ?? null,
+    source_finished_at: run.source_finished_at ?? null,
+    capture_lag_ms: run.capture_lag_ms ?? null,
+  };
+}
+
+/** Translate compact manifests to the immutable operations projection contract. */
+export function manifestRun(
+  summary: InvocationSummaryV1,
+  summaries: readonly InvocationSummaryV1[],
+): RunProjection {
+  const segments = Array.isArray(summary.usage_segments) ? summary.usage_segments : [];
+  const token = (key: "input" | "cached_input" | "output" | "reasoning" | "total") =>
+    segments.length === 0 || segments.some((segment) => !recordNumber(segment.tokens?.[key]))
+      ? null
+      : segments.reduce((total, segment) => total + (segment.tokens?.[key] ?? 0), 0);
+  const tokenTotal = summary.quantitative_metrics.tokens_total;
+  const usd = summary.quantitative_metrics.estimated_usd;
+  const brl = summary.quantitative_metrics.estimated_brl;
+  const metric = {
+    events: summary.source_event_count,
+    tokens: {
+      input: token("input"),
+      cached_input: token("cached_input"),
+      output: token("output"),
+      reasoning: token("reasoning"),
+      total: tokenTotal.known_sum,
+    },
+    cost: {
+      usd: summary.historical_cost?.estimated_usd ?? usd.known_sum,
+      brl: summary.historical_cost?.estimated_brl ?? brl.known_sum,
+    },
+    coverage: {
+      events: summary.source_event_count,
+      tokens: tokenTotal.complete,
+      usd: usd.complete,
+      brl: brl.complete,
+    },
+  };
+  const empty = {
+    ...metric,
+    events: 0,
+    tokens: { input: null, cached_input: null, output: null, reasoning: null, total: null },
+    cost: { usd: null, brl: null },
+    coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+  };
+  const execution = summary.phase === "execution" ? metric : empty;
+  const delegated = summary.invocation_kind === "delegated";
+  return {
+    id: summary.run_id,
+    artifact_path: `.agents/records/runs/${summary.run_id}`,
+    status: summary.status ?? "completed",
+    phase: summary.phase ?? "execution",
+    entrypoint: summary.task_id === null ? "conversation" : "task",
+    work_type: "new",
+    run_role: delegated ? ("subagent" as const) : ("orchestrator" as const),
+    run_kind: delegated ? ("subrun" as const) : ("run" as const),
+    run_purpose: manifestRunPurpose(summary.purpose, delegated),
+    requires_finalizer: false,
+    parent_run_id:
+      summaries.find(
+        (candidate) => candidate.agent_invocation_id === summary.parent_agent_invocation_id,
+      )?.run_id ?? null,
+    client: "codex",
+    agent: summary.zaip_agent ?? "unknown",
+    agent_name: summary.zaip_agent ?? "unknown",
+    provider: segments.find((segment) => typeof segment.provider === "string")?.provider ?? null,
+    model: segments.find((segment) => typeof segment.model === "string")?.model ?? "unknown",
+    reasoning_effort:
+      segments.find((segment) => typeof segment.reasoning_effort === "string")?.reasoning_effort ??
+      null,
+    effective_model: null,
+    effective_reasoning_effort: null,
+    effective_config_mixed: false,
+    service_tier:
+      segments.find((segment) => typeof segment.service_tier === "string")?.service_tier ?? null,
+    call_count: summary.llm_call_count,
+    terminal_call_count: summary.llm_call_count,
+    failed_call_count: summary.status === "failed" ? summary.llm_call_count : 0,
+    cancelled_call_count: summary.status === "cancelled" ? summary.llm_call_count : 0,
+    conversation_id: summary.agent_invocation_id,
+    execution_id: summary.execution_id,
+    task_id: summary.task_id,
+    spec_id: summary.spec_id,
+    prd_id: summary.prd_id,
+    change_id: summary.change_id,
+    started_at: summary.occurred_at,
+    finished_at: summary.status === null ? null : summary.occurred_at,
+    duration_ms: summary.time.duration_ms,
+    source_duration_ms: summary.time.duration_ms,
+    source_started_at: null,
+    source_finished_at: summary.time.source_latest_at,
+    pricing_segments: segments.map((segment) => ({
+      phase: "execution" as const,
+      provider: segment.provider,
+      model: segment.model,
+      service_tier: segment.service_tier,
+      input_tokens: segment.tokens?.input ?? null,
+      cached_input_tokens: segment.tokens?.cached_input ?? null,
+      output_tokens: segment.tokens?.output ?? null,
+      reasoning_tokens: segment.tokens?.reasoning ?? null,
+      total_tokens: segment.tokens?.total ?? null,
+    })),
+    usage: {
+      conversation: empty,
+      planning: empty,
+      execution,
+      total: metric,
+      new_work: metric,
+      rework: empty,
+    },
+  };
+}
+
+function manifestRunPurpose(
+  value: string | null,
+  delegated: boolean,
+): RunProjection["run_purpose"] {
+  if (
+    value === "intake" ||
+    value === "orchestration" ||
+    value === "execution" ||
+    value === "review" ||
+    value === "audit" ||
+    value === "finalization"
+  ) {
+    return value;
+  }
+  return delegated ? "execution" : "orchestration";
+}
+
+function recordNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}

package/templates/.agents/dashboard/packages/local-runtime/src/project-settings.test.ts

@@ -0,0 +1,92 @@
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { parseProjectConfig, parseYaml, WorkspaceFileSystem } from "@zaip-ai/core";
+import { afterEach, describe, expect, it } from "vitest";
+import { persistProjectSettings, readProjectSettings } from "./project-settings.js";
+
+const fixtures: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(fixtures.splice(0).map((path) => rm(path, { force: true, recursive: true })));
+});
+
+async function fixtureProject() {
+  const root = await mkdtemp(join(tmpdir(), "zaip-project-settings-"));
+  fixtures.push(root);
+  const configPath = join(root, ".agents", "config", "project.yaml");
+  await mkdir(join(root, ".agents", "config"), { recursive: true });
+  await writeFile(
+    configPath,
+    [
+      "schema_version: 1",
+      "zaip:",
+      "  enabled: true",
+      "project:",
+      "  id: fixture",
+      "  name: Fixture",
+      "  timezone: UTC",
+      "stack:",
+      "  id: typescript-hono-kysely",
+      "  overrides:",
+      "    database: postgres",
+      "clients:",
+      "  codex: true",
+      "  claude: false",
+      "tracking:",
+      "  enabled: true",
+      "  currency: BRL",
+      "  storage_mode: tracked_sanitized",
+      "",
+    ].join("\n"),
+    "utf8",
+  );
+  return { configPath, filesystem: new WorkspaceFileSystem(root) };
+}
+
+describe("project settings persistence", () => {
+  it("reads, validates and atomically persists the complete project config", async () => {
+    const { configPath, filesystem } = await fixtureProject();
+    const current = await readProjectSettings(filesystem);
+    const updated = await persistProjectSettings(filesystem, {
+      ...current,
+      zaip: { enabled: false },
+      project: { ...current.project, name: "Updated fixture" },
+      stack: {
+        ...current.stack,
+        overrides: {
+          languages: {
+            frontend: ["TypeScript"],
+            backend: ["TypeScript"],
+            site: ["Astro"],
+          },
+        },
+      },
+    });
+
+    expect(updated.zaip?.enabled).toBe(false);
+    expect(updated.stack.overrides).toEqual({
+      database: "postgres",
+      languages: {
+        frontend: ["TypeScript"],
+        backend: ["TypeScript"],
+        site: ["Astro"],
+      },
+    });
+    expect(parseProjectConfig(parseYaml(await readFile(configPath, "utf8")))).toEqual(updated);
+  });
+
+  it("rejects invalid settings before touching the project file", async () => {
+    const { configPath, filesystem } = await fixtureProject();
+    const original = await readFile(configPath, "utf8");
+    const current = await readProjectSettings(filesystem);
+
+    await expect(
+      persistProjectSettings(filesystem, {
+        ...current,
+        tracking: { ...current.tracking, currency: "real" },
+      }),
+    ).rejects.toThrow();
+    await expect(readFile(configPath, "utf8")).resolves.toBe(original);
+  });
+});

package/templates/.agents/dashboard/packages/local-runtime/src/project-settings.ts

@@ -0,0 +1,32 @@
+import {
+  PROJECT_CONFIG_PATH,
+  type ProjectConfig,
+  parseProjectConfig,
+  parseYaml,
+  serializeYaml,
+  type WorkspaceFileSystem,
+} from "@zaip-ai/core";
+
+export async function readProjectSettings(filesystem: WorkspaceFileSystem): Promise<ProjectConfig> {
+  return parseProjectConfig(parseYaml(await filesystem.readText(PROJECT_CONFIG_PATH)));
+}
+
+export async function persistProjectSettings(
+  filesystem: WorkspaceFileSystem,
+  input: unknown,
+): Promise<ProjectConfig> {
+  const current = await readProjectSettings(filesystem);
+  const requested = parseProjectConfig(input);
+  const candidate = parseProjectConfig({
+    ...requested,
+    stack: {
+      ...requested.stack,
+      overrides: {
+        ...current.stack.overrides,
+        ...requested.stack.overrides,
+      },
+    },
+  });
+  await filesystem.writeTextAtomic(PROJECT_CONFIG_PATH, serializeYaml(candidate));
+  return candidate;
+}

package/templates/.agents/dashboard/packages/local-runtime/src/runtime.mjs

@@ -0,0 +1,222 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+export const host = "127.0.0.1";
+export const defaultFrontendPort = 5173;
+export const defaultApiPort = 4317;
+const maxPortAttempts = 25;
+
+const sourceDirectory = dirname(fileURLToPath(import.meta.url));
+export const packageRoot = resolve(sourceDirectory, "..");
+export const workspaceRoot = resolve(packageRoot, "../../../..");
+export const frontendRoot = resolve(workspaceRoot, ".agents/dashboard/apps/frontend");
+const localNodeModules = resolve(packageRoot, "node_modules");
+const workspaceKey = createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
+export const sessionDirectory = join(tmpdir(), "zaip-aios", workspaceKey);
+export const dashboardSessionPath = join(sessionDirectory, "dashboard-session.json");
+export const launcherLogPath = join(sessionDirectory, "dashboard-launcher.log");
+
+export function createSessionToken() {
+  return process.env.ZAIP_UI_TOKEN ?? randomBytes(24).toString("base64url");
+}
+
+export function createSharedEnvironment(overrides = {}) {
+  return {
+    ...process.env,
+    NODE_ENV: "development",
+    ZAIP_WORKSPACE: workspaceRoot,
+    ...overrides,
+  };
+}
+
+export function appendLauncherLog(message) {
+  try {
+    mkdirSync(sessionDirectory, { recursive: true });
+    appendFileSync(launcherLogPath, `[${new Date().toISOString()}] ${message}\n`, {
+      encoding: "utf8",
+      flush: true,
+    });
+  } catch {
+    // Best-effort diagnostics must never hide the original launcher failure.
+  }
+}
+
+export async function ensureSessionDirectory() {
+  await mkdir(sessionDirectory, { recursive: true });
+}
+
+export function spawnNode(script, args, { cwd, env, stdio = ["ignore", "pipe", "pipe"] }) {
+  return spawn(process.execPath, [script, ...args], {
+    cwd,
+    env: createSharedEnvironment(env),
+    stdio,
+    shell: false,
+    windowsHide: true,
+  });
+}
+
+export function spawnTool(relativePath, args, options) {
+  return spawnNode(resolve(localNodeModules, relativePath), args, options);
+}
+
+export function stopChildProcess(child) {
+  if (!child || child.killed) return;
+  if (process.platform === "win32") {
+    spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+      stdio: "ignore",
+      windowsHide: true,
+    });
+    return;
+  }
+  child.kill("SIGTERM");
+}
+
+export function isPortFree(port) {
+  return new Promise((resolvePort) => {
+    const server = createServer();
+    server.unref();
+    server.once("error", () => resolvePort(false));
+    server.listen({ host, port }, () => server.close(() => resolvePort(true)));
+  });
+}
+
+export async function findAvailablePort(startPort) {
+  for (let port = startPort; port < startPort + maxPortAttempts; port += 1) {
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error(`No free port found between ${startPort} and ${startPort + maxPortAttempts - 1}`);
+}
+
+export async function waitForHttpOk(url, { headers = {}, timeoutMs = 30_000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(url, { headers });
+      if (response.ok) return;
+    } catch {
+      // The child may still be binding the loopback port.
+    }
+    await new Promise((resolveDelay) => setTimeout(resolveDelay, 250));
+  }
+  throw new Error(`Timed out waiting for ${url}`);
+}
+
+export async function startProjectionServer({ port, token, stdio = ["ignore", "pipe", "pipe"] }) {
+  const child = spawnTool("tsx/dist/cli.mjs", ["src/server.ts"], {
+    cwd: packageRoot,
+    env: {
+      ZAIP_SERVER_PORT: String(port),
+      ZAIP_UI_TOKEN: token,
+    },
+    stdio,
+  });
+  try {
+    await waitForHttpOk(`http://${host}:${port}/api/v2/health`);
+    return child;
+  } catch (error) {
+    stopChildProcess(child);
+    throw error;
+  }
+}
+
+export function startFrontend({ port, apiPort, token, stdio = ["ignore", "pipe", "pipe"] }) {
+  return spawnTool("vite/bin/vite.js", ["--host", host, "--port", String(port), "--strictPort"], {
+    cwd: frontendRoot,
+    env: {
+      BROWSER: "none",
+      ZAIP_DASHBOARD_API_PORT: String(apiPort),
+      ZAIP_UI_TOKEN: token,
+    },
+    stdio,
+  });
+}
+
+export async function buildFrontend({ stdio = ["ignore", "pipe", "pipe"] } = {}) {
+  const child = spawnTool("vite/bin/vite.js", ["build"], {
+    cwd: frontendRoot,
+    env: { BROWSER: "none" },
+    stdio,
+  });
+  await new Promise((resolveBuild, rejectBuild) => {
+    child.once("error", rejectBuild);
+    child.once("exit", (code, signal) => {
+      if (code === 0) resolveBuild();
+      else
+        rejectBuild(
+          new Error(`Frontend build failed (${signal ?? `exit code ${code ?? "unknown"}`})`),
+        );
+    });
+  });
+}
+
+export async function writeDashboardSession(session) {
+  await ensureSessionDirectory();
+  await writeFile(dashboardSessionPath, `${JSON.stringify(session, null, 2)}\n`, "utf8");
+}
+
+export async function readDashboardSession() {
+  try {
+    return JSON.parse(await readFile(dashboardSessionPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export async function clearDashboardSession() {
+  await rm(dashboardSessionPath, { force: true });
+}
+
+export async function stopRecordedDashboardSession() {
+  const session = await readDashboardSession();
+  await stopDashboardSession(session);
+  await clearDashboardSession();
+}
+
+export async function stopDashboardSession(session) {
+  if (!session || session.workspace !== workspaceRoot || !Array.isArray(session.pids)) return;
+  const rootPid = Number.isInteger(session.rootPid) ? session.rootPid : session.pids[0];
+  if (process.platform === "win32" && rootPid > 0 && rootPid !== process.pid) {
+    await new Promise((resolveStop) => {
+      const child = spawn("taskkill", ["/pid", String(rootPid), "/t", "/f"], {
+        stdio: "ignore",
+        windowsHide: true,
+      });
+      child.once("error", () => resolveStop());
+      child.once("exit", () => resolveStop());
+    });
+  }
+}
+
+function spawnDetached(command, args) {
+  try {
+    const child = spawn(command, args, { detached: true, stdio: "ignore", windowsHide: true });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function openBrowser(url) {
+  if (process.env.ZAIP_UI_NO_BROWSER === "1") return;
+  if (process.platform === "win32") {
+    const systemRoot = process.env.SystemRoot ?? "C:\\Windows";
+    const commands = [
+      [resolve(systemRoot, "explorer.exe"), [url]],
+      [process.env.ComSpec ?? resolve(systemRoot, "System32", "cmd.exe"), ["/c", "start", "", url]],
+    ];
+    for (const [command, args] of commands) {
+      if (spawnDetached(command, args)) return;
+    }
+    return;
+  }
+  const command = process.platform === "darwin" ? "open" : "xdg-open";
+  spawnDetached(command, [url]);
+}