@agentprojectcontext/apx 1.74.2 → 1.75.0

package/src/host/daemon/api/profiles.js

@@ -0,0 +1,179 @@
+// GET    /profiles                 installed + bundled packages, which one is active
+// GET    /profiles/doctor          health of the active profile (or ?id=)
+// GET    /profiles/:id             one package, with its schema, settings and prompt preview
+// POST   /profiles/install         { source, force? }
+// POST   /profiles/use             { id, force? }
+// POST   /profiles/off
+// PATCH  /profiles/config          { values: {...}, id? }
+// DELETE /profiles/:id             uninstall
+//
+// Thin adapter — body → core/profiles → response. The daemon is the writer on
+// purpose: activating a profile changes the live system prompt and the routine
+// schedule, so the process that owns both has to be the one applying it.
+import { readConfig } from "#core/config/index.js";
+import { readIdentity } from "#core/identity/index.js";
+import {
+  listProfilesWithState,
+  readProfile,
+  readProfileState,
+  effectiveProfileConfig,
+  installProfile,
+  useProfile,
+  offProfile,
+  setProfileConfig,
+  uninstallProfile,
+  profileDoctor,
+  renderProfilePrompt,
+  estimateTokens,
+} from "#core/profiles/index.js";
+
+/** 400 for anything the caller could have got right, 500 for the rest. */
+function fail(res, e) {
+  const msg = e?.message || String(e);
+  const isUserError =
+    /not installed|not found|invalid|unknown setting|must be|already|missing|required|not supported|cannot be activated|failed:/i.test(
+      msg
+    );
+  res.status(isUserError ? 400 : 500).json({ error: msg });
+}
+
+function detail(id, { preview = true } = {}) {
+  const profile = readProfile(id);
+  if (!profile) return null;
+
+  const cfg = readConfig();
+  const state = readProfileState(cfg);
+  const identity = (() => { try { return readIdentity(); } catch { return null; } })();
+  const settings = effectiveProfileConfig(profile, cfg);
+
+  const languages = profile.prompts.map((f) => {
+    const m = f.match(/^PROFILE\.([\w-]+)\.md$/);
+    return m ? m[1] : "en";
+  });
+
+  const rendered = preview
+    ? renderProfilePrompt(profile, {
+        identity,
+        globalConfig: { ...cfg, profile: { active: id, config: settings } },
+        lang: cfg?.user?.language || identity?.language || "en",
+      })
+    : "";
+
+  return {
+    id: profile.id,
+    name: profile.manifest.name || profile.id,
+    version: profile.manifest.version || null,
+    description: profile.manifest.description || "",
+    author: profile.manifest.author || null,
+    source: profile.source,
+    dir: profile.dir,
+    active: state.active === id,
+    languages: [...new Set(languages)].sort(),
+    provides: profile.manifest.provides || {},
+    requires: profile.manifest.requires || {},
+    schema: profile.schema || null,
+    defaults: profile.defaults,
+    config: settings,
+    budget: profile.manifest.prompt_budget_tokens || null,
+    tokens: preview ? estimateTokens(rendered) : null,
+    // The rendered block, exactly as it reaches the model. This is the best
+    // debugging tool the panel can offer and it costs nothing to expose.
+    preview: rendered,
+  };
+}
+
+export function register(app) {
+  app.get("/profiles", (_req, res) => {
+    try {
+      const cfg = readConfig();
+      res.json({
+        active: readProfileState(cfg).active,
+        profiles: listProfilesWithState(cfg),
+      });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  // Registered before /profiles/:id so "doctor" isn't swallowed as an id.
+  app.get("/profiles/doctor", (req, res) => {
+    try {
+      res.json(profileDoctor(req.query?.id || null));
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.get("/profiles/:id", (req, res) => {
+    try {
+      const out = detail(req.params.id, { preview: req.query?.preview !== "0" });
+      if (!out) return res.status(404).json({ error: `profile "${req.params.id}" not found` });
+      res.json(out);
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.post("/profiles/install", (req, res) => {
+    try {
+      const { source, force } = req.body || {};
+      if (!source) return res.status(400).json({ error: "body needs { source }" });
+      const out = installProfile(source, { force: !!force });
+      res.json({
+        ok: true,
+        profile: detail(out.profile.id),
+        warnings: out.warnings,
+        tokens: out.tokens,
+        doctor: out.doctor,
+      });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.post("/profiles/use", (req, res) => {
+    try {
+      const { id, force } = req.body || {};
+      if (!id) return res.status(400).json({ error: "body needs { id }" });
+      const out = useProfile(id, { confirmReplace: !!force });
+      res.json({
+        ok: true,
+        profile: detail(id),
+        routines: out.routines,
+        warnings: out.warnings,
+        tokens: out.tokens,
+      });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.post("/profiles/off", (_req, res) => {
+    try {
+      res.json({ ok: true, ...offProfile() });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.patch("/profiles/config", (req, res) => {
+    try {
+      const { values, id } = req.body || {};
+      if (!values || typeof values !== "object") {
+        return res.status(400).json({ error: "body needs { values: { key: value } }" });
+      }
+      const out = setProfileConfig(values, { id: id || null });
+      res.json({ ok: true, ...out });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+
+  app.delete("/profiles/:id", (req, res) => {
+    try {
+      res.json({ ok: true, ...uninstallProfile(req.params.id) });
+    } catch (e) {
+      fail(res, e);
+    }
+  });
+}

package/src/host/daemon/api/web.js

@@ -24,7 +24,7 @@ const API_PREFIXES = [
   "/health", "/admin", "/projects", "/telegram", "/engines", "/runtimes",
   "/messages", "/sessions", "/tools", "/mcp", "/voice", "/tts", "/desktop", "/overlay",
   "/transcribe", "/run", "/files", "/memory", "/env", "/pair", "/deck",
-  "/super-agent", "/identity", "/skills",
+  "/super-agent", "/identity", "/skills", "/profiles",
 ];
 
 export function isApiPath(p) {

package/src/host/daemon/api.js

@@ -51,6 +51,7 @@ import { register as registerPairing } from "./api/pairing.js";
 import { register as registerAdmin } from "./api/admin.js";
 import { register as registerAdminConfig } from "./api/admin-config.js";
 import { register as registerIdentity } from "./api/identity.js";
+import { register as registerProfiles } from "./api/profiles.js";
 import { register as registerWeb } from "./api/web.js";
 import { register as registerConfirm } from "./api/confirm.js";
 
@@ -151,6 +152,7 @@ export function buildApi({
   registerAdmin(app, ctx);
   registerAdminConfig(app, ctx);
   registerIdentity(app, ctx);
+  registerProfiles(app, ctx);
 
   // ---- Web admin panel (static SPA, must mount before 404) ---------
   // Serves src/interfaces/web/dist when present + the /admin/web-token

package/src/interfaces/cli/commands/profile.js

@@ -0,0 +1,252 @@
+// apx profile — install, activate and configure the super-agent's personality.
+//
+//   apx profile list
+//   apx profile show <id>       [--preview]
+//   apx profile install <id|path> [--force]
+//   apx profile use <id>        [--force]
+//   apx profile off
+//   apx profile config          [--set k=v]... [--interactive]
+//   apx profile doctor          [<id>]
+//   apx profile uninstall <id>
+//
+// Everything goes through the daemon: activating a profile changes the live
+// system prompt and rewrites the routine schedule, so the process that owns
+// both has to apply it. Writing config from here would leave the running
+// daemon out of date.
+import readline from "node:readline/promises";
+import { http } from "../http.js";
+
+export const PROFILE_USAGE = {
+  list:      "apx profile list",
+  show:      "apx profile show <id> [--preview]",
+  install:   "apx profile install <id|path> [--force]",
+  use:       "apx profile use <id> [--force]",
+  off:       "apx profile off",
+  config:    "apx profile config [--set key=value]... [--interactive]",
+  doctor:    "apx profile doctor [<id>]",
+  uninstall: "apx profile uninstall <id>",
+};
+
+function fail(sub, msg) {
+  console.error(`apx profile ${sub}: ${msg}`);
+  console.error(`Usage: ${PROFILE_USAGE[sub]}`);
+  process.exit(1);
+}
+
+function asArray(v) {
+  if (v === undefined || v === null) return [];
+  return Array.isArray(v) ? v : [v];
+}
+
+/** `--set k=v --set a=b` → { k: "v", a: "b" } */
+function parseSetFlags(flags) {
+  const out = {};
+  for (const raw of asArray(flags?.set)) {
+    const s = String(raw);
+    const eq = s.indexOf("=");
+    if (eq < 1) {
+      console.error(`apx profile config: --set expects key=value — got "${s}"`);
+      process.exit(1);
+    }
+    out[s.slice(0, eq).trim()] = s.slice(eq + 1);
+  }
+  return out;
+}
+
+function printWarnings(warnings = []) {
+  for (const w of warnings) console.log(`  warning: ${w}`);
+}
+
+function printDoctor(report) {
+  console.log(report.summary);
+  if (report.tokens != null) {
+    const budget = report.budget ? ` (declared budget ${report.budget})` : "";
+    console.log(`  prompt: ~${report.tokens} tokens${budget}`);
+  }
+  for (const c of report.checks || []) {
+    const mark = c.level === "error" ? "✖" : "!";
+    console.log(`  ${mark} [${c.label}] ${c.detail}`);
+    if (c.fix) console.log(`      fix: ${c.fix}`);
+  }
+}
+
+// ── list ────────────────────────────────────────────────────────────────────
+
+export async function cmdProfileList() {
+  const { active, profiles } = await http.get("/profiles");
+  if (!profiles.length) {
+    console.log("(no profiles available)");
+    return;
+  }
+  for (const p of profiles) {
+    const mark = p.active ? "*" : " ";
+    const version = p.version ? ` v${p.version}` : "";
+    console.log(`${mark} ${p.id.padEnd(16)} ${p.name}${version}  [${p.source}]`);
+    if (p.description) console.log(`    ${p.description}`);
+  }
+  console.log("");
+  console.log(active ? `active: ${active}` : "active: none (vanilla)");
+}
+
+// ── show ────────────────────────────────────────────────────────────────────
+
+export async function cmdProfileShow(args) {
+  const id = args._[0];
+  if (!id) fail("show", "missing <id>");
+
+  const p = await http.get(`/profiles/${encodeURIComponent(id)}`);
+  console.log(`${p.name} (${p.id}) v${p.version || "?"} — ${p.source}${p.active ? " — ACTIVE" : ""}`);
+  if (p.description) console.log(p.description);
+  console.log(`languages: ${p.languages.join(", ") || "en"}`);
+  console.log(`prompt: ~${p.tokens} tokens${p.budget ? ` (declared budget ${p.budget})` : ""}`);
+  console.log(`path: ${p.dir}`);
+
+  const keys = Object.keys(p.config || {});
+  if (keys.length) {
+    console.log("\nsettings:");
+    for (const k of keys.sort()) console.log(`  ${k.padEnd(24)} ${p.config[k]}`);
+  }
+
+  if (args?.flags?.preview) {
+    console.log("\n--- rendered prompt block ---");
+    console.log(p.preview || "(empty)");
+  }
+}
+
+// ── install ─────────────────────────────────────────────────────────────────
+
+export async function cmdProfileInstall(args) {
+  const source = args._[0];
+  if (!source) fail("install", "missing <id|path>");
+
+  const r = await http.post("/profiles/install", { source, force: !!args?.flags?.force });
+  console.log(`installed ${r.profile.name} (${r.profile.id}) v${r.profile.version || "?"}`);
+  console.log(`  prompt: ~${r.tokens} tokens`);
+  printWarnings(r.warnings);
+  console.log("");
+  console.log(`Not active yet — run: apx profile use ${r.profile.id}`);
+}
+
+// ── use / off ───────────────────────────────────────────────────────────────
+
+export async function cmdProfileUse(args) {
+  const id = args._[0];
+  if (!id) fail("use", "missing <id>");
+
+  const r = await http.post("/profiles/use", { id, force: !!args?.flags?.force });
+  console.log(`active profile: ${r.profile.name} (${r.profile.id})`);
+  printWarnings(r.warnings);
+
+  const { installed = [], skipped = [] } = r.routines || {};
+  if (installed.length) console.log(`  routines installed: ${installed.join(", ")}`);
+  for (const s of skipped) {
+    console.log(`  routine "${s.name}" left alone (${s.reason.replace(/_/g, " ")})`);
+  }
+  if (!r.profile.active) console.log("  (warning: profile did not activate)");
+}
+
+export async function cmdProfileOff() {
+  const r = await http.post("/profiles/off", {});
+  if (!r.was) {
+    console.log("no profile was active — nothing to do");
+    return;
+  }
+  console.log(`profile "${r.was}" is off — APX is back to vanilla`);
+  if (r.routines?.length) console.log(`  routines disabled (not deleted): ${r.routines.join(", ")}`);
+  console.log("  settings, tasks and memory were kept — `apx profile use` restores them");
+}
+
+// ── config ──────────────────────────────────────────────────────────────────
+
+async function interactiveConfig(profile) {
+  const props = profile.schema?.properties || {};
+  const keys = Object.keys(props);
+  if (!keys.length) {
+    console.log(`profile "${profile.id}" has no configurable settings`);
+    return {};
+  }
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const values = {};
+  try {
+    console.log(`Configuring ${profile.name}. Press enter to keep the current value.\n`);
+    for (const key of keys) {
+      const def = props[key];
+      const current = profile.config?.[key];
+      const hint = def.enum ? ` (${def.enum.join(" | ")})` : def.type ? ` (${def.type})` : "";
+      const label = def.title || key;
+      const answer = (await rl.question(`${label}${hint} [${current ?? ""}]: `)).trim();
+      if (answer !== "") values[key] = answer;
+    }
+  } finally {
+    rl.close();
+  }
+  return values;
+}
+
+export async function cmdProfileConfig(args) {
+  const { active } = await http.get("/profiles");
+  const id = args?.flags?.profile || active;
+  if (!id) {
+    console.error("apx profile config: no profile is active — run: apx profile use <id>");
+    process.exit(1);
+  }
+
+  const profile = await http.get(`/profiles/${encodeURIComponent(id)}?preview=0`);
+
+  let values = parseSetFlags(args?.flags);
+  if (args?.flags?.interactive) {
+    values = { ...values, ...(await interactiveConfig(profile)) };
+  }
+
+  // No changes asked for → show the current settings.
+  if (!Object.keys(values).length) {
+    const props = profile.schema?.properties || {};
+    const keys = Object.keys(profile.config || {});
+    if (!keys.length) {
+      console.log(`profile "${id}" has no settings`);
+      return;
+    }
+    console.log(`settings for ${profile.name} (${id}):`);
+    for (const k of keys.sort()) {
+      const def = props[k] || {};
+      const allowed = def.enum ? `  [${def.enum.join(" | ")}]` : "";
+      console.log(`  ${k.padEnd(24)} ${profile.config[k]}${allowed}`);
+    }
+    console.log("\nchange one with: apx profile config --set key=value");
+    return;
+  }
+
+  const r = await http.patch("/profiles/config", { values, id });
+  console.log(`updated: ${r.changed.join(", ")}`);
+  for (const k of r.changed) console.log(`  ${k.padEnd(24)} ${r.config[k]}`);
+
+  const { installed = [], skipped = [] } = r.routines || {};
+  if (installed.length) console.log(`  routines rescheduled: ${installed.join(", ")}`);
+  for (const s of skipped) {
+    console.log(`  routine "${s.name}" left alone (${s.reason.replace(/_/g, " ")})`);
+  }
+}
+
+// ── doctor / uninstall ──────────────────────────────────────────────────────
+
+export async function cmdProfileDoctor(args) {
+  const id = args._[0];
+  const q = id ? `?id=${encodeURIComponent(id)}` : "";
+  printDoctor(await http.get(`/profiles/doctor${q}`));
+}
+
+export async function cmdProfileUninstall(args) {
+  const id = args._[0];
+  if (!id) fail("uninstall", "missing <id>");
+
+  const r = await http.delete(`/profiles/${encodeURIComponent(id)}`);
+  console.log(`uninstalled "${r.id}" (${r.source})`);
+  if (r.routines?.removed?.length) console.log(`  routines removed: ${r.routines.removed.join(", ")}`);
+  if (r.routines?.kept?.length) {
+    console.log(`  kept (you edited these): ${r.routines.kept.join(", ")}`);
+  }
+  if (r.source === "bundled") {
+    console.log("  bundled package hidden — reinstall it any time with: apx profile install " + r.id);
+  }
+}

package/src/interfaces/cli/index.js

@@ -151,6 +151,16 @@ import {
   cmdTaskReopen,
   cmdTaskPatch,
 } from "./commands/task.js";
+import {
+  cmdProfileList,
+  cmdProfileShow,
+  cmdProfileInstall,
+  cmdProfileUse,
+  cmdProfileOff,
+  cmdProfileConfig,
+  cmdProfileDoctor,
+  cmdProfileUninstall,
+} from "./commands/profile.js";
 import {
   cmdOrgShow,
   cmdOrgAreaAdd,
@@ -1607,6 +1617,42 @@ const HELP_TOPICS = new Map(Object.entries({
     examples: ["apx plugins status telegram"],
   }),
 
+  profile: topic({
+    title: "apx profile",
+    summary:
+      "Install, activate and configure the super-agent's line of work. With no profile active, APX behaves exactly as it always has.",
+    usage: ["apx profile <subcommand> [args] [--flags]"],
+    commands: [
+      ["list | ls", "Show every available profile and which one is active."],
+      ["show | get <id>", "Details, settings and token cost of one profile."],
+      ["install | add <id|path>", "Validate and install a profile. Does NOT activate it."],
+      ["use | activate <id>", "Make a profile active and install its routines."],
+      ["off | deactivate", "Go back to vanilla. Disables its routines, deletes nothing."],
+      ["config", "Show or change the active profile's settings."],
+      ["doctor [<id>]", "What is missing for this profile to do its job."],
+      ["uninstall | remove <id>", "Remove a profile, keeping anything you edited."],
+    ],
+    options: [
+      ["--preview", "show: also print the rendered prompt block."],
+      ["--set <key=value>", "config: set one setting. Repeatable."],
+      ["--interactive", "config: walk through every setting."],
+      ["--force", "install: overwrite. use: replace the active profile."],
+    ],
+    examples: [
+      "apx profile list",
+      "apx profile install secretary",
+      "apx profile use secretary",
+      "apx profile config --set day_open_at=08:30 --set nudge_budget_per_day=3",
+      "apx profile show secretary --preview",
+      "apx profile off",
+    ],
+  }),
+  profiles: topic({
+    title: "apx profiles",
+    summary: "Alias for apx profile.",
+    usage: ["apx profiles <subcommand>"],
+    examples: ["apx profiles list"],
+  }),
   task: topic({
     title: "apx task",
     summary: "Per-project TODO list backed by the daemon (/projects/:pid/tasks).",
@@ -2753,6 +2799,22 @@ async function dispatch(cmd, rest) {
         break;
       }
 
+      case "profile":
+      case "profiles": {
+        const sub = rest[0];
+        const a = parseArgs(rest.slice(1));
+        if (!sub || sub === "list" || sub === "ls") await cmdProfileList(a);
+        else if (sub === "show" || sub === "get") await cmdProfileShow(a);
+        else if (sub === "install" || sub === "add") await cmdProfileInstall(a);
+        else if (sub === "use" || sub === "activate") await cmdProfileUse(a);
+        else if (sub === "off" || sub === "deactivate") await cmdProfileOff(a);
+        else if (sub === "config") await cmdProfileConfig(a);
+        else if (sub === "doctor") await cmdProfileDoctor(a);
+        else if (sub === "uninstall" || sub === "remove" || sub === "rm") await cmdProfileUninstall(a);
+        else die(`unknown profile subcommand: ${sub}\nUsage: apx profile <list|show|install|use|off|config|doctor|uninstall>`);
+        break;
+      }
+
       case "command":
       case "commands": {
         const sub = rest[0];