@agentprojectcontext/apx 1.58.0 → 1.60.0

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.
+  }
+}

package/src/core/integrations/store.js

@@ -0,0 +1,118 @@
+// IntegrationStore: CRUD over one project's integrations.json, plus the
+// cross-scope resolution used by agent tools. Pure filesystem + data logic —
+// no Express, no plugin HTTP calls (those live in ./plugins/*). This keeps the
+// storage layer testable in isolation (see tests/integrations.test.js).
+import {
+  readIntegrations,
+  writeIntegrations,
+  defaultIntegrationsStorage,
+} from "./sources.js";
+
+// Keys inside `config` that hold secrets — never sent to the web UI in clear.
+const SECRET_KEYS = new Set([
+  "personal_access_token",
+  "token",
+  "api_key",
+  "client_secret",
+]);
+
+// Return a shallow copy of a record with secret config values masked, safe to
+// send to the browser. A present secret becomes `true` under `config.<key>_set`
+// so the UI can show "configured" without leaking the value.
+export function redactRecord(record) {
+  if (!record) return record;
+  const config = { ...(record.config || {}) };
+  for (const key of Object.keys(config)) {
+    if (SECRET_KEYS.has(key)) {
+      const hasValue = typeof config[key] === "string" && config[key].length > 0;
+      delete config[key];
+      config[`${key}_set`] = hasValue;
+    }
+  }
+  return { ...record, config };
+}
+
+export class IntegrationStore {
+  // `storagePath` is a project's ~/.apx/projects/<apxId>/ directory.
+  constructor(storagePath) {
+    if (!storagePath) throw new Error("IntegrationStore: storagePath required");
+    this.storagePath = storagePath;
+  }
+
+  list() {
+    return readIntegrations(this.storagePath);
+  }
+
+  get(slug) {
+    return this.list().find((r) => r.slug === slug) || null;
+  }
+
+  // Insert or merge a record by slug. `patch` is shallow-merged; `patch.config`
+  // is deep-merged one level so callers can update a single config key without
+  // clobbering the token. Returns the persisted record.
+  upsert(slug, patch = {}) {
+    const entries = this.list();
+    const idx = entries.findIndex((r) => r.slug === slug);
+    const now = new Date().toISOString();
+    if (idx === -1) {
+      const record = {
+        slug,
+        name: patch.name || slug,
+        type: patch.type || "custom",
+        description: patch.description || "",
+        source: patch.source || "builtin",
+        status: patch.status || "disconnected",
+        is_enabled: patch.is_enabled ?? false,
+        config: patch.config || {},
+        created_at: now,
+        updated_at: now,
+      };
+      entries.push(record);
+      writeIntegrations(this.storagePath, entries);
+      return record;
+    }
+    const prev = entries[idx];
+    const merged = {
+      ...prev,
+      ...patch,
+      config: { ...(prev.config || {}), ...(patch.config || {}) },
+      updated_at: now,
+    };
+    entries[idx] = merged;
+    writeIntegrations(this.storagePath, entries);
+    return merged;
+  }
+
+  remove(slug) {
+    const entries = this.list();
+    const next = entries.filter((r) => r.slug !== slug);
+    if (next.length === entries.length) return false;
+    writeIntegrations(this.storagePath, next);
+    return true;
+  }
+}
+
+// Resolve the effective integration for `slug` in a project, applying the
+// project→default precedence: a project's OWN enabled record wins; otherwise
+// the default project's enabled record is used. Returns { record, scope } or
+// null when neither is usable. `defaultStorage` defaults to the default
+// project's storage so callers only need the current project's storagePath.
+export function resolveIntegration({
+  projectStorage,
+  slug,
+  defaultStorage = defaultIntegrationsStorage(),
+  requireEnabled = true,
+}) {
+  const usable = (record) =>
+    !!record && (!requireEnabled || (record.is_enabled && record.status === "active"));
+
+  if (projectStorage) {
+    const own = new IntegrationStore(projectStorage).get(slug);
+    if (usable(own)) return { record: own, scope: "project", storagePath: projectStorage };
+  }
+  if (defaultStorage && defaultStorage !== projectStorage) {
+    const fallback = new IntegrationStore(defaultStorage).get(slug);
+    if (usable(fallback)) return { record: fallback, scope: "global", storagePath: defaultStorage };
+  }
+  return null;
+}

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

@@ -0,0 +1,191 @@
+// Integration plugins per project. Companion to api/mcps.js: MCP servers are
+// raw tool endpoints; integrations are higher-level plugins (Asana today) that
+// own a credential + lifecycle and expose named tools to agents.
+//
+// Scoping (see core/integrations/store.js): every record lives in one project's
+// integrations.json. `?scope=global` targets the DEFAULT project's store, so
+// "global" integrations are literally the default project's — a project without
+// its own record falls back to that one. This keeps "which Asana runs here?"
+// unambiguous when you have both a base Asana and a per-project Asana.
+//
+//   GET    /projects/:pid/integrations?scope=project|global      list stored (redacted)
+//   GET    /projects/:pid/integrations/catalog                   roster + resolved status
+//   GET    /projects/:pid/integrations/:slug?scope=…             one plugin status
+//   POST   /projects/:pid/integrations/:slug/configure?scope=…   save credentials
+//   POST   /projects/:pid/integrations/:slug/validate?scope=…    verify against provider
+//   POST   /projects/:pid/integrations/:slug/deactivate?scope=…  disable
+//   POST   /projects/:pid/integrations/:slug/action/:action?scope=…  plugin read action
+//   DELETE /projects/:pid/integrations/:slug?scope=…             remove
+import {
+  IntegrationStore,
+  resolveIntegration,
+  redactRecord,
+  defaultIntegrationsStorage,
+  listCatalog,
+  getPluginService,
+} from "#core/integrations/index.js";
+
+function normalizeScope(raw) {
+  if (!raw) return "project";
+  const s = String(raw).toLowerCase();
+  if (s === "global" || s === "default") return "global";
+  if (s === "project" || s === "shared" || s === "runtime") return "project";
+  return null;
+}
+
+// Resolve the storagePath for the requested scope. `global` → default project
+// store; `project` → the current project's store.
+function storagePathForScope(scope, p, projects) {
+  if (scope === "global") {
+    const base = projects.get(0);
+    return base?.storagePath || defaultIntegrationsStorage();
+  }
+  return p.storagePath || null;
+}
+
+export function register(app, { projects, project }) {
+  // List stored integrations in the chosen scope (secrets redacted).
+  app.get("/projects/:pid/integrations", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const records = new IntegrationStore(storagePath).list().map(redactRecord);
+    res.json(records);
+  });
+
+  // The full plugin roster with each plugin's resolved status for this project
+  // (project record wins over the default/global one).
+  app.get("/projects/:pid/integrations/catalog", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const catalog = listCatalog().map((entry) => {
+      const svc = getPluginService(entry.slug);
+      let status = { slug: entry.slug, status: "disconnected", is_enabled: false };
+      let scope = null;
+      if (svc) {
+        const resolved = resolveIntegration({
+          projectStorage: p.storagePath,
+          slug: entry.slug,
+          requireEnabled: false,
+        });
+        status = svc.status(resolved?.record || null);
+        scope = resolved?.scope || null;
+      }
+      return { ...entry, status, resolved_scope: scope };
+    });
+    res.json(catalog);
+  });
+
+  // Status for a single plugin in the chosen scope.
+  app.get("/projects/:pid/integrations/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const record = new IntegrationStore(storagePath).get(req.params.slug);
+    res.json(svc.status(record));
+  });
+
+  // Save credentials / config. Creates the record if missing.
+  app.post("/projects/:pid/integrations/:slug/configure", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    try {
+      const { patch } = svc.configure(store.get(req.params.slug), req.body || {});
+      const record = store.upsert(req.params.slug, patch);
+      res.status(201).json(redactRecord(record));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Verify the stored credentials against the provider, then persist the result.
+  app.post("/projects/:pid/integrations/:slug/validate", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    const record = store.get(req.params.slug);
+    if (!record) return res.status(404).json({ error: "integration not configured" });
+    try {
+      const { patch, result } = await svc.validate(record);
+      store.upsert(req.params.slug, patch);
+      if (result && result.ok === false) return res.status(400).json(result);
+      res.json(result);
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Disable a plugin without deleting its stored credentials.
+  app.post("/projects/:pid/integrations/:slug/deactivate", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const store = new IntegrationStore(storagePath);
+    if (!store.get(req.params.slug)) return res.status(404).json({ error: "integration not configured" });
+    const { patch } = svc.deactivate(store.get(req.params.slug));
+    const record = store.upsert(req.params.slug, patch);
+    res.json(svc.status(record));
+  });
+
+  // Plugin-specific read action (e.g. Asana → list workspaces for the token).
+  app.post("/projects/:pid/integrations/:slug/action/:action", async (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const svc = getPluginService(req.params.slug);
+    if (!svc) return res.status(404).json({ error: `unknown plugin "${req.params.slug}"` });
+    const fn = svc.actions?.[req.params.action];
+    if (typeof fn !== "function") {
+      return res.status(404).json({ error: `unknown action "${req.params.action}"` });
+    }
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const record = new IntegrationStore(storagePath).get(req.params.slug);
+    if (!record) return res.status(404).json({ error: "integration not configured" });
+    try {
+      res.json(await fn.call(svc.actions, record));
+    } catch (e) {
+      res.status(400).json({ error: e.message });
+    }
+  });
+
+  // Remove a stored integration entirely.
+  app.delete("/projects/:pid/integrations/:slug", (req, res) => {
+    const p = project(req, res);
+    if (!p) return;
+    const scope = normalizeScope(req.query?.scope);
+    if (scope === null) return res.status(400).json({ error: `unknown scope "${req.query?.scope}"` });
+    const storagePath = storagePathForScope(scope, p, projects);
+    if (!storagePath) return res.status(400).json({ error: "project has no storage path" });
+    const removed = new IntegrationStore(storagePath).remove(req.params.slug);
+    if (!removed) return res.status(404).end();
+    res.status(204).end();
+  });
+}