@agentprojectcontext/apx 1.74.2 → 1.75.0

package/src/core/profiles/manifest.js

@@ -0,0 +1,193 @@
+// profile.json + config.schema.json validation.
+//
+// The schema support is a deliberate subset — type / enum / default / title /
+// description / required — so a profile package can describe its white-label
+// variables without APX taking on a JSON Schema dependency. Anything richer
+// belongs in the profile's own logic, not in the manifest.
+import { PROFILE_ID_RE } from "./paths.js";
+
+const REQUIRED_FIELDS = ["id", "name", "version"];
+const SUPPORTED_TYPES = new Set(["string", "integer", "number", "boolean"]);
+
+/** Semver-ish compare. Returns -1 / 0 / 1. Ignores pre-release tags. */
+export function compareVersions(a, b) {
+  const parse = (v) =>
+    String(v || "0")
+      .split("-")[0]
+      .split(".")
+      .map((n) => parseInt(n, 10) || 0);
+  const [x, y] = [parse(a), parse(b)];
+  for (let i = 0; i < Math.max(x.length, y.length); i++) {
+    const d = (x[i] || 0) - (y[i] || 0);
+    if (d !== 0) return d > 0 ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * Validate a profile manifest.
+ * @returns {{ ok: boolean, errors: string[], warnings: string[] }}
+ */
+export function validateManifest(manifest, { apxVersion = null } = {}) {
+  const errors = [];
+  const warnings = [];
+
+  if (!manifest || typeof manifest !== "object" || Array.isArray(manifest)) {
+    return { ok: false, errors: ["profile.json must be a JSON object"], warnings };
+  }
+
+  for (const field of REQUIRED_FIELDS) {
+    if (!manifest[field] || typeof manifest[field] !== "string") {
+      errors.push(`profile.json: "${field}" is required and must be a string`);
+    }
+  }
+
+  if (manifest.id && !PROFILE_ID_RE.test(manifest.id)) {
+    errors.push(
+      `profile.json: "id" must be a lowercase slug (a-z, 0-9, dashes) — got "${manifest.id}"`
+    );
+  }
+
+  if (manifest.languages != null && !Array.isArray(manifest.languages)) {
+    errors.push('profile.json: "languages" must be an array of language codes');
+  }
+
+  if (manifest.prompt_budget_tokens != null) {
+    const n = manifest.prompt_budget_tokens;
+    if (!Number.isInteger(n) || n <= 0) {
+      errors.push('profile.json: "prompt_budget_tokens" must be a positive integer');
+    }
+  }
+
+  // apx_min_version gates installation, but only warns when we can't tell.
+  if (manifest.apx_min_version) {
+    if (!apxVersion) {
+      warnings.push(
+        `could not determine the running APX version to check apx_min_version ` +
+        `(${manifest.apx_min_version})`
+      );
+    } else if (compareVersions(apxVersion, manifest.apx_min_version) < 0) {
+      errors.push(
+        `profile "${manifest.id}" needs APX >= ${manifest.apx_min_version}, ` +
+        `this is ${apxVersion}`
+      );
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/**
+ * Validate a config.schema.json (the white-label variable declaration).
+ * Every property must carry a default — installing a profile and configuring
+ * nothing has to yield a working system, not a questionnaire.
+ */
+export function validateConfigSchema(schema) {
+  const errors = [];
+  const warnings = [];
+
+  if (schema == null) return { ok: true, errors, warnings };
+  if (typeof schema !== "object" || Array.isArray(schema)) {
+    return { ok: false, errors: ["config.schema.json must be a JSON object"], warnings };
+  }
+  if (schema.type && schema.type !== "object") {
+    errors.push('config.schema.json: top-level "type" must be "object"');
+  }
+
+  const props = schema.properties || {};
+  if (typeof props !== "object" || Array.isArray(props)) {
+    return { ok: false, errors: ['config.schema.json: "properties" must be an object'], warnings };
+  }
+
+  for (const [key, def] of Object.entries(props)) {
+    if (!def || typeof def !== "object") {
+      errors.push(`config.schema.json: property "${key}" must be an object`);
+      continue;
+    }
+    if (def.type && !SUPPORTED_TYPES.has(def.type)) {
+      errors.push(
+        `config.schema.json: property "${key}" has unsupported type "${def.type}" ` +
+        `(supported: ${[...SUPPORTED_TYPES].join(", ")})`
+      );
+    }
+    if (def.enum != null && (!Array.isArray(def.enum) || def.enum.length === 0)) {
+      errors.push(`config.schema.json: property "${key}" — "enum" must be a non-empty array`);
+    }
+    if (def.default === undefined) {
+      warnings.push(
+        `config.schema.json: property "${key}" has no default — a profile should work ` +
+        `before the user configures anything`
+      );
+    } else if (def.enum && !def.enum.includes(def.default)) {
+      errors.push(
+        `config.schema.json: property "${key}" — default "${def.default}" is not in its enum`
+      );
+    }
+  }
+
+  return { ok: errors.length === 0, errors, warnings };
+}
+
+/** Every property's default, as a plain object. Missing defaults are skipped. */
+export function schemaDefaults(schema) {
+  const out = {};
+  const props = schema?.properties || {};
+  for (const [key, def] of Object.entries(props)) {
+    if (def && def.default !== undefined) out[key] = def.default;
+  }
+  return out;
+}
+
+function coerce(value, type) {
+  if (type === "integer" || type === "number") {
+    const n = Number(value);
+    if (!Number.isFinite(n)) return { ok: false };
+    if (type === "integer" && !Number.isInteger(n)) return { ok: false };
+    return { ok: true, value: n };
+  }
+  if (type === "boolean") {
+    if (typeof value === "boolean") return { ok: true, value };
+    const s = String(value).toLowerCase();
+    if (["true", "1", "yes", "on"].includes(s)) return { ok: true, value: true };
+    if (["false", "0", "no", "off"].includes(s)) return { ok: true, value: false };
+    return { ok: false };
+  }
+  return { ok: true, value: String(value) };
+}
+
+/**
+ * Validate + coerce a config patch against the schema.
+ * CLI flags arrive as strings, so values are coerced to the declared type
+ * rather than rejected for being "3" instead of 3.
+ *
+ * @returns {{ ok: boolean, errors: string[], value: object }}
+ */
+export function validateConfigValues(schema, values = {}) {
+  const errors = [];
+  const out = {};
+  const props = schema?.properties || {};
+
+  for (const [key, raw] of Object.entries(values || {})) {
+    const def = props[key];
+    if (!def) {
+      const known = Object.keys(props);
+      errors.push(
+        `unknown setting "${key}"` +
+        (known.length ? ` — this profile accepts: ${known.join(", ")}` : "")
+      );
+      continue;
+    }
+    const { ok, value } = coerce(raw, def.type || "string");
+    if (!ok) {
+      errors.push(`"${key}" must be a ${def.type} — got "${raw}"`);
+      continue;
+    }
+    if (def.enum && !def.enum.includes(value)) {
+      errors.push(`"${key}" must be one of: ${def.enum.join(", ")} — got "${value}"`);
+      continue;
+    }
+    out[key] = value;
+  }
+
+  return { ok: errors.length === 0, errors, value: out };
+}

package/src/core/profiles/paths.js

@@ -0,0 +1,51 @@
+// Filesystem layout for installable profiles.
+//
+// Two layers, mirroring the agent vault (core/apc/parser.js):
+//   - BUNDLED → src/core/profiles/bundled/<id>/, shipped with APX, read-only.
+//   - USER    → ~/.apx/profiles/<id>/, installed from a local path, plus
+//               copy-on-write overrides of a bundled package.
+//   - REMOVED → ~/.apx/profiles/.removed.json, tombstones for bundled ids the
+//               user uninstalled (a bundled package can't be deleted).
+//
+// Bundled packages live under src/ rather than assets/ on purpose: package.json
+// `files` ships src/, skills/ and README.md only, so anything under assets/ is
+// absent from an npm install. See docs-internal/secretary/00-findings.md § A.
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { APX_HOME } from "../config/paths.js";
+
+const __profilesDir = path.dirname(fileURLToPath(import.meta.url));
+
+/** Packages shipped with APX. Read-only on the user's machine. */
+export const BUNDLED_PROFILES_DIR = path.join(__profilesDir, "bundled");
+
+/** The user's own packages and overrides. */
+export const PROFILES_DIR = path.join(APX_HOME, "profiles");
+
+/** Tombstones — bundled ids the user removed. */
+export const PROFILES_TOMBSTONE_PATH = path.join(PROFILES_DIR, ".removed.json");
+
+export const MANIFEST_FILE = "profile.json";
+export const PROMPT_FILE = "PROFILE.md";
+export const CONFIG_SCHEMA_FILE = "config.schema.json";
+
+/** Ids are slugs: lowercase, digits, dashes. Keeps them safe as path segments. */
+export const PROFILE_ID_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+export function bundledProfileDir(id) {
+  return path.join(BUNDLED_PROFILES_DIR, id);
+}
+
+export function userProfileDir(id) {
+  return path.join(PROFILES_DIR, id);
+}
+
+/**
+ * Language-specific prompt filename: PROFILE.es.md, PROFILE.pt-BR.md, …
+ * `null`/"en" means the base PROFILE.md.
+ */
+export function promptFileFor(lang) {
+  const code = String(lang || "").trim();
+  if (!code || code.toLowerCase() === "en") return PROMPT_FILE;
+  return `PROFILE.${code}.md`;
+}

package/src/core/profiles/store.js

@@ -0,0 +1,184 @@
+// Profile package resolution — the layered read.
+//
+// This mirrors readVaultAgents() in core/apc/parser.js: bundled and user
+// packages are resolved at READ time, user wins per id, tombstones hide bundled
+// ids the user removed. Nothing is copied at install time.
+//
+// That distinction matters. If installing a bundled profile copied it into
+// ~/.apx/profiles/, the user would be frozen at that version forever — a later
+// `npm update` would ship an improved PROFILE.md that their copy shadows. So a
+// user-layer directory exists only when the user genuinely owns that package:
+// they installed it from a local path, or they explicitly ejected a bundled one
+// to edit it.
+//
+// The user's *settings* are not part of the package. They live in
+// ~/.apx/config.json under `profile.config`, so they survive package updates,
+// `off` → `use` round-trips, and uninstall/reinstall.
+import fs from "node:fs";
+import path from "node:path";
+
+import {
+  BUNDLED_PROFILES_DIR,
+  PROFILES_DIR,
+  PROFILES_TOMBSTONE_PATH,
+  MANIFEST_FILE,
+  CONFIG_SCHEMA_FILE,
+  PROFILE_ID_RE,
+  bundledProfileDir,
+  userProfileDir,
+  promptFileFor,
+} from "./paths.js";
+import { schemaDefaults } from "./manifest.js";
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readDirIds(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && PROFILE_ID_RE.test(e.name))
+    .map((e) => e.name)
+    .sort();
+}
+
+// --------------------- tombstones -------------------------------------------
+
+export function readProfileTombstones() {
+  const raw = readJson(PROFILES_TOMBSTONE_PATH);
+  return new Set(Array.isArray(raw?.ids) ? raw.ids : []);
+}
+
+export function writeProfileTombstones(ids) {
+  fs.mkdirSync(PROFILES_DIR, { recursive: true });
+  fs.writeFileSync(
+    PROFILES_TOMBSTONE_PATH,
+    JSON.stringify({ ids: [...ids].sort() }, null, 2) + "\n"
+  );
+}
+
+// --------------------- resolution -------------------------------------------
+
+/**
+ * Where a profile's files actually come from, honouring the layering.
+ * @returns {{ dir: string, source: "user"|"user-override"|"bundled" }|null}
+ */
+export function resolveProfileDir(id) {
+  if (!PROFILE_ID_RE.test(String(id || ""))) return null;
+
+  const user = userProfileDir(id);
+  const bundled = bundledProfileDir(id);
+  const hasUser = fs.existsSync(path.join(user, MANIFEST_FILE));
+  const hasBundled = fs.existsSync(path.join(bundled, MANIFEST_FILE));
+
+  if (hasUser) return { dir: user, source: hasBundled ? "user-override" : "user" };
+  if (hasBundled) return { dir: bundled, source: "bundled" };
+  return null;
+}
+
+/**
+ * Load one profile package.
+ * @returns {{
+ *   id, dir, source, manifest, schema, defaults, prompts: string[]
+ * }|null}
+ */
+export function readProfile(id) {
+  const resolved = resolveProfileDir(id);
+  if (!resolved) return null;
+
+  const manifest = readJson(path.join(resolved.dir, MANIFEST_FILE));
+  if (!manifest) return null;
+
+  const schema = readJson(path.join(resolved.dir, CONFIG_SCHEMA_FILE));
+  const prompts = fs.existsSync(resolved.dir)
+    ? fs.readdirSync(resolved.dir).filter((f) => /^PROFILE(\.[\w-]+)?\.md$/.test(f)).sort()
+    : [];
+
+  return {
+    id,
+    dir: resolved.dir,
+    source: resolved.source,
+    manifest: { ...manifest, id: manifest.id || id },
+    schema,
+    defaults: schemaDefaults(schema),
+    prompts,
+  };
+}
+
+/**
+ * Every profile visible to the user: bundled ∪ user, user wins, tombstones
+ * filtered out.
+ */
+export function listProfiles({ includeRemoved = false } = {}) {
+  const tombstones = readProfileTombstones();
+  const ids = new Set([...readDirIds(BUNDLED_PROFILES_DIR), ...readDirIds(PROFILES_DIR)]);
+
+  const out = [];
+  for (const id of [...ids].sort()) {
+    if (!includeRemoved && tombstones.has(id)) continue;
+    const profile = readProfile(id);
+    if (profile) out.push({ ...profile, removed: tombstones.has(id) });
+  }
+  return out;
+}
+
+/**
+ * Resolve the prompt file for a language, falling back to the base PROFILE.md.
+ * Returns the file path, or null when the package has no prompt at all.
+ */
+export function resolvePromptFile(profileDir, lang) {
+  const candidates = [promptFileFor(lang)];
+
+  // "pt-BR" → also try "pt" before giving up on the base file.
+  const base = String(lang || "").split("-")[0];
+  if (base && base !== lang) candidates.push(promptFileFor(base));
+  candidates.push(promptFileFor("en"));
+
+  for (const name of candidates) {
+    const file = path.join(profileDir, name);
+    if (fs.existsSync(file)) return file;
+  }
+  return null;
+}
+
+// --------------------- active profile state ---------------------------------
+
+/**
+ * The activation record from global config. Shape:
+ *   { active: string|null, config: object, installed_at: string, version: string }
+ *
+ * A missing key, or `active: null`, means vanilla — and vanilla is the default
+ * of a clean install.
+ */
+export function readProfileState(globalConfig) {
+  const p = globalConfig?.profile;
+  if (!p || typeof p !== "object") return { active: null, config: {} };
+  return {
+    active: p.active || null,
+    config: p.config && typeof p.config === "object" ? p.config : {},
+    installed_at: p.installed_at || null,
+    version: p.version || null,
+  };
+}
+
+/** The profile package that is currently active, or null. */
+export function readActiveProfile(globalConfig) {
+  const { active } = readProfileState(globalConfig);
+  if (!active) return null;
+  return readProfile(active);
+}
+
+/**
+ * Effective settings for a profile: schema defaults with the user's saved
+ * values layered on top. Callers render prompts from this, never from the raw
+ * saved config — a package that gains a new setting must not leave a hole.
+ */
+export function effectiveProfileConfig(profile, globalConfig) {
+  const saved = readProfileState(globalConfig).config || {};
+  return { ...(profile?.defaults || {}), ...saved };
+}

package/src/core/runtime-skills/apx-profile/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: apx-profile
+description: Agent profiles — installable lines of work for the super-agent (secretary, project manager, analyst, tutor). Load when the user wants to install, activate, configure, diagnose or remove one, or asks why the agent behaves the way it does. Triggers: 'install a profile', 'apx profile', 'what profiles are there', 'activate the secretary', 'go back to vanilla', 'change my agent's schedule', 'why does it message me'.
+---
+
+# apx-profile
+
+A **profile** is an installable package that gives the super-agent a line of work: a
+prompt block, its own routines, and the white-label settings the owner fills in. With no
+profile active APX is *vanilla* — the system prompt is byte-identical to a clean install.
+
+Three words that are easy to confuse. Keep them apart:
+
+| Term | What it is | Where it lives |
+|---|---|---|
+| **profile** | an installable line of work (this skill) | `~/.apx/profiles/`, `config.profile` |
+| **persona** | the super-agent's visible NAME | `~/.apx/identity.json` → `agent_name` |
+| project config | per-project overrides | `.apc/config.json` |
+
+Installing and activating are **different operations**. `install` validates a package and
+makes it reachable; `use` is the moment behaviour changes.
+
+## Concrete CLI calls
+
+```bash
+# Discover
+apx profile list                      # everything available, and which is active
+apx profile show secretary            # settings, token cost, where it came from
+apx profile show secretary --preview  # ...plus the rendered prompt block
+
+# Install and activate
+apx profile install secretary         # a bundled id
+apx profile install ./my-profile      # a local package directory
+apx profile use secretary             # activates + installs its routines
+apx profile use tutor --force         # replace whatever is active
+
+# Configure — this is where white-label happens
+apx profile config                                  # show current settings
+apx profile config --set day_open_at="30 8 * * 1-5"
+apx profile config --set nudge_budget_per_day=3 --set quiet_hours=22:00-07:30
+apx profile config --interactive                    # walk the whole schema
+
+# Health and removal
+apx profile doctor                    # what's missing for it to do its job
+apx profile off                       # back to vanilla
+apx profile uninstall secretary
+```
+
+## What each command actually does
+
+- **`install`** validates the manifest, the schema and every template, then seeds the
+  settings with the schema defaults. It does **not** activate. A **local path** is copied
+  into `~/.apx/profiles/`; a **bundled** package is not — it is read in place so a later
+  `npm update` improves it instead of being shadowed by a stale copy.
+- **`use`** writes `config.profile.active`, reloads the prompt, and installs the package's
+  routines (named `<profile-id>-<routine>`, marked `origin: "profile:<id>"`).
+- **`off`** sets `active: null` and **disables** those routines. It deletes nothing —
+  settings, tasks, commitments and memory all survive, so `use` again restores everything.
+- **`config`** validates against the schema and **really reschedules**: changing an opening
+  time moves the cron, it doesn't just edit JSON.
+- **`uninstall`** removes the package and the routines it installed, but **keeps any routine
+  the user edited** and never touches one the user wrote. A bundled package can't be
+  deleted, so it gets a tombstone and can be reinstalled any time.
+
+## Settings are per profile
+
+`config.profile.configs[<id>]` holds each profile's own settings; `config.profile.config`
+mirrors the active one. Switching A → B → A gives A its settings back rather than handing
+it B's.
+
+## When the user asks "why did it message me?"
+
+Read the active profile's prompt block — `apx profile show <id> --preview` — and its
+settings. Interruption budgets, quiet hours and staleness thresholds are all profile
+settings, not core behaviour. If the answer is "it shouldn't have", the fix is usually
+`apx profile config`, not a code change.
+
+## Package layout
+
+```
+<id>/
+  profile.json            # manifest: id, name, version, requires, prompt_budget_tokens
+  PROFILE.md              # the always-on prompt block (template)
+  PROFILE.es.md           # optional translations: PROFILE.<lang>.md
+  config.schema.json      # the white-label settings, every one with a default
+  channels/<ch>.md        # optional per-channel overlay, appended after the core file
+  routines/*.json         # routines it installs
+  agents/*.md             # specialists it adds to the vault
+  skills/<slug>/SKILL.md  # its own operational procedures
+```
+
+**Template rules, enforced at install time** (installation fails, naming the variable):
+
+- Only flat `{{single_word}}` names. `{{profile.name}}` cannot be substituted and is rejected.
+- Every variable must resolve: a built-in (`owner_name`, `agent_name`, `owner_context`,
+  `profile_name`) or a schema property **with a default**. A property declared without a
+  default is rejected, because it would silently render as an empty string.
+
+## Channel overlays
+
+`channels/<ch>.md` is rendered and appended after the core `channels/<ch>.md`, only on that
+surface. Use it for judgement that must load deterministically where a decision is taken —
+the rules for speaking unprompted belong in `channels/routine.md`, not in an on-demand
+skill, because "should I interrupt?" is a decision the model may not know it is about to
+take. Costs nothing on the channels that don't need it.
+
+## The prompt budget is real
+
+The block ships on **every turn of every channel**, on top of a ~2.5k-token base. A
+package declares `prompt_budget_tokens`; exceeding it warns, exceeding 1.5× fails to
+install. Check the real number with `apx profile show <id>` or
+`node scripts/inspect-channel-prompts.js`.
+
+## HTTP
+
+`GET /profiles` · `GET /profiles/:id` (includes `preview`) · `GET /profiles/doctor` ·
+`POST /profiles/install` · `POST /profiles/use` · `POST /profiles/off` ·
+`PATCH /profiles/config` · `DELETE /profiles/:id`
+
+## Gotchas
+
+- **`install` does not activate.** The most common confusion. Follow it with `use`.
+- **One profile at a time.** Activating a second needs `--force`.
+- **`off` is not `uninstall`.** `off` is reversible and keeps everything.
+- **The vanilla invariant is load-bearing.** With no profile active the prompt must stay
+  byte-identical. If a change would alter that, it's a bug, not a feature.

package/src/core/stores/routines.js

@@ -138,7 +138,7 @@ export function getRoutine(projectPath, name) {
   return readFile(projectPath).find((r) => r.name === name) || null;
 }
 
-export function upsertRoutine(storagePath, { name, kind, schedule, spec, enabled = true, permission_mode, allowed_tools, pre_commands, post_commands, skip_prompt_on }) {
+export function upsertRoutine(storagePath, { name, kind, schedule, spec, enabled = true, permission_mode, allowed_tools, pre_commands, post_commands, skip_prompt_on, origin, origin_hash }) {
   if (!name || !kind || !schedule) throw new Error("routine requires name, kind, schedule");
   const now = nowIso();
   const routines = readFile(storagePath);
@@ -166,6 +166,14 @@ export function upsertRoutine(storagePath, { name, kind, schedule, spec, enabled
     //   "always"      — never run the LLM (shell-only routine)
     //   "never"       — always run the LLM regardless of pre_commands
     skip_prompt_on: skip_prompt_on || prev?.skip_prompt_on || "signal",
+    // Provenance. A routine installed by a persona package carries
+    // origin: "persona:<id>" so it can be disabled or removed with that
+    // package without touching the user's own routines. `origin_hash` is the
+    // hash of the spec as the package rendered it: when the record no longer
+    // matches, the user has edited it and the package must never overwrite or
+    // delete it again.
+    origin: origin ?? prev?.origin ?? null,
+    origin_hash: origin_hash ?? prev?.origin_hash ?? null,
     enabled: enabled !== false,
     last_run_at: prev?.last_run_at ?? null,
     last_status: prev?.last_status ?? null,