@agentprojectcontext/apx 1.60.1 → 1.62.0

package/src/core/integrations/catalog.js

@@ -2,32 +2,27 @@
 // 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).
+// satisfies the lifecycle contract (configure/validate/status/deactivate) and
+// declares a `ui` descriptor the generic PluginConnect component renders. The
+// rest carry `coming_soon: true`. Adding a plugin = drop a module in ./plugins/
+// + register it in PLUGIN_SERVICES (open/closed) — no API/route changes.
+//
+// Scope of this catalog (per product decision): Asana, GitHub, WhatsApp only.
+// Telegram is intentionally absent — it's a channel, configured under its own
+// surface, not a service plugin. Transcription lives with the desktop STT stack.
 import { asanaPlugin } from "./plugins/asana.js";
+import { githubPlugin } from "./plugins/github.js";
 
 // slug -> live plugin service (must implement the lifecycle contract).
 export const PLUGIN_SERVICES = Object.freeze({
   asana: asanaPlugin,
+  github: githubPlugin,
 });
 
-// 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.
+// Static descriptors for plugins that are declared but not yet connectable.
+// WhatsApp needs a WhatsApp-Web bridge (QR pairing) that APX doesn't ship yet,
+// so it stays coming-soon rather than pretending to connect.
 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",
@@ -36,17 +31,11 @@ const COMING_SOON = [
     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.
+// The full catalog: implemented plugins first, then coming-soon. Implemented
+// entries carry their `ui` descriptor + tools so the generic component can
+// render their config form.
 export function listCatalog() {
   const implemented = Object.values(PLUGIN_SERVICES).map((p) => ({
     slug: p.slug,
@@ -55,6 +44,7 @@ export function listCatalog() {
     description: p.description,
     auth: p.auth,
     tools: p.tools || [],
+    ui: p.ui || null,
     coming_soon: false,
   }));
   return [...implemented, ...COMING_SOON];

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

@@ -142,6 +142,28 @@ export const asanaPlugin = {
     { slug: "asana_update_task", desc: "Actualizar estado o campos de una tarea" },
   ],
 
+  // Declarative UI descriptor consumed by the generic PluginConnect component
+  // (see web/components/integrations/PluginConnect.tsx). STRUCTURE ONLY — all
+  // display text lives in the web i18n dictionaries under integrations.<slug>.*
+  // (keyed by field key). configFields render as inputs; `select` is a
+  // post-validate picker sourced from an action; connectedFields are the status
+  // keys shown once connected. `help_url`/`help_url_label` are non-translatable
+  // data kept here.
+  ui: {
+    accent: "rose",
+    configFields: [
+      {
+        key: "personal_access_token",
+        type: "password",
+        placeholder: "1/1234567890abcdef:...",
+        help_url: "https://app.asana.com/0/my-apps",
+        help_url_label: "app.asana.com/0/my-apps",
+      },
+    ],
+    select: { key: "workspace_gid", action: "workspaces", listKey: "workspaces", valueKey: "gid", labelKey: "name" },
+    connectedFields: ["user_name", "user_email", "workspace_name"],
+  },
+
   // Save the PAT and/or the target workspace. Returns a patch to persist.
   configure(record, body = {}) {
     const pat = (body.personal_access_token || "").trim();

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

@@ -0,0 +1,160 @@
+// GitHub integration plugin — Personal Access Token auth. Same shape as the
+// Asana plugin: a pure REST client + a lifecycle descriptor the daemon API
+// dispatches to. Self-contained (GitHub REST over fetch); no GitHub App / OAuth
+// broker yet — a PAT is enough to connect, list repos and open issues.
+
+const GITHUB_API_BASE = "https://api.github.com";
+const REQUEST_TIMEOUT_MS = 15_000;
+
+function headers(token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    Accept: "application/vnd.github+json",
+    "X-GitHub-Api-Version": "2022-11-28",
+    "User-Agent": "apx-integrations",
+  };
+}
+
+async function request(token, method, apiPath, { params, payload } = {}) {
+  let url = `${GITHUB_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(payload) : undefined,
+      signal: controller.signal,
+    });
+  } catch (e) {
+    clearTimeout(timer);
+    if (e.name === "AbortError") throw new Error("GitHub request timed out");
+    throw new Error(`GitHub request failed: ${e.message}`);
+  }
+  clearTimeout(timer);
+  if (!res.ok) {
+    let detail = `${res.status}`;
+    try {
+      const body = await res.json();
+      detail = body?.message || JSON.stringify(body);
+    } catch {
+      /* non-JSON error body */
+    }
+    throw new Error(`GitHub API ${res.status}: ${detail}`);
+  }
+  return res.json();
+}
+
+// ─── REST client ──────────────────────────────────────────────────────────────
+
+export async function validateToken(token) {
+  const user = await request(token, "GET", "/user");
+  if (!user?.login) throw new Error("GitHub returned an empty user response");
+  return user;
+}
+
+export async function listRepos(token, { affiliation = "owner,collaborator,organization_member", perPage = 30 } = {}) {
+  return request(token, "GET", "/user/repos", {
+    params: { affiliation, per_page: perPage, sort: "updated" },
+  });
+}
+
+export async function createIssue(token, { owner, repo, title, body }) {
+  return request(token, "POST", `/repos/${owner}/${repo}/issues`, { payload: { title, body } });
+}
+
+// ─── Plugin descriptor + lifecycle ────────────────────────────────────────────
+
+function safeToken(record) {
+  const token = record?.config?.token || "";
+  if (!token) throw new Error("GitHub token not configured");
+  return token;
+}
+
+export const githubPlugin = {
+  slug: "github",
+  name: "GitHub",
+  type: "source_control",
+  description: "Conectá GitHub con un token para que los agentes listen repos y abran issues",
+  auth: "token",
+  tools: [
+    { slug: "github_list_repos", desc: "Listar repositorios accesibles" },
+    { slug: "github_create_issue", desc: "Crear un issue en un repo" },
+  ],
+  // Structure only — display text lives in web i18n (integrations.github.*).
+  ui: {
+    accent: "slate",
+    configFields: [
+      {
+        key: "token",
+        type: "password",
+        placeholder: "ghp_... o github_pat_...",
+        help_url: "https://github.com/settings/tokens",
+        help_url_label: "github.com/settings/tokens",
+      },
+    ],
+    connectedFields: ["user_login", "user_name"],
+  },
+
+  configure(record, body = {}) {
+    const token = (body.token || "").trim();
+    if (!token && !record) throw new Error("Provide a GitHub token");
+    const config = {};
+    if (token) config.token = token;
+    const patch = { name: "GitHub", type: this.type, description: this.description, config };
+    if (token) patch.status = "pending_validation";
+    return { patch };
+  },
+
+  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_login: user.login, user_name: user.name || null, last_error: null };
+    return {
+      patch: { status: "active", is_enabled: true, config },
+      result: { ok: true, user_login: user.login, user_name: user.name || null },
+    };
+  },
+
+  status(record) {
+    const config = record?.config || {};
+    return {
+      slug: this.slug,
+      status: record?.status || "disconnected",
+      is_enabled: !!record?.is_enabled,
+      user_login: config.user_login || null,
+      user_name: config.user_name || null,
+    };
+  },
+
+  deactivate() {
+    return { patch: { status: "inactive", is_enabled: false } };
+  },
+
+  actions: {
+    async repos(record) {
+      const token = safeToken(record);
+      const repos = await listRepos(token);
+      return { repos: repos.map((r) => ({ full_name: r.full_name, private: r.private, url: r.html_url })) };
+    },
+  },
+};
+
+export default githubPlugin;

package/src/core/stores/runtime-callbacks.js

@@ -0,0 +1,107 @@
+// Durable pending-callback store for background runtime runs.
+//
+// When call_runtime launches a runtime detached (background mode), the result
+// must reach the originating chat when the runtime finishes — even if the
+// daemon that spawned it dies in the meantime (a crash, a pull, or, as we hit
+// in testing, a task whose very job is to restart the daemon). An in-memory
+// promise can't survive that. So we drop a small durable "IOU" here at launch;
+// a reconciler (host/daemon/callback-reconciler.js) delivers it once the
+// runtime's session record shows the run finished — regardless of WHICH daemon
+// is alive, and regardless of who closed the session (the daemon's own await,
+// or the runtime proactively via `apx session close`).
+//
+// One JSON file per pending callback: <APX_HOME>/pending-callbacks/<id>.json.
+// The in-process fast path deletes the file the moment it takes ownership of
+// delivery; whatever files remain are runs whose spawning daemon never got to
+// deliver — exactly the set the reconciler must handle.
+import fs from "node:fs";
+import path from "node:path";
+import { APX_HOME } from "#core/config/paths.js";
+import { nowIso } from "#core/util/time.js";
+
+export const PENDING_CALLBACKS_DIR = path.join(APX_HOME, "pending-callbacks");
+
+const SAFE_ID = /^[A-Za-z0-9._-]+$/;
+
+function fileFor(sessionId) {
+  return path.join(PENDING_CALLBACKS_DIR, `${sessionId}.json`);
+}
+
+/**
+ * Record that a background runtime run owes a callback to a channel. `entry`:
+ * { session_id, session_path, channel, chat_id, tg_channel, runtime, agent, who }.
+ * Best-effort — a failure to persist must never break the launch.
+ */
+export function writePendingCallback(entry) {
+  try {
+    if (!entry?.session_id || !SAFE_ID.test(String(entry.session_id))) return;
+    fs.mkdirSync(PENDING_CALLBACKS_DIR, { recursive: true });
+    fs.writeFileSync(fileFor(entry.session_id), JSON.stringify({ ...entry, created: nowIso() }, null, 2));
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Drop the IOU — called the instant an in-process delivery takes ownership. */
+export function deletePendingCallback(sessionId) {
+  try {
+    if (!sessionId || !SAFE_ID.test(String(sessionId))) return;
+    fs.rmSync(fileFor(sessionId), { force: true });
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** All outstanding IOUs (parsed). Silently skips unreadable/corrupt files. */
+export function listPendingCallbacks() {
+  let files;
+  try {
+    files = fs.readdirSync(PENDING_CALLBACKS_DIR).filter((f) => f.endsWith(".json"));
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const f of files) {
+    try {
+      const entry = JSON.parse(fs.readFileSync(path.join(PENDING_CALLBACKS_DIR, f), "utf8"));
+      if (entry?.session_id) out.push(entry);
+    } catch {
+      /* skip corrupt */
+    }
+  }
+  return out;
+}
+
+/**
+ * Read the finished-state of a runtime session .md by parsing its frontmatter.
+ * Returns { exists, done, status, result, completed } — `done` is true once the
+ * run has a completed timestamp (set by the daemon's closeRuntimeSession OR by
+ * the runtime's proactive `apx session close`).
+ */
+export function readSessionState(sessionPath) {
+  let text;
+  try {
+    text = fs.readFileSync(sessionPath, "utf8");
+  } catch {
+    return { exists: false, done: false };
+  }
+  const fm = {};
+  if (text.startsWith("---\n")) {
+    const end = text.indexOf("\n---", 4);
+    if (end !== -1) {
+      for (const line of text.slice(4, end).split("\n")) {
+        const i = line.indexOf(":");
+        if (i > 0) fm[line.slice(0, i).trim()] = line.slice(i + 1).trim();
+      }
+    }
+  }
+  const completed = fm.completed || "";
+  const status = fm.status || "";
+  return {
+    exists: true,
+    done: !!completed && !/in progress/i.test(status),
+    status,
+    result: fm.result || "",
+    completed,
+  };
+}

package/src/host/daemon/callback-reconciler.js

@@ -0,0 +1,87 @@
+// Durable delivery of background-runtime callbacks.
+//
+// Pairs with core/stores/runtime-callbacks.js: call_runtime drops a pending
+// "IOU" when it launches a runtime detached, and deletes it the moment the
+// in-process fast path delivers. Whatever IOUs survive belong to runs whose
+// spawning daemon died before delivering (crash, pull, or a task that restarted
+// the daemon). This reconciler — run once at boot and on an interval — delivers
+// those late, keying on the runtime SESSION being finished rather than on any
+// in-memory promise. That's what makes the callback survive a restart, and also
+// absorbs the "proactive" close: it doesn't care whether the daemon's own await
+// or the runtime's `apx session close` marked the session done.
+//
+// Recovery delivery is a plain channel send of the session's recorded result
+// (after a restart the full stdout is gone — only the one-line result the
+// session close captured remains). The rich A2A relay (Roby re-voicing the
+// result) stays the job of the live in-process path.
+import { listPendingCallbacks, deletePendingCallback, readSessionState } from "#core/stores/runtime-callbacks.js";
+
+const GRACE_MS = 30_000;               // let the live in-process path win a fresh completion
+const STALE_MS = 24 * 60 * 60 * 1000;  // drop IOUs for runs that never finished in a day
+
+function deliverText(entry, state) {
+  const who = entry.who || entry.runtime || "runtime";
+  const result = String(state.result || "").trim();
+  const isError = /error|⚠️/i.test(state.status) || /^(failed|error)/i.test(result);
+  const head = isError
+    ? `⚠️ La sesión de ${who} (\`${entry.session_id}\`) terminó con error${result ? `: ${result}` : ""}.`
+    : `✅ Terminó la sesión de ${who} (\`${entry.session_id}\`).`;
+  const text = !isError && result ? `${head}\n\n${result}` : head;
+  return text.slice(0, 3800);
+}
+
+/** One reconciliation pass. Best-effort per entry; a failure keeps the IOU for
+ *  the next tick rather than dropping the callback. */
+export async function reconcilePendingCallbacks({ plugins, log }) {
+  const pending = listPendingCallbacks();
+  if (!pending.length) return;
+  const telegram = plugins?.get?.("telegram");
+  const now = Date.now();
+
+  for (const entry of pending) {
+    try {
+      if (entry.channel !== "telegram") continue; // only telegram delivery for now
+      const state = readSessionState(entry.session_path);
+
+      if (!state.exists) {
+        deletePendingCallback(entry.session_id); // session file gone → orphan IOU
+        continue;
+      }
+      if (!state.done) {
+        const age = now - Date.parse(entry.created || "");
+        if (Number.isFinite(age) && age > STALE_MS) {
+          log?.(`callback-reconciler: dropping stale pending ${entry.session_id} (never completed)`);
+          deletePendingCallback(entry.session_id);
+        }
+        continue; // still running — check again next tick
+      }
+
+      // Finished. Give the live in-process path a grace window to win the
+      // normal (no-restart) case, so we don't double-deliver.
+      const compAge = now - Date.parse(state.completed || "");
+      if (Number.isFinite(compAge) && compAge < GRACE_MS) continue;
+
+      if (!telegram) continue; // telegram plugin not up this boot — retry next tick
+      await telegram.send({
+        channel: entry.tg_channel || undefined,
+        chat_id: entry.chat_id,
+        text: deliverText(entry, state),
+      });
+      deletePendingCallback(entry.session_id);
+      log?.(`callback-reconciler: delivered late callback for ${entry.session_id} → chat ${entry.chat_id}`);
+    } catch (e) {
+      log?.(`callback-reconciler: delivery failed for ${entry.session_id}: ${e.message}`);
+      // keep the IOU; next tick retries
+    }
+  }
+}
+
+/** Start the reconciler: one pass at boot (recovers anything a prior daemon
+ *  left behind), then every `intervalMs`. Returns { stop }. */
+export function startCallbackReconciler({ plugins, log, intervalMs = 30_000 }) {
+  const tick = () => reconcilePendingCallbacks({ plugins, log }).catch(() => {});
+  tick();
+  const timer = setInterval(tick, intervalMs);
+  timer.unref?.();
+  return { stop: () => clearInterval(timer) };
+}

package/src/host/daemon/index.js

@@ -19,6 +19,7 @@ import { ProjectManager } from "./db.js";
 import { McpRegistry } from "#core/mcp/runner.js";
 import { PluginManager } from "./plugins/index.js";
 import { RoutineScheduler } from "./routines-scheduler.js";
+import { startCallbackReconciler } from "./callback-reconciler.js";
 import { buildApi } from "./api.js";
 import { createTokenStore } from "./token-store.js";
 import { triggerWakeup } from "./wakeup.js";
@@ -208,12 +209,17 @@ async function main() {
 
   plugins.installRoutes(app);
 
+  let callbackReconciler = null;
   const server = app.listen(port, host, () => {
     writePid();
     log(`apx-daemon ${PKG.version} listening on http://${host}:${port}`);
     log(`projects: ${projects.list().length} | plugins: ${Object.keys(plugins.status()).join(", ") || "(none)"}`);
     plugins.startAll();
     scheduler.start();
+    // Durable background-runtime callbacks: deliver any results whose spawning
+    // daemon died before it could (crash, pull, or a task that restarted the
+    // daemon). Runs once now to recover prior IOUs, then on an interval.
+    callbackReconciler = startCallbackReconciler({ plugins, log });
     // Cross-channel memory: ensure ~/.apx/memory.md exists, open the vector
     // store, and start the incremental RAG indexer. Best-effort — never blocks
     // boot and never throws into the daemon.
@@ -280,6 +286,7 @@ async function main() {
   function shutdown(signal) {
     log(`received ${signal}, shutting down...`);
     scheduler.stop();
+    callbackReconciler?.stop();
     plugins.stopAll();
     stopMemory();
     registries.shutdown();