@agentprojectcontext/apx 1.59.0 → 1.60.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentprojectcontext/apx",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "description": "APX — unified CLI + daemon for the Agent Project Context (APC) standard.",
   "publishConfig": {
     "access": "public"

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

@@ -0,0 +1,34 @@
+// Shared helpers for the Asana agent tools (asana-*.js). Kept in an underscore
+// file — like _git.js — so it holds no tool `name:` of its own. Each tool file
+// stays a thin adapter: resolve the project's effective Asana integration (its
+// own record wins over the default project's — see resolveIntegration), then
+// call the pure REST client in core/integrations/plugins/asana.js.
+import { resolveProject } from "../helpers.js";
+import { resolveIntegration } from "#core/integrations/index.js";
+
+// Resolve the active Asana token + config for a project, or throw a message the
+// model can act on (tell the user to connect Asana in the web panel).
+export function resolveAsana(projects, project) {
+  const p = resolveProject(projects, project);
+  const resolved = resolveIntegration({ projectStorage: p.storagePath, slug: "asana" });
+  if (!resolved) {
+    throw new Error(
+      "Asana is not connected for this project. Ask the user to connect it in the web panel → Integrations → Plugins → Asana.",
+    );
+  }
+  const config = resolved.record.config || {};
+  const token = config.personal_access_token;
+  if (!token) throw new Error("Asana integration has no token configured");
+  return { token, config, scope: resolved.scope };
+}
+
+export function requireWorkspace(config) {
+  const gid = config.workspace_gid;
+  if (!gid) throw new Error("No Asana workspace selected. Configure it in the web panel first.");
+  return gid;
+}
+
+// The optional `project` arg every Asana tool accepts (defaults to current).
+export const PROJECT_ARG = {
+  project: { type: "string", description: "APX project id/name (optional; defaults to current)" },
+};

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

@@ -0,0 +1,38 @@
+import * as asana from "#core/integrations/plugins/asana.js";
+import { resolveAsana, requireWorkspace, PROJECT_ARG } from "./_asana.js";
+
+export default {
+  name: "asana_create_task",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "asana_create_task",
+      description: "Create an Asana task in the connected workspace.",
+      parameters: {
+        type: "object",
+        properties: {
+          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" },
+          assignee: { type: "string", description: "Optional assignee (user gid or 'me')" },
+          due_on: { type: "string", description: "Optional due date (YYYY-MM-DD)" },
+          ...PROJECT_ARG,
+        },
+        required: ["name"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, name, notes, project_gid, assignee, due_on } = {}) => {
+    const { token, config } = resolveAsana(projects, project);
+    const task = await asana.createTask(token, {
+      workspaceGid: requireWorkspace(config),
+      name,
+      notes,
+      projectGid: project_gid,
+      assignee,
+      dueOn: due_on,
+    });
+    return { task };
+  },
+};

package/src/core/agent/tools/handlers/asana-list-projects.js

@@ -0,0 +1,19 @@
+import * as asana from "#core/integrations/plugins/asana.js";
+import { resolveAsana, requireWorkspace, PROJECT_ARG } from "./_asana.js";
+
+export default {
+  name: "asana_list_projects",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "asana_list_projects",
+      description: "List Asana projects in the connected workspace.",
+      parameters: { type: "object", properties: { ...PROJECT_ARG } },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project } = {}) => {
+    const { token, config } = resolveAsana(projects, project);
+    return { projects: await asana.listProjects(token, requireWorkspace(config)) };
+  },
+};

package/src/core/agent/tools/handlers/asana-list-tasks.js

@@ -0,0 +1,27 @@
+import * as asana from "#core/integrations/plugins/asana.js";
+import { resolveAsana, PROJECT_ARG } from "./_asana.js";
+
+export default {
+  name: "asana_list_tasks",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "asana_list_tasks",
+      description: "List tasks in an Asana project.",
+      parameters: {
+        type: "object",
+        properties: {
+          project_gid: { type: "string", description: "Asana project gid (from asana_list_projects)" },
+          completed: { type: "boolean", description: "Include completed tasks (default false)" },
+          ...PROJECT_ARG,
+        },
+        required: ["project_gid"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, project_gid, completed = false } = {}) => {
+    const { token } = resolveAsana(projects, project);
+    return { tasks: await asana.listTasks(token, project_gid, completed) };
+  },
+};

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

@@ -0,0 +1,32 @@
+import * as asana from "#core/integrations/plugins/asana.js";
+import { resolveAsana, PROJECT_ARG } from "./_asana.js";
+
+export default {
+  name: "asana_update_task",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "asana_update_task",
+      description: "Update an Asana task's fields (rename, complete, reschedule, reassign).",
+      parameters: {
+        type: "object",
+        properties: {
+          task_gid: { type: "string", description: "Asana task gid" },
+          name: { type: "string" },
+          notes: { type: "string" },
+          completed: { type: "boolean" },
+          due_on: { type: "string", description: "YYYY-MM-DD" },
+          assignee: { type: "string" },
+          ...PROJECT_ARG,
+        },
+        required: ["task_gid"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, task_gid, name, notes, completed, due_on, assignee } = {}) => {
+    const { token } = resolveAsana(projects, project);
+    const task = await asana.updateTask(token, task_gid, { name, notes, completed, dueOn: due_on, assignee });
+    return { task };
+  },
+};

package/src/core/agent/tools/names.js

@@ -50,6 +50,12 @@ export const TOOLS = Object.freeze({
   CALL_MCP:            "call_mcp",
   CALL_RUNTIME:        "call_runtime",
 
+  // Integrations — Asana plugin (see core/integrations/plugins/asana.js)
+  ASANA_LIST_PROJECTS: "asana_list_projects",
+  ASANA_LIST_TASKS:    "asana_list_tasks",
+  ASANA_CREATE_TASK:   "asana_create_task",
+  ASANA_UPDATE_TASK:   "asana_update_task",
+
   // Side-effects
   SEND_TELEGRAM:       "send_telegram",
   SET_IDENTITY:        "set_identity",
@@ -94,6 +100,10 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.CALL_AGENT,
   TOOLS.CALL_MCP,
   TOOLS.CALL_RUNTIME,
+  TOOLS.ASANA_LIST_PROJECTS,
+  TOOLS.ASANA_LIST_TASKS,
+  TOOLS.ASANA_CREATE_TASK,
+  TOOLS.ASANA_UPDATE_TASK,
   TOOLS.SEND_TELEGRAM,
   TOOLS.SET_IDENTITY,
   TOOLS.SET_PERMISSION_MODE,

package/src/core/agent/tools/registry.js

@@ -33,6 +33,10 @@ import gitStatus from "./handlers/git-status.js";
 import gitDiff from "./handlers/git-diff.js";
 import gitLog from "./handlers/git-log.js";
 import gitShow from "./handlers/git-show.js";
+import asanaListProjects from "./handlers/asana-list-projects.js";
+import asanaListTasks from "./handlers/asana-list-tasks.js";
+import asanaCreateTask from "./handlers/asana-create-task.js";
+import asanaUpdateTask from "./handlers/asana-update-task.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 import { TOOLS, CODE_CHANNEL_TOOLS } from "./names.js";
@@ -74,6 +78,13 @@ const NATIVE_TOOLS = [
   gitDiff,
   gitLog,
   gitShow,
+  // Integration plugin tools (Asana). Each carries its own `category`, so it
+  // lands in the "integrations" group of the discover_tools catalog and stays
+  // lazy on chat channels until activated.
+  asanaListProjects,
+  asanaListTasks,
+  asanaCreateTask,
+  asanaUpdateTask,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

package/src/core/integrations/catalog.js

@@ -0,0 +1,66 @@
+// Plugin catalog — the source of truth for which integration plugins exist and
+// which are wired end-to-end. The daemon API + web "Plugins" tab read this.
+//
+// A plugin is "implemented" when it has a service module in ./plugins/ that
+// satisfies the lifecycle contract (configure/validate/status/deactivate). The
+// rest are declared here with `coming_soon: true` so the Integrations page shows
+// the full roster (matching PandaProject) while remaining honest about what is
+// actually connectable. Adding a new plugin = drop a module in ./plugins/ and
+// register it in PLUGIN_SERVICES — no API or route changes (open/closed).
+import { asanaPlugin } from "./plugins/asana.js";
+
+// slug -> live plugin service (must implement the lifecycle contract).
+export const PLUGIN_SERVICES = Object.freeze({
+  asana: asanaPlugin,
+});
+
+// Static descriptors for the catalog UI. Implemented plugins derive their
+// metadata from the service module; coming-soon ones are declared inline.
+// `coming_soon` entries in PandaProject depend on domain/channel infrastructure
+// (GitHub outputs↔repos, a WhatsApp-Web bridge, Telegram-voice whisper) that
+// APX models differently — they are placeholders until ported natively.
+const COMING_SOON = [
+  {
+    slug: "github",
+    name: "GitHub",
+    type: "source_control",
+    description: "Vinculá repos, issues y PRs para que los agentes trabajen sobre tu código",
+    auth: "token",
+    coming_soon: true,
+  },
+  {
+    slug: "whatsapp",
+    name: "WhatsApp",
+    type: "channel",
+    description: "Conectá WhatsApp Web al orquestador — responde mensajes automáticamente",
+    auth: "qr",
+    coming_soon: true,
+  },
+  {
+    slug: "local-transcription",
+    name: "Transcripción Local",
+    type: "transcription",
+    description: "Transcripción de audio con faster-whisper local — sin depender de una API externa",
+    auth: "none",
+    coming_soon: true,
+  },
+];
+
+// The full catalog: implemented plugins first, then coming-soon.
+export function listCatalog() {
+  const implemented = Object.values(PLUGIN_SERVICES).map((p) => ({
+    slug: p.slug,
+    name: p.name,
+    type: p.type,
+    description: p.description,
+    auth: p.auth,
+    tools: p.tools || [],
+    coming_soon: false,
+  }));
+  return [...implemented, ...COMING_SOON];
+}
+
+// Resolve a live plugin service by slug (or null when not implemented).
+export function getPluginService(slug) {
+  return PLUGIN_SERVICES[slug] || null;
+}

package/src/core/integrations/index.js

@@ -0,0 +1,10 @@
+// Public surface of the integrations core module. Daemon + agent tools import
+// from here.
+export {
+  integrationsPath,
+  defaultIntegrationsStorage,
+  readIntegrations,
+  writeIntegrations,
+} from "./sources.js";
+export { IntegrationStore, resolveIntegration, redactRecord } from "./store.js";
+export { listCatalog, getPluginService, PLUGIN_SERVICES } from "./catalog.js";

package/src/core/integrations/plugins/asana.js

@@ -0,0 +1,231 @@
+// Asana integration plugin — ported from PandaProject's asana_service.py.
+//
+// Two halves:
+//   1. A thin Asana REST client (Personal Access Token auth) — pure HTTP, no
+//      knowledge of storage. Used by both the lifecycle below and the agent
+//      tools in core/agent/tools/handlers/asana.js.
+//   2. A plugin descriptor implementing the shared lifecycle contract
+//      (configure / validate / status / deactivate / actions) that the daemon
+//      API dispatches to. Lifecycle methods take a stored record and return a
+//      patch to persist — they never touch the filesystem themselves (SRP).
+//
+// Contract shared by every plugin (see catalog.js):
+//   configure(record, body)  -> { patch }                        (sync)
+//   validate(record)         -> Promise<{ patch, result }>       (async, hits API)
+//   status(record)           -> statusObject                     (sync, pure)
+//   deactivate(record)       -> { patch }                        (sync)
+//   actions: { <name>(record) -> Promise<any> }                  (async reads)
+
+const ASANA_API_BASE = "https://app.asana.com/api/1.0";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+// ─── HTTP helpers ────────────────────────────────────────────────────────────
+
+function headers(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/json",
+    "Content-Type": "application/json",
+  };
+}
+
+async function request(token, method, apiPath, { params, payload } = {}) {
+  let url = `${ASANA_API_BASE}${apiPath}`;
+  if (params) {
+    const qs = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== null && v !== "") qs.set(k, String(v));
+    }
+    const s = qs.toString();
+    if (s) url += `?${s}`;
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  let res;
+  try {
+    res = await fetch(url, {
+      method,
+      headers: headers(token),
+      body: payload !== undefined ? JSON.stringify({ data: payload }) : undefined,
+      signal: controller.signal,
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    if (e.name === "AbortError") throw new Error("Asana request timed out");
+    throw new Error(`Asana request failed: ${e.message}`);
+  }
+  clearTimeout(timer);
+  if (!res.ok) {
+    let detail = `${res.status}`;
+    try {
+      const body = await res.json();
+      const first = Array.isArray(body?.errors) ? body.errors[0]?.message : null;
+      detail = first || JSON.stringify(body);
+    } catch {
+      /* non-JSON error body */
+    }
+    throw new Error(`Asana API ${res.status}: ${detail}`);
+  }
+  return res.json();
+}
+
+// ─── REST client (mirrors asana_service.py) ───────────────────────────────────
+
+export async function validateToken(token) {
+  const result = await request(token, "GET", "/users/me");
+  const user = result?.data || {};
+  if (!user.gid) throw new Error("Asana returned an empty user response");
+  return user;
+}
+
+export async function getWorkspaces(token) {
+  const result = await request(token, "GET", "/workspaces");
+  return result?.data || [];
+}
+
+export async function listProjects(token, workspaceGid) {
+  const result = await request(token, "GET", "/projects", {
+    params: { workspace: workspaceGid, opt_fields: "gid,name,color,archived,permalink_url" },
+  });
+  return result?.data || [];
+}
+
+export async function listTasks(token, projectGid, completed = false) {
+  const result = await request(token, "GET", `/projects/${projectGid}/tasks`, {
+    params: {
+      opt_fields: "gid,name,completed,due_on,assignee.name,notes,permalink_url",
+      completed_since: completed ? "" : "now",
+    },
+  });
+  return result?.data || [];
+}
+
+export async function createTask(token, { workspaceGid, name, notes = "", projectGid, assignee, dueOn } = {}) {
+  const payload = { name, workspace: workspaceGid };
+  if (notes) payload.notes = notes;
+  if (projectGid) payload.projects = [projectGid];
+  if (assignee) payload.assignee = assignee;
+  if (dueOn) payload.due_on = dueOn;
+  const result = await request(token, "POST", "/tasks", { payload });
+  return result?.data || {};
+}
+
+export async function updateTask(token, taskGid, { name, notes, completed, dueOn, assignee } = {}) {
+  const payload = {};
+  if (name !== undefined) payload.name = name;
+  if (notes !== undefined) payload.notes = notes;
+  if (completed !== undefined) payload.completed = completed;
+  if (dueOn !== undefined) payload.due_on = dueOn;
+  if (assignee !== undefined) payload.assignee = assignee;
+  const result = await request(token, "PUT", `/tasks/${taskGid}`, { payload });
+  return result?.data || {};
+}
+
+// ─── Plugin descriptor + lifecycle ────────────────────────────────────────────
+
+function safeToken(record) {
+  const token = record?.config?.personal_access_token || "";
+  if (!token) throw new Error("Asana token not configured");
+  return token;
+}
+
+export const asanaPlugin = {
+  slug: "asana",
+  name: "Asana",
+  type: "project_management",
+  description: "Conectá tu workspace de Asana para que los agentes creen, actualicen y consulten tareas",
+  auth: "token",
+  tools: [
+    { slug: "asana_list_projects", desc: "Listar proyectos del workspace" },
+    { slug: "asana_list_tasks", desc: "Listar tareas de un proyecto" },
+    { slug: "asana_create_task", desc: "Crear una tarea" },
+    { slug: "asana_update_task", desc: "Actualizar estado o campos de una tarea" },
+  ],
+
+  // Save the PAT and/or the target workspace. Returns a patch to persist.
+  configure(record, body = {}) {
+    const pat = (body.personal_access_token || "").trim();
+    const workspaceGid = (body.workspace_gid || "").trim();
+    if (!pat && !workspaceGid && !record) {
+      throw new Error("Provide personal_access_token or workspace_gid");
+    }
+    const config = {};
+    if (pat) config.personal_access_token = pat;
+    if (workspaceGid) config.workspace_gid = workspaceGid;
+    const patch = {
+      name: "Asana",
+      type: this.type,
+      description: this.description,
+      config,
+    };
+    // Saving a fresh token means the connection is not yet verified.
+    if (pat) patch.status = "pending_validation";
+    return { patch };
+  },
+
+  // Verify the PAT against Asana and resolve user + workspace metadata.
+  async validate(record) {
+    const token = safeToken(record);
+    let user;
+    try {
+      user = await validateToken(token);
+    } catch (e) {
+      return {
+        patch: { status: "error", is_enabled: false, config: { last_error: String(e.message || e) } },
+        result: { ok: false, error: String(e.message || e) },
+      };
+    }
+    const config = { user_name: user.name || null, user_email: user.email || null, last_error: null };
+    let workspaceGid = record?.config?.workspace_gid || null;
+    try {
+      const workspaces = await getWorkspaces(token);
+      if (workspaceGid) {
+        const match = workspaces.find((w) => w.gid === workspaceGid);
+        if (match) config.workspace_name = match.name;
+      } else if (workspaces.length === 1) {
+        // Auto-select when the token owner has exactly one workspace.
+        config.workspace_gid = workspaces[0].gid;
+        config.workspace_name = workspaces[0].name;
+        workspaceGid = workspaces[0].gid;
+      }
+    } catch {
+      /* workspace resolution is best-effort */
+    }
+    return {
+      patch: { status: "active", is_enabled: true, config },
+      result: {
+        ok: true,
+        user_name: config.user_name,
+        user_email: config.user_email,
+        workspace_gid: config.workspace_gid || workspaceGid,
+        workspace_name: config.workspace_name || null,
+      },
+    };
+  },
+
+  status(record) {
+    const config = record?.config || {};
+    return {
+      slug: this.slug,
+      status: record?.status || "disconnected",
+      is_enabled: !!record?.is_enabled,
+      user_name: config.user_name || null,
+      user_email: config.user_email || null,
+      workspace_gid: config.workspace_gid || null,
+      workspace_name: config.workspace_name || null,
+    };
+  },
+
+  deactivate() {
+    return { patch: { status: "inactive", is_enabled: false } };
+  },
+
+  actions: {
+    async workspaces(record) {
+      const token = safeToken(record);
+      return { workspaces: await getWorkspaces(token) };
+    },
+  },
+};
+
+export default asanaPlugin;

package/src/core/integrations/sources.js

@@ -0,0 +1,56 @@
+// Integration storage. Integrations are per-project records that hold plugin
+// credentials + resolved metadata (Asana PAT, workspace gid, connected user…).
+//
+// Scoping model (see IntegrationStore + resolveIntegration in ./store.js):
+//   - Every integration lives in ONE project's integrations.json.
+//   - "Global" integrations are simply the ones stored under the DEFAULT project
+//     (~/.apx/projects/default/integrations.json). There is no separate global
+//     file: this keeps "which Asana does project X use?" unambiguous — a project
+//     uses its own record if present, otherwise it falls back to the default's.
+//
+// The file may contain tokens, so it is written chmod 0600 exactly like the
+// runtime MCP + vars stores.
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_PROJECT_STORE } from "#core/config/index.js";
+
+const INTEGRATIONS_FILENAME = "integrations.json";
+
+// Absolute path to a project's integrations.json given its storagePath
+// (~/.apx/projects/<apxId>/). Returns null when no storagePath is available.
+export function integrationsPath(storagePath) {
+  if (!storagePath) return null;
+  return path.join(storagePath, INTEGRATIONS_FILENAME);
+}
+
+// The storagePath of the DEFAULT project — the home of "global" integrations.
+export function defaultIntegrationsStorage() {
+  return DEFAULT_PROJECT_STORE;
+}
+
+// Read the raw array of integration records for a project. Always returns an
+// array (missing/corrupt file → []).
+export function readIntegrations(storagePath) {
+  const p = integrationsPath(storagePath);
+  if (!p || !fs.existsSync(p)) return [];
+  try {
+    const json = JSON.parse(fs.readFileSync(p, "utf8"));
+    return Array.isArray(json) ? json : [];
+  } catch {
+    return [];
+  }
+}
+
+// Persist the array of integration records for a project. Creates the storage
+// directory if needed and locks the file to 0600 (tokens live here).
+export function writeIntegrations(storagePath, entries) {
+  const p = integrationsPath(storagePath);
+  if (!p) throw new Error("writeIntegrations: storagePath required");
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  fs.writeFileSync(p, JSON.stringify(entries, null, 2) + "\n");
+  try {
+    fs.chmodSync(p, 0o600);
+  } catch {
+    // best-effort on non-POSIX filesystems (Windows) — ignore.
+  }
+}