@agentprojectcontext/apx 1.80.2 → 1.89.1

package/src/core/agent/skills/media.js

@@ -0,0 +1,121 @@
+// A skill can carry images (a golf grip, a swing position, a diagram) so an
+// agent can SEND you the right one when it teaches a concept, and — on demand —
+// LOOK at one itself. The model never gets the pixels for free: what rides in
+// the prompt is a cheap text manifest (id → caption). The agent picks an id and
+// attaches it to its message (attach_media), or pulls it into its own context
+// to reason about (view_media).
+//
+// Where the files live:
+//   • dir-style skill  (~/.apx/skills/<slug>/SKILL.md)  → alongside SKILL.md
+//   • flat-style skill (<proj>/.apc/skills/<slug>.md)   → a sibling <slug>/ dir
+// A `media.json` in that dir is the manifest; without one, image files in the
+// dir are auto-listed (id = filename without extension, no caption).
+import fs from "node:fs";
+import path from "node:path";
+
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".svg"]);
+
+const MIME_BY_EXT = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+  ".svg": "image/svg+xml",
+};
+
+/** The asset directory for a resolved skill file (see file header). */
+export function skillAssetsDir(skillFile) {
+  if (!skillFile) return "";
+  const base = path.basename(skillFile);
+  if (base.toLowerCase() === "skill.md") return path.dirname(skillFile);
+  // flat "<slug>.md" → sibling "<slug>/"
+  return skillFile.replace(/\.md$/i, "");
+}
+
+function mimeFor(file) {
+  return MIME_BY_EXT[path.extname(file).toLowerCase()] || "application/octet-stream";
+}
+
+function isImage(file) {
+  return IMAGE_EXT.has(path.extname(file).toLowerCase());
+}
+
+/**
+ * The media a skill declares (or that simply sit in its asset dir).
+ *
+ * @param {{slug:string, file:string}} skill  a loadSkill() result (needs .file)
+ * @returns {Array<{id, file, path, caption, mime, exists}>}
+ */
+export function readSkillMedia(skill) {
+  const dir = skillAssetsDir(skill?.file);
+  if (!dir || !fs.existsSync(dir)) return [];
+
+  const items = [];
+  const seen = new Set();        // ids already taken
+  const seenFiles = new Set();   // basenames already claimed by the manifest
+
+  // 1) explicit manifest
+  const manifestPath = path.join(dir, "media.json");
+  if (fs.existsSync(manifestPath)) {
+    let manifest = [];
+    try { manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8")); } catch { manifest = []; }
+    const list = Array.isArray(manifest) ? manifest : Array.isArray(manifest?.media) ? manifest.media : [];
+    for (const raw of list) {
+      if (!raw || typeof raw !== "object") continue;
+      const file = String(raw.file || raw.path || "").trim();
+      if (!file) continue;
+      const id = String(raw.id || file.replace(/\.[^.]+$/, "")).trim();
+      if (seen.has(id)) continue;
+      seen.add(id);
+      seenFiles.add(path.basename(file));
+      const abs = path.isAbsolute(file) ? file : path.join(dir, file);
+      items.push({
+        id,
+        file: path.basename(file),
+        path: abs,
+        caption: String(raw.caption || raw.when || raw.description || "").trim(),
+        mime: raw.mime || mimeFor(file),
+        exists: fs.existsSync(abs),
+      });
+    }
+  }
+
+  // 2) auto-discover any image files not already in the manifest
+  let entries = [];
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { entries = []; }
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    if (!isImage(e.name)) continue;
+    if (seenFiles.has(e.name)) continue; // already described by the manifest
+    const id = e.name.replace(/\.[^.]+$/, "");
+    if (seen.has(id)) continue;
+    seen.add(id);
+    const abs = path.join(dir, e.name);
+    items.push({
+      id,
+      file: e.name,
+      path: abs,
+      caption: "",
+      mime: mimeFor(e.name),
+      exists: true,
+    });
+  }
+
+  return items;
+}
+
+/** A one-line-per-image manifest for the system prompt / read_skill result. */
+export function renderMediaManifest(media) {
+  const usable = (media || []).filter((m) => m.exists);
+  if (!usable.length) return "";
+  const lines = usable.map((m) => `- ${m.id}${m.caption ? ` — ${m.caption}` : ""}`);
+  return ["Images available (attach with attach_media, inspect with view_media):", ...lines].join("\n");
+}
+
+/** Resolve one media item by id within a list. */
+export function findMedia(media, id) {
+  const want = String(id || "").trim();
+  return (media || []).find((m) => m.id === want) || null;
+}

package/src/core/agent/skills/origin.js

@@ -0,0 +1,61 @@
+// Where a skill's files actually live — APX may only hold a symlink.
+//
+// `source` is the APX layer (builtin / global / project). `origin` is the
+// host that owns the bytes: claude, cursor, codex, agents, or APX itself.
+// The UI badge uses origin so a linked-in Claude skill does not look like
+// "you wrote this in ~/.apx/skills".
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const SKILL_ORIGIN_HOSTS = Object.freeze([
+  ["claude", [".claude", "skills"]],
+  ["cursor", [".cursor", "skills"]],
+  ["codex", [".codex", "skills"]],
+  ["agents", [".agents", "skills"]],
+]);
+
+function realOrResolve(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+
+function homeRelLiteral(p, home) {
+  const abs = path.resolve(p);
+  const root = path.resolve(home);
+  if (abs === root) return "~";
+  if (abs.startsWith(root + path.sep)) return "~" + abs.slice(root.length);
+  return abs;
+}
+
+export function homeRel(p, home = os.homedir()) {
+  const abs = realOrResolve(p);
+  const root = realOrResolve(home);
+  if (abs === root) return "~";
+  if (abs.startsWith(root + path.sep)) return "~" + abs.slice(root.length);
+  return abs;
+}
+
+/**
+ * @param {string} file  path to SKILL.md (or a flat <slug>.md)
+ * @param {{ source?: string, home?: string }} [opts]
+ * @returns {{ origin: string, origin_path: string, file_path: string }}
+ */
+export function skillOrigin(file, { source, home = os.homedir() } = {}) {
+  const filePath = homeRelLiteral(file, home);
+  if (source === "builtin") return { origin: "apx", origin_path: filePath, file_path: filePath };
+  if (source === "project") return { origin: "project", origin_path: filePath, file_path: filePath };
+
+  let realFile = file;
+  try { realFile = fs.realpathSync(file); } catch { /* broken link — fall through */ }
+  const originPath = homeRel(realFile, home);
+  const realDir = path.dirname(realOrResolve(realFile));
+
+  for (const [origin, segs] of SKILL_ORIGIN_HOSTS) {
+    const host = path.resolve(home, ...segs);
+    const hostReal = fs.existsSync(host) ? realOrResolve(host) : host;
+    if (realDir === hostReal || realDir.startsWith(hostReal + path.sep)) {
+      return { origin, origin_path: originPath, file_path: filePath };
+    }
+  }
+  return { origin: "global", origin_path: originPath, file_path: filePath };
+}

package/src/core/agent/skills/sections.js

@@ -0,0 +1,136 @@
+// Splitting a skill body into sections, so a large skill can be loaded one
+// section at a time instead of whole (progressive disclosure). A project agent
+// gets the skill's OUTLINE (its headings) in the system prompt for ~nothing,
+// and pulls the one section it needs with the read_skill tool.
+//
+// Sectioning is by markdown headings. A heading owns everything under it until
+// the next heading at the SAME or a HIGHER level — so a `##` section carries
+// its `###` subsections with it, which is what a reader wants when they ask for
+// "section 2".
+
+const HEADING_RE = /^(#{1,6})\s+(.+?)\s*#*$/;
+
+/**
+ * Parse a markdown body into a flat list of headings with their span.
+ * @returns {Array<{level:number, title:string, line:number}>}
+ */
+function headings(body) {
+  const lines = String(body || "").split("\n");
+  const out = [];
+  let inFence = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    // Don't mistake a `#` inside a ``` code fence for a heading.
+    if (/^\s*(```|~~~)/.test(line)) { inFence = !inFence; continue; }
+    if (inFence) continue;
+    const m = HEADING_RE.exec(line);
+    if (m) out.push({ level: m[1].length, title: m[2].trim(), line: i });
+  }
+  return out;
+}
+
+/**
+ * Sections of a skill body: each heading plus the text it owns (down to the
+ * next heading at the same or higher level). Text BEFORE the first heading is
+ * returned as a leading section with an empty title (the skill's preamble).
+ *
+ * @returns {Array<{level:number, title:string, text:string}>}
+ */
+export function splitSkillSections(body) {
+  const text = String(body || "");
+  const lines = text.split("\n");
+  const heads = headings(text);
+  const sections = [];
+
+  if (!heads.length) {
+    const t = text.trim();
+    return t ? [{ level: 0, title: "", text: t }] : [];
+  }
+
+  // Preamble before the first heading.
+  if (heads[0].line > 0) {
+    const pre = lines.slice(0, heads[0].line).join("\n").trim();
+    if (pre) sections.push({ level: 0, title: "", text: pre });
+  }
+
+  for (let i = 0; i < heads.length; i++) {
+    const h = heads[i];
+    // The section ends at the next heading whose level is <= this one's.
+    let end = lines.length;
+    for (let j = i + 1; j < heads.length; j++) {
+      if (heads[j].level <= h.level) { end = heads[j].line; break; }
+    }
+    sections.push({
+      level: h.level,
+      title: h.title,
+      text: lines.slice(h.line, end).join("\n").trim(),
+    });
+  }
+  return sections;
+}
+
+/**
+ * A compact outline for the system prompt: the top-level headings (levels 1-2),
+ * numbered, so the model can name a section to read_skill without the bodies.
+ * @returns {string[]}  e.g. ["1. Evaluaciones de Habilidad", "2. Técnica del Swing"]
+ */
+export function skillOutline(body, { maxLevel = 2 } = {}) {
+  return splitSkillSections(body)
+    .filter((s) => s.title && s.level >= 1 && s.level <= maxLevel)
+    .map((s) => s.title);
+}
+
+function norm(s) {
+  return String(s || "")
+    .toLowerCase()
+    .normalize("NFD")
+    .replace(/[̀-ͯ]/g, "")
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+/**
+ * Find the section a `query` refers to. Accepts a title (fuzzy, accent- and
+ * case-insensitive), a leading section number ("2" or "2."), or a substring of
+ * a title. Returns the best section, or null.
+ *
+ * @returns {{title:string, text:string, level:number}|null}
+ */
+export function pickSkillSection(body, query) {
+  const sections = splitSkillSections(body).filter((s) => s.title);
+  if (!sections.length) return null;
+  const q = norm(query);
+  if (!q) return null;
+
+  // "2" / "2." → the section whose title starts with that number, else the Nth.
+  const numMatch = /^(\d+)\.?$/.exec(String(query).trim());
+  if (numMatch) {
+    const n = numMatch[1];
+    const byPrefix = sections.find((s) => new RegExp(`^${n}\\b`).test(s.title.trim()));
+    if (byPrefix) return byPrefix;
+    const idx = Number(n) - 1;
+    if (idx >= 0 && idx < sections.length) return sections[idx];
+  }
+
+  // Exact normalized title.
+  const exact = sections.find((s) => norm(s.title) === q);
+  if (exact) return exact;
+
+  // Query contained in a title, or a title contained in the query.
+  const contains = sections.find((s) => {
+    const t = norm(s.title);
+    return t.includes(q) || q.includes(t);
+  });
+  if (contains) return contains;
+
+  // Token overlap — pick the title sharing the most words with the query.
+  const qTokens = new Set(q.split(" ").filter(Boolean));
+  let best = null;
+  let bestScore = 0;
+  for (const s of sections) {
+    const tTokens = s.title ? norm(s.title).split(" ").filter(Boolean) : [];
+    const score = tTokens.reduce((n, tok) => n + (qTokens.has(tok) ? 1 : 0), 0);
+    if (score > bestScore) { bestScore = score; best = s; }
+  }
+  return bestScore > 0 ? best : null;
+}

package/src/core/agent/super-agent.js

@@ -13,7 +13,9 @@ import {
 import { resolveAgentName } from "#core/identity/index.js";
 import { memoryBlockFor, buildActiveThreadsBlock } from "#core/memory/index.js";
 import { CHANNELS } from "#core/constants/channels.js";
-import { judgeConfig, judgeCompletion, applyJudgeLoop } from "#core/agent/judge.js";
+import { judgeConfig, judgeCompletion, applyJudgeLoop, continuableTurn } from "#core/agent/judge.js";
+import { channelToolIters, MAX_TOOL_ITERS } from "#core/agent/constants.js";
+import { mobilityContextBlock } from "#core/mobility/state.js";
 
 export {
   buildIdentityBlock,
@@ -39,6 +41,7 @@ export async function runSuperAgent({
   onEvent = null,
   signal,
   onToken = null,
+  onReasoningToken = null,
   suppressTools = null,
   // Channel-specific addendum appended to the system prompt; used by
   // voice.js to ask for trailing ```suggestions``` JSON on voice/deck
@@ -46,12 +49,19 @@ export async function runSuperAgent({
   systemSuffix = "",
   // Per-reply output cap; forwarded to runAgent. Summarize/ask raise it.
   maxTokens,
-  // Max tool-loop iterations; forwarded to runAgent. The Code module raises
-  // this so coding tasks run to completion instead of stopping after a step.
+  // Max tool-loop iterations for the TURN — the first run plus any judge round
+  // that continues it, which share this number rather than each getting it in
+  // full. Forwarded to runAgent; the Code module raises it so coding tasks run
+  // to completion instead of stopping after a step. Left unset, the channel
+  // decides (channelToolIters): the web chat runs to completion, everything
+  // else keeps runAgent's conversational default.
   maxIters,
   // Structural "keep going until done" contract (finish tool + forced tool
   // choice). Coding surfaces (web Code build mode, terminal Build) turn this on.
   completionContract = false,
+  // The completion judge, injectable so a test can supply verdicts without an
+  // engine. Production always uses the real one.
+  judgeCompletionFn = judgeCompletion,
   // Run tool-free: pure text generation, no tool registry. Used by the
   // summarize/ask endpoint so a transcript that *mentions* a tool (e.g. the
   // telegram plugin) can't make the model actually fire it.
@@ -115,11 +125,13 @@ export async function runSuperAgent({
   const scopedListSkills = (opts = {}) =>
     filterEnabledSkills(listSkills(opts), { config: globalConfig, projectPath });
 
+  const mobilityBlock = mobilityContextBlock();
+  const effectiveContextNote = [contextNote, mobilityBlock].filter(Boolean).join("\n\n");
   const system = buildSuperAgentSystem({
     globalConfig,
     projects,
     listSkills: scopedListSkills,
-    contextNote,
+    contextNote: effectiveContextNote,
     channel,
     channelMeta,
     relationshipBlock,
@@ -142,7 +154,19 @@ export async function runSuperAgent({
     ? null
     : selectModelByRules({ prompt, previousMessages, channel, channelMeta }, globalConfig);
 
-  const runOnce = (turnPrompt, history) =>
+  // An explicit budget from the caller always wins; otherwise the surface's own
+  // default applies. This is where the web chat stops hitting a wall every 9
+  // actions and asking whether to keep going — see WEB_TOOL_ITERS.
+  //
+  // Resolved to a NUMBER here, falling through to runAgent's own default rather
+  // than leaving it unset, because this is the turn's total and the judge loop
+  // below has to subtract from it. "Whatever runAgent picks" is not a total you
+  // can share between rounds.
+  const turnMaxIters = maxIters || channelToolIters(globalConfig, channel) || MAX_TOOL_ITERS;
+
+  // `iters` is what THIS pass may spend, which is the whole budget for the
+  // first run and whatever is left for a judge round.
+  const runOnce = (turnPrompt, history, iters = turnMaxIters) =>
     runAgent({
       globalConfig,
       system,
@@ -157,21 +181,34 @@ export async function runSuperAgent({
       onEvent,
       signal,
       onToken,
+      onReasoningToken,
       agentName: resolveAgentName(globalConfig),
       suppressTools,
       ...(maxTokens ? { maxTokens } : {}),
-      ...(maxIters ? { maxIters } : {}),
+      maxIters: iters,
       ...(completionContract ? { completionContract: true } : {}),
     });
 
   const result = await runOnce(prompt, previousMessages);
 
-  // Goal-completion judge (OpenHands critic pattern): opt-in, and only where
-  // "done" is a checkable claim — completion-contract turns at the top level.
-  // Sub-agent runs are excluded (the parent already judges the overall turn);
-  // tool-free callers (summarize/ask) have nothing to verify.
+  // Goal-completion judge (OpenHands critic pattern). Two doors into it:
+  //
+  //   - a completion-contract turn declared itself done, and `judge.enabled`
+  //     asks for that claim to be checked;
+  //   - a conversational turn stopped calling tools, which is also what the
+  //     model does when it just announces its next step. That reads as a task
+  //     that quit halfway, so the judge continues it instead of leaving the
+  //     user to type "seguí". Skipped for chat and for a turn that ended asking
+  //     something — see continuableTurn.
+  //
+  // Sub-agent runs are excluded (the parent judges the overall turn); tool-free
+  // callers (summarize/ask) have nothing to verify; and an aborted turn is the
+  // user saying stop, which is the one instruction a judge must not overrule.
   const jCfg = judgeConfig(globalConfig);
-  if (!jCfg.enabled || !completionContract || noTools || subagentDepth > 0) {
+  const judging = completionContract
+    ? jCfg.enabled
+    : jCfg.continue_unfinished && continuableTurn(result);
+  if (!judging || noTools || subagentDepth > 0 || signal?.aborted) {
     return result;
   }
   // Rolling refinement history: each round sees the original goal, its own
@@ -181,10 +218,13 @@ export async function runSuperAgent({
     initialResult: result,
     cfg: jCfg,
     onEvent,
-    judgeFn: (r) => judgeCompletion({ goal: prompt, result: r, globalConfig }),
-    runFollowup: async (followup, prior) => {
+    // The turn's whole budget, shared with the run above rather than reissued
+    // per round. Without this the ceiling was (1 + max_iterations) × turnMaxIters.
+    maxIters: turnMaxIters,
+    judgeFn: (r) => judgeCompletionFn({ goal: prompt, result: r, globalConfig }),
+    runFollowup: async (followup, prior, { maxIters: roundIters } = {}) => {
       history.push({ role: "assistant", content: prior.text || "" });
-      const next = await runOnce(followup, [...history]);
+      const next = await runOnce(followup, [...history], roundIters);
       history.push({ role: "user", content: followup });
       return next;
     },

package/src/core/agent/tools/handlers/_calendar.js

@@ -0,0 +1,50 @@
+// Shared helpers for the calendar agent tools (calendar-*.js). Underscore file,
+// like _asana.js, so it carries no tool `name:` of its own: each tool stays a
+// thin adapter over the pure client in core/integrations/plugins/calendar.js.
+import { resolveProject } from "../helpers.js";
+import { resolveIntegration } from "#core/integrations/index.js";
+
+/**
+ * The effective calendar config for a project, or an error the model can act
+ * on. `calendar_id` is resolved here rather than in each tool: which calendar
+ * is a connection detail the owner picked once, not a decision to re-take on
+ * every call.
+ */
+export function resolveCalendar(projects, project, { needsWrite = false } = {}) {
+  const p = resolveProject(projects, project);
+  const resolved = resolveIntegration({ projectStorage: p.storagePath, slug: "calendar" });
+  if (!resolved) {
+    throw new Error(
+      "No calendar is connected. Ask the user to connect one in the web panel → Integrations → Plugins → Google Calendar.",
+    );
+  }
+  const config = resolved.record.config || {};
+  // Under user OAuth the calendar is always the account's own ("primary"); there
+  // is no calendar to pick. But we DO need an authorized connection.
+  if (!config.refresh_token) {
+    throw new Error(
+      "The calendar isn't authorized yet. Ask the user to connect it with Google in the web panel → Integrations → Google Calendar.",
+    );
+  }
+  const calendarId = config.calendar_id || "primary";
+  // Read-only is possible, and the agent finding out by way of a 403 from Google
+  // is a worse answer than being told here.
+  if (needsWrite && !config.write_access) {
+    throw new Error(
+      "This calendar is connected read-only. The user has to enable write access in the web panel → Integrations → Google Calendar before anything can be scheduled.",
+    );
+  }
+  return { config, calendarId, scope: resolved.scope };
+}
+
+/** The optional `project` arg every calendar tool accepts. */
+export const PROJECT_ARG = {
+  project: { type: "string", description: "APX project id/name (optional; defaults to current)" },
+};
+
+/** Default window: from now to the end of the day, in the machine's timezone. */
+export function todayWindow(now = new Date()) {
+  const end = new Date(now);
+  end.setHours(23, 59, 59, 999);
+  return { timeMin: now.toISOString(), timeMax: end.toISOString() };
+}

package/src/core/agent/tools/handlers/add-mcp.js

@@ -0,0 +1,103 @@
+import {
+  readApfMcps, writeApfMcps,
+  readRuntimeMcps, writeRuntimeMcps,
+  readGlobalMcps, writeGlobalMcps,
+} from "#core/mcp/sources.js";
+import { projectMeta, resolveProject } from "../helpers.js";
+
+// Register an MCP server. The super-agent could LIST mcps and CALL their tools
+// but not add one — so wiring a new MCP meant shelling out to `apx mcp add`,
+// the same gap that made building an agent painful. This closes it.
+//
+// Three scopes (see the apx-mcp skill), each a different file with different
+// commit/secrecy semantics:
+//   shared  → .apc/mcps.json  (committed; NON-SECRET hints only)
+//   runtime → ~/.apx/projects/<id>/mcps.json  (private; where SECRETS live)
+//   global  → ~/.apx/mcps.json  (private; every project)
+function readScope(scope, p) {
+  if (scope === "runtime") return readRuntimeMcps(p.storagePath);
+  if (scope === "global") return readGlobalMcps();
+  return readApfMcps(p.path);
+}
+function writeScope(scope, p, json) {
+  if (scope === "runtime") {
+    if (!p.storagePath) throw new Error("runtime scope requires a project with a storage path");
+    return writeRuntimeMcps(p.storagePath, json);
+  }
+  if (scope === "global") return writeGlobalMcps(json);
+  return writeApfMcps(p.path, json);
+}
+
+export default {
+  name: "add_mcp",
+  schema: {
+    type: "function",
+    function: {
+      name: "add_mcp",
+      description:
+        "Register (or update) an MCP server so its tools become callable via call_mcp. A stdio server needs `command` (+ optional `args`/`env`); a remote HTTP one needs `url` (+ optional `headers`). Scope decides WHERE it is stored and its secrecy: 'runtime' (default here — private, holds secrets), 'shared' (.apc/mcps.json, committed — NON-SECRET hints only, never a token), or 'global' (private, all projects). Put anything secret in runtime or global, never shared.",
+      parameters: {
+        type: "object",
+        required: ["name"],
+        properties: {
+          project: { type: "string", description: "Project id, name or path. Omit or 'default' for ~/.apx/projects/default." },
+          name:    { type: "string", description: "Server name (how you'll reference it in call_mcp)." },
+          command: { type: "string", description: "stdio: the executable to spawn (e.g. 'npx')." },
+          args:    { type: "array", items: { type: "string" }, description: "stdio: arguments for the command." },
+          env:     { type: "object", description: "stdio: environment variables { KEY: value }." },
+          url:     { type: "string", description: "http: the remote endpoint URL." },
+          headers: { type: "object", description: "http: request headers { Header: value }." },
+          scope:   { type: "string", enum: ["runtime", "shared", "global"], description: "Where to store it. Default: runtime." },
+          enabled: { type: "boolean", description: "Enable it now (default true)." },
+        },
+      },
+    },
+  },
+  makeHandler: ({ projects, registries, requirePermission }) => async (args = {}) => {
+    const { project, name, command, args: cmdArgs, env, url, headers, enabled } = args;
+    await requirePermission("add_mcp", { dangerous: true, args: { name, scope: args.scope } });
+    if (!name) return { error: "name required" };
+    if (!command && !url) return { error: "either command (stdio) or url (http) required" };
+    if (command && url) return { error: "pass either command (stdio) or url (http), not both" };
+
+    const scope = ["runtime", "shared", "global"].includes(args.scope) ? args.scope
+      : args.scope === "apc" ? "shared"
+      : args.scope ? null : "runtime";
+    if (scope === null) return { error: `unknown scope "${args.scope}" (use runtime|shared|global)` };
+
+    let p;
+    try {
+      p = resolveProject(projects, project || "default");
+    } catch (e) {
+      return { error: e.message };
+    }
+
+    try {
+      const json = readScope(scope, p);
+      json.mcpServers = json.mcpServers || {};
+      const existing = json.mcpServers[name] || {};
+      json.mcpServers[name] = {
+        ...existing,
+        ...(command !== undefined ? { command } : {}),
+        ...(cmdArgs !== undefined ? { args: cmdArgs } : {}),
+        ...(env !== undefined ? { env } : {}),
+        ...(url !== undefined ? { url } : {}),
+        ...(headers !== undefined ? { headers } : {}),
+        enabled: enabled === undefined ? true : !!enabled,
+      };
+      writeScope(scope, p, json);
+      registries?.evictName?.(name);
+      projects.rebuild(p.id);
+      return {
+        ok: true,
+        name,
+        scope,
+        transport: url ? "http" : "stdio",
+        project: projectMeta(projects, p),
+        hint: "Registered. Use list_mcp_tools to see what it exposes, then call_mcp to run a tool.",
+      };
+    } catch (e) {
+      return { error: e.message };
+    }
+  },
+};

package/src/core/agent/tools/handlers/asana-create-task.js

@@ -15,6 +15,7 @@ export default {
           name: { type: "string", description: "Task title" },
           notes: { type: "string", description: "Task description/notes" },
           project_gid: { type: "string", description: "Optional Asana project gid to add the task to" },
+          section_gid: { type: "string", description: "Optional Asana section gid to place the task in (e.g. a backlog column). Only valid together with project_gid." },
           assignee: { type: "string", description: "Optional assignee (user gid or 'me')" },
           due_on: { type: "string", description: "Optional due date (YYYY-MM-DD)" },
           ...PROJECT_ARG,
@@ -23,13 +24,14 @@ export default {
       },
     },
   },
-  makeHandler: ({ projects }) => async ({ project, name, notes, project_gid, assignee, due_on } = {}) => {
+  makeHandler: ({ projects }) => async ({ project, name, notes, project_gid, section_gid, assignee, due_on } = {}) => {
     const { token, config } = resolveAsana(projects, project);
     const task = await asana.createTask(token, {
       workspaceGid: requireWorkspace(config),
       name,
       notes,
       projectGid: project_gid,
+      sectionGid: section_gid,
       assignee,
       dueOn: due_on,
     });