@agentprojectcontext/apx 1.15.5 → 1.16.0

package/src/cli-ts/commands/exec.ts

@@ -0,0 +1,109 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp, type StreamEvent } from "../http.js";
+import { error } from "../ui.js";
+
+interface GlobalArgs { project?: string }
+
+async function resolveProjectId(project?: string): Promise<string> {
+  const http = await getHttp();
+  const projects = (await http.get("/projects")) as Array<{ id: string; name: string; path: string }>;
+  if (!projects?.length) throw new Error("No projects registered. Run: apx init");
+  if (project) {
+    const match = projects.find(
+      (p) => p.id === project || p.name === project || p.path === project || p.path?.endsWith("/" + project),
+    );
+    if (!match) throw new Error(`Project not found: ${project}`);
+    return match.id;
+  }
+  return projects[0]!.id;
+}
+
+export const execCmd: CommandModule = {
+  command: "exec <agent> [prompt..]",
+  aliases: ["run"],
+  describe: "Run a one-shot prompt through an agent (non-interactive)",
+  builder: (yargs: Argv) =>
+    yargs
+      .positional("agent", { type: "string", demandOption: true, describe: "Agent slug" })
+      .positional("prompt", { type: "string", array: true, describe: "Prompt text" })
+      .option("model", { type: "string", describe: "Override model" })
+      .option("max-tokens", { type: "number", describe: "Max output tokens" })
+      .option("temperature", { type: "number", describe: "Sampling temperature (0–1)" })
+      .option("format", {
+        choices: ["text", "json"] as const,
+        default: "text" as const,
+        describe: "Output format",
+      })
+      .option("stream", {
+        type: "boolean",
+        default: true,
+        describe: "Stream output as it arrives",
+      }),
+  handler: async (
+    args: ArgumentsCamelCase<Record<string, unknown>>,
+  ) => {
+    try {
+      const project = args.project as string | undefined;
+      const agent = args.agent as string;
+      const promptArgs = args.prompt as string[] | undefined;
+      const model = args.model as string | undefined;
+      const maxTokens = args.maxTokens as number | undefined;
+      const temperature = args.temperature as number | undefined;
+      const format = args.format as "text" | "json";
+      const stream = args.stream as boolean;
+
+      // Build prompt from args + stdin
+      let prompt = (promptArgs ?? []).join(" ");
+      if (!process.stdin.isTTY) {
+        const chunks: Buffer[] = [];
+        for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+        const piped = Buffer.concat(chunks).toString().trim();
+        if (piped) prompt = prompt ? prompt + "\n\n" + piped : piped;
+      }
+      if (!prompt) throw new Error("No prompt provided. Pass text as argument or via stdin.");
+
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      const body = {
+        prompt,
+        model,
+        maxTokens,
+        temperature,
+      };
+
+      if (stream) {
+        // Try streaming endpoint first
+        try {
+          const result = await http.streamPost(
+            `/projects/${pid}/super-agent/chat/stream`,
+            { ...body, contextNote: `Agent: ${agent}` },
+            (ev: StreamEvent) => {
+              if (ev.type === "chunk" && typeof ev.chunk === "string") {
+                process.stdout.write(ev.chunk);
+              }
+              if (ev.type === "event" && ev.event === "assistant_text" && typeof (ev as Record<string, unknown>).text === "string") {
+                process.stdout.write((ev as Record<string, unknown>).text as string);
+              }
+            },
+          ) as { text?: string };
+          if (!result?.text) process.stdout.write("\n");
+          return;
+        } catch {
+          // Fall through to non-streaming
+        }
+      }
+
+      const result = (await http.post(`/projects/${pid}/agents/${agent}/exec`, body)) as {
+        text: string; usage?: { input_tokens: number; output_tokens: number };
+      };
+      if (format === "json") {
+        process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+      } else {
+        process.stdout.write(result.text + "\n");
+      }
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};

package/src/cli-ts/commands/mcp.ts

@@ -0,0 +1,235 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp } from "../http.js";
+import { println, error, success, dim, highlight, table } from "../ui.js";
+
+interface GlobalArgs { project?: string }
+
+async function resolveProjectId(project?: string): Promise<string> {
+  const http = await getHttp();
+  const projects = (await http.get("/projects")) as Array<{ id: string; name: string; path: string }>;
+  if (!projects?.length) throw new Error("No projects registered. Run: apx init");
+  if (project) {
+    const match = projects.find(
+      (p) => p.id === project || p.name === project || p.path === project || p.path?.endsWith("/" + project),
+    );
+    if (!match) throw new Error(`Project not found: ${project}`);
+    return match.id;
+  }
+  return projects[0]!.id;
+}
+
+// ---------- list ----------
+
+const listCmd: CommandModule = {
+  command: "list",
+  aliases: ["ls"],
+  describe: "List registered MCP servers",
+  handler: async (args: ArgumentsCamelCase<GlobalArgs>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project as string | undefined);
+      const mcps = (await http.get(`/projects/${pid}/mcps`)) as Array<{
+        name: string; transport?: string; enabled?: boolean; source?: string;
+      }>;
+      if (!mcps?.length) { println(dim("No MCP servers configured.")); return; }
+      table(
+        mcps.map((m) => ({
+          Name: m.name,
+          Transport: m.transport || "-",
+          Enabled: m.enabled ? "✓" : "✗",
+          Source: m.source || "-",
+        })),
+        ["Name", "Transport", "Enabled", "Source"],
+      );
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- add ----------
+
+const addCmd: CommandModule = {
+  command: "add <name>",
+  describe: "Register an MCP server",
+  builder: (yargs: Argv) =>
+    yargs
+      .positional("name", { type: "string", demandOption: true, describe: "MCP server name" })
+      .option("command", { alias: "c", type: "string", describe: "Command to launch MCP server" })
+      .option("url", { type: "string", describe: "Remote MCP server URL (for HTTP transport)" })
+      .option("env", {
+        type: "array",
+        string: true,
+        describe: "Environment variables (KEY=VALUE)",
+      })
+      .option("enabled", { type: "boolean", default: true, describe: "Enable the server" }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const name = args.name as string;
+      const command = args.command as string | undefined;
+      const url = args.url as string | undefined;
+      const env = args.env as string[] | undefined;
+      const enabled = args.enabled as boolean;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      // Parse env KEY=VALUE pairs
+      const envRecord: Record<string, string> = {};
+      for (const e of env ?? []) {
+        const idx = e.indexOf("=");
+        if (idx > 0) envRecord[e.slice(0, idx)] = e.slice(idx + 1);
+      }
+      const body: Record<string, unknown> = {
+        name,
+        enabled,
+      };
+      if (command) body.command = command;
+      if (url) body.url = url;
+      if (Object.keys(envRecord).length) body.env = envRecord;
+
+      await http.post(`/projects/${pid}/mcps`, body);
+      success(`MCP server registered: ${highlight(name)}`);
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- remove ----------
+
+const removeCmd: CommandModule = {
+  command: "remove <name>",
+  aliases: ["rm"],
+  describe: "Remove an MCP server",
+  builder: (yargs: Argv) =>
+    yargs.positional("name", { type: "string", demandOption: true, describe: "MCP server name" }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const name = args.name as string;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      await http.delete(`/projects/${pid}/mcps/${name}`);
+      success(`MCP server removed: ${name}`);
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- enable / disable ----------
+
+const enableCmd: CommandModule = {
+  command: "enable <name>",
+  describe: "Enable an MCP server",
+  builder: (yargs: Argv) =>
+    yargs.positional("name", { type: "string", demandOption: true }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const name = args.name as string;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      await http.post(`/projects/${pid}/mcps`, { name, enabled: true });
+      success(`Enabled: ${name}`);
+    } catch (err: unknown) { error(String(err)); process.exit(1); }
+  },
+};
+
+const disableCmd: CommandModule = {
+  command: "disable <name>",
+  describe: "Disable an MCP server",
+  builder: (yargs: Argv) =>
+    yargs.positional("name", { type: "string", demandOption: true }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const name = args.name as string;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      await http.post(`/projects/${pid}/mcps`, { name, enabled: false });
+      success(`Disabled: ${name}`);
+    } catch (err: unknown) { error(String(err)); process.exit(1); }
+  },
+};
+
+// ---------- tools ----------
+
+const toolsCmd: CommandModule = {
+  command: "tools <name>",
+  describe: "List tools exposed by an MCP server",
+  builder: (yargs: Argv) =>
+    yargs.positional("name", { type: "string", demandOption: true }),
+  handler: async (args: ArgumentsCamelCase<Record<string, unknown>>) => {
+    try {
+      const project = args.project as string | undefined;
+      const name = args.name as string;
+      const http = await getHttp();
+      const pid = await resolveProjectId(project);
+      const result = (await http.post(`/mcp/run`, {
+        project: pid,
+        name,
+        tool: "list_tools",
+        params: {},
+      })) as { result?: { tools?: Array<{ name: string; description?: string }> } };
+      const tools = result?.result?.tools ?? [];
+      if (!tools.length) { println(dim("No tools found.")); return; }
+      table(
+        tools.map((t) => ({ Tool: t.name, Description: t.description?.slice(0, 60) || "-" })),
+        ["Tool", "Description"],
+      );
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- check ----------
+
+const checkCmd: CommandModule = {
+  command: "check",
+  describe: "Validate MCP configuration",
+  handler: async (args: ArgumentsCamelCase<GlobalArgs>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project as string | undefined);
+      const result = (await http.get(`/projects/${pid}/mcps/check`)) as {
+        conflicts?: string[];
+        entries?: Array<{ name: string; ok: boolean; error?: string }>;
+      };
+      if (result.conflicts?.length) {
+        println("\x1b[93m⚠ Conflicts:\x1b[0m");
+        result.conflicts.forEach((c) => println("  " + c));
+      }
+      result.entries?.forEach((e) => {
+        if (e.ok) success(e.name);
+        else error(`${e.name}: ${e.error}`);
+      });
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- parent ----------
+
+export const mcpCmd: CommandModule = {
+  command: "mcp",
+  describe: "Manage MCP (Model Context Protocol) servers",
+  builder: (yargs: Argv) =>
+    yargs
+      .command(listCmd)
+      .command(addCmd)
+      .command(removeCmd)
+      .command(enableCmd)
+      .command(disableCmd)
+      .command(toolsCmd)
+      .command(checkCmd)
+      .demandCommand(1, "Specify an mcp subcommand"),
+  handler: () => {},
+};

package/src/cli-ts/commands/session.ts

@@ -0,0 +1,224 @@
+import type { CommandModule, Argv, ArgumentsCamelCase } from "yargs";
+import { getHttp } from "../http.js";
+import { println, error, success, dim, bold, table, highlight } from "../ui.js";
+
+interface Session {
+  filename?: string;
+  title?: string;
+  started_at?: string;
+  ended_at?: string;
+  agent?: string;
+  status?: string;
+}
+
+interface GlobalArgs {
+  project?: string;
+}
+
+async function resolveProjectId(project?: string): Promise<string> {
+  const http = await getHttp();
+  const projects = (await http.get("/projects")) as Array<{
+    id: string;
+    name: string;
+    path: string;
+  }>;
+  if (!projects?.length) throw new Error("No projects registered. Run: apx init");
+
+  if (project) {
+    const match = projects.find(
+      (p) =>
+        p.id === project ||
+        p.name === project ||
+        p.path === project ||
+        p.path?.endsWith("/" + project),
+    );
+    if (!match) throw new Error(`Project not found: ${project}`);
+    return match.id;
+  }
+  // Default to first project
+  return projects[0]!.id;
+}
+
+// ---------- list ----------
+
+const listCmd: CommandModule<GlobalArgs, GlobalArgs & { last: number; format: string }> = {
+  command: "list",
+  aliases: ["ls"],
+  describe: "List sessions for the current project",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs
+      .option("last", {
+        alias: "n",
+        type: "number",
+        default: 20,
+        describe: "Number of recent sessions to show",
+      })
+      .option("format", {
+        choices: ["table", "json"] as const,
+        default: "table" as const,
+        describe: "Output format",
+      }),
+  handler: async (args: ArgumentsCamelCase<GlobalArgs & { last: number; format: string }>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project);
+      const sessions = (await http.get(`/projects/${pid}/sessions`)) as Session[];
+      if (!sessions?.length) {
+        println(dim("No sessions found."));
+        return;
+      }
+      const slice = sessions.slice(-args.last);
+      if (args.format === "json") {
+        process.stdout.write(JSON.stringify(slice, null, 2) + "\n");
+        return;
+      }
+      table(
+        slice.map((s) => ({
+          Title: s.title || s.filename || "(no title)",
+          Agent: s.agent || "-",
+          Started: s.started_at ? new Date(s.started_at).toLocaleString() : "-",
+          Status: s.status || "open",
+        })),
+        ["Title", "Agent", "Started", "Status"],
+      );
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- new ----------
+
+const newCmd: CommandModule<GlobalArgs, GlobalArgs & { title?: string; body?: string; agent?: string }> = {
+  command: "new",
+  describe: "Create a new session",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs
+      .option("title", {
+        type: "string",
+        describe: "Session title",
+      })
+      .option("body", {
+        type: "string",
+        describe: "Initial session body / context",
+      })
+      .option("agent", {
+        type: "string",
+        describe: "Agent slug to associate the session with",
+      }),
+  handler: async (args: ArgumentsCamelCase<GlobalArgs & { title?: string; body?: string; agent?: string }>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project);
+      const agentSlug = args.agent || "default";
+      const session = (await http.post(`/projects/${pid}/agents/${agentSlug}/sessions`, {
+        title: args.title || `Session ${new Date().toLocaleDateString()}`,
+        body: args.body,
+      })) as { filename: string; path: string };
+      success(`Session created: ${highlight(session.filename)}`);
+      if (session.path) println(dim(session.path));
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- get / show ----------
+
+const getCmd: CommandModule<GlobalArgs, GlobalArgs & { id: string; body: boolean }> = {
+  command: "get <id>",
+  aliases: ["show"],
+  describe: "Show a session by filename or ID",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs
+      .positional("id", { type: "string", demandOption: true, describe: "Session filename or ID" })
+      .option("body", {
+        type: "boolean",
+        default: false,
+        describe: "Print session body / markdown",
+      }),
+  handler: async (args: ArgumentsCamelCase<GlobalArgs & { id: string; body: boolean }>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project);
+      const session = (await http.get(`/projects/${pid}/sessions/${args.id}`)) as Record<string, unknown>;
+      if (args.body) {
+        process.stdout.write(String(session.body_md || session.body || "") + "\n");
+        return;
+      }
+      process.stdout.write(JSON.stringify(session, null, 2) + "\n");
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- delete ----------
+
+const deleteCmd: CommandModule<GlobalArgs, GlobalArgs & { id: string }> = {
+  command: "delete <id>",
+  aliases: ["rm"],
+  describe: "Delete a session",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs.positional("id", { type: "string", demandOption: true, describe: "Session filename or ID" }),
+  handler: async (args: ArgumentsCamelCase<GlobalArgs & { id: string }>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project);
+      await http.delete(`/projects/${pid}/sessions/${args.id}`);
+      success(`Session deleted: ${args.id}`);
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- compact ----------
+
+const compactCmd: CommandModule<GlobalArgs, GlobalArgs & { id?: string; model?: string }> = {
+  command: "compact [id]",
+  describe: "Summarize and compact a session's conversation history",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs
+      .positional("id", { type: "string", describe: "Session ID (defaults to latest)" })
+      .option("model", { type: "string", describe: "Model to use for summarization" }),
+  handler: async (args: ArgumentsCamelCase<GlobalArgs & { id?: string; model?: string }>) => {
+    try {
+      const http = await getHttp();
+      const pid = await resolveProjectId(args.project);
+      const path = args.id
+        ? `/projects/${pid}/sessions/${args.id}/compact`
+        : `/sessions/${pid}/compact`;
+      const result = (await http.post(path, { model: args.model, project: pid })) as {
+        compacted_turns?: number;
+        summary?: string;
+      };
+      success(`Compacted ${result.compacted_turns ?? "?"} turns.`);
+      if (result.summary) println(dim(result.summary));
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};
+
+// ---------- parent command ----------
+
+export const sessionCmd: CommandModule<GlobalArgs, GlobalArgs> = {
+  command: "session",
+  aliases: ["sessions"],
+  describe: "Manage APC sessions",
+  builder: (yargs: Argv<GlobalArgs>) =>
+    yargs
+      .command(listCmd as CommandModule)
+      .command(newCmd as CommandModule)
+      .command(getCmd as CommandModule)
+      .command(deleteCmd as CommandModule)
+      .command(compactCmd as CommandModule)
+      .demandCommand(1, "Specify a session subcommand"),
+  handler: () => {},
+};

package/src/cli-ts/commands/status.ts

@@ -0,0 +1,61 @@
+import type { CommandModule, ArgumentsCamelCase } from "yargs";
+import { getHttp } from "../http.js";
+import { println, error, success, dim, bold, highlight } from "../ui.js";
+
+export const statusCmd: CommandModule = {
+  command: "status",
+  describe: "Show APX system health and project overview",
+  handler: async (args: ArgumentsCamelCase<{ project?: string }>) => {
+    try {
+      const http = await getHttp();
+
+      // Daemon health
+      let daemonOk = false;
+      try {
+        const health = (await http.get("/health")) as { version?: string; uptime_s?: number };
+        println(
+          "\x1b[92m●\x1b[0m Daemon  " +
+          dim(`v${health.version ?? "?"}`) +
+          "  uptime " + dim(`${health.uptime_s ?? "?"}s`),
+        );
+        daemonOk = true;
+      } catch {
+        println("\x1b[91m✗\x1b[0m Daemon  " + dim("not running — run: apx daemon start"));
+      }
+
+      if (!daemonOk) { process.exit(1); return; }
+
+      // Projects
+      const projects = (await http.get("/projects")) as Array<{
+        id: string; name: string; path: string;
+      }>;
+      println("");
+      println(bold("Projects") + "  " + dim(`(${projects?.length ?? 0})`));
+      if (!projects?.length) {
+        println(dim("  No projects. Run: apx init <path>"));
+      } else {
+        for (const p of projects) {
+          const isActive = !args.project || p.name === args.project || p.id === args.project;
+          println(
+            (isActive ? "\x1b[94m▶\x1b[0m" : " ") +
+            " " + highlight(p.name ?? p.id) +
+            "  " + dim(p.path),
+          );
+        }
+      }
+
+      // Engines
+      try {
+        const eng = (await http.get("/engines")) as { engines: string[] };
+        if (eng?.engines?.length) {
+          println("");
+          println(bold("Engines") + "  " + dim(`(${eng.engines.length})`));
+          println(dim("  " + eng.engines.slice(0, 6).join("  ") + (eng.engines.length > 6 ? "  …" : "")));
+        }
+      } catch { /* engines endpoint optional */ }
+    } catch (err: unknown) {
+      error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  },
+};

package/src/cli-ts/http.ts

@@ -0,0 +1,36 @@
+// Typed wrapper around the APX HTTP client (src/cli/http.js).
+// We use dynamic import since the base client is plain JS ESM.
+
+export interface StreamEvent {
+  type: "event" | "chunk" | "final" | "error";
+  [key: string]: unknown;
+}
+
+type HttpModule = {
+  get(path: string, opts?: RequestInit): Promise<unknown>;
+  post(path: string, body: unknown, opts?: RequestInit): Promise<unknown>;
+  put(path: string, body: unknown, opts?: RequestInit): Promise<unknown>;
+  patch(path: string, body: unknown, opts?: RequestInit): Promise<unknown>;
+  delete(path: string, opts?: RequestInit): Promise<unknown>;
+  streamPost(
+    path: string,
+    body: unknown,
+    onEvent: (ev: StreamEvent) => void,
+    opts?: RequestInit,
+  ): Promise<unknown>;
+  baseUrl(): string;
+  ping(timeoutMs?: number): Promise<boolean>;
+  createAbortController(): AbortController;
+};
+
+let _http: HttpModule | null = null;
+
+export async function getHttp(): Promise<HttpModule> {
+  if (!_http) {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore – plain JS outside rootDir; HttpModule above provides typing
+    const m = (await import("../cli/http.js")) as { http: HttpModule };
+    _http = m.http;
+  }
+  return _http;
+}