@agentprojectcontext/apx 1.60.1 → 1.61.0

package/package.json

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

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

@@ -0,0 +1,22 @@
+// Shared helper for the GitHub agent tools (github-*.js). Underscore file — no
+// tool `name:` of its own. Resolves the project's effective GitHub integration
+// (its own record wins over the default project's) and hands back the token.
+import { resolveProject } from "../helpers.js";
+import { resolveIntegration } from "#core/integrations/index.js";
+
+export function resolveGithub(projects, project) {
+  const p = resolveProject(projects, project);
+  const resolved = resolveIntegration({ projectStorage: p.storagePath, slug: "github" });
+  if (!resolved) {
+    throw new Error(
+      "GitHub is not connected for this project. Ask the user to connect it in the web panel → Integrations → Plugins → GitHub.",
+    );
+  }
+  const token = resolved.record.config?.token;
+  if (!token) throw new Error("GitHub integration has no token configured");
+  return { token, scope: resolved.scope };
+}
+
+export const PROJECT_ARG = {
+  project: { type: "string", description: "APX project id/name (optional; defaults to current)" },
+};

package/src/core/agent/tools/handlers/github-create-issue.js

@@ -0,0 +1,30 @@
+import * as github from "#core/integrations/plugins/github.js";
+import { resolveGithub, PROJECT_ARG } from "./_github.js";
+
+export default {
+  name: "github_create_issue",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "github_create_issue",
+      description: "Open an issue in a GitHub repository.",
+      parameters: {
+        type: "object",
+        properties: {
+          owner: { type: "string", description: "Repo owner (user or org)" },
+          repo: { type: "string", description: "Repo name" },
+          title: { type: "string", description: "Issue title" },
+          body: { type: "string", description: "Issue body (markdown)" },
+          ...PROJECT_ARG,
+        },
+        required: ["owner", "repo", "title"],
+      },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project, owner, repo, title, body } = {}) => {
+    const { token } = resolveGithub(projects, project);
+    const issue = await github.createIssue(token, { owner, repo, title, body });
+    return { issue: { number: issue.number, url: issue.html_url, title: issue.title } };
+  },
+};

package/src/core/agent/tools/handlers/github-list-repos.js

@@ -0,0 +1,20 @@
+import * as github from "#core/integrations/plugins/github.js";
+import { resolveGithub, PROJECT_ARG } from "./_github.js";
+
+export default {
+  name: "github_list_repos",
+  category: "integrations",
+  schema: {
+    type: "function",
+    function: {
+      name: "github_list_repos",
+      description: "List GitHub repositories accessible to the connected token.",
+      parameters: { type: "object", properties: { ...PROJECT_ARG } },
+    },
+  },
+  makeHandler: ({ projects }) => async ({ project } = {}) => {
+    const { token } = resolveGithub(projects, project);
+    const repos = await github.listRepos(token);
+    return { repos: repos.map((r) => ({ full_name: r.full_name, private: r.private, url: r.html_url, description: r.description })) };
+  },
+};

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

@@ -56,6 +56,10 @@ export const TOOLS = Object.freeze({
   ASANA_CREATE_TASK:   "asana_create_task",
   ASANA_UPDATE_TASK:   "asana_update_task",
 
+  // Integrations — GitHub plugin (see core/integrations/plugins/github.js)
+  GITHUB_LIST_REPOS:   "github_list_repos",
+  GITHUB_CREATE_ISSUE: "github_create_issue",
+
   // Side-effects
   SEND_TELEGRAM:       "send_telegram",
   SET_IDENTITY:        "set_identity",
@@ -104,6 +108,8 @@ export const NATIVE_TOOL_NAMES = new Set([
   TOOLS.ASANA_LIST_TASKS,
   TOOLS.ASANA_CREATE_TASK,
   TOOLS.ASANA_UPDATE_TASK,
+  TOOLS.GITHUB_LIST_REPOS,
+  TOOLS.GITHUB_CREATE_ISSUE,
   TOOLS.SEND_TELEGRAM,
   TOOLS.SET_IDENTITY,
   TOOLS.SET_PERMISSION_MODE,

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

@@ -37,6 +37,8 @@ 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 githubListRepos from "./handlers/github-list-repos.js";
+import githubCreateIssue from "./handlers/github-create-issue.js";
 import { createPermissionGuard } from "./helpers.js";
 import { buildBridgedTools, DEFAULT_CATEGORIES } from "./registry-bridge.js";
 import { TOOLS, CODE_CHANNEL_TOOLS } from "./names.js";
@@ -85,6 +87,8 @@ const NATIVE_TOOLS = [
   asanaListTasks,
   asanaCreateTask,
   asanaUpdateTask,
+  githubListRepos,
+  githubCreateIssue,
 ];
 
 // Registry-backed bridges. Categories can be overridden per-process via env

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,48 @@ 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). configFields render as
+  // inputs; `select` is a post-validate picker sourced from an action; and
+  // connectedFields are the status keys shown once connected.
+  ui: {
+    accent: "rose",
+    configFields: [
+      {
+        key: "personal_access_token",
+        label: "Personal Access Token",
+        type: "password",
+        placeholder: "1/1234567890abcdef:...",
+        help: {
+          label: "¿Cómo obtener el token?",
+          url: "https://app.asana.com/0/my-apps",
+          urlLabel: "app.asana.com/0/my-apps",
+          steps: [
+            "Abrí app.asana.com/0/my-apps en el navegador.",
+            'Bajá hasta la sección "Personal access tokens" (no tus apps OAuth).',
+            'Hacé clic en "+ New access token".',
+            "Dale un nombre y confirmá.",
+            'Copiá el token completo — empieza con "1/..." y tiene un ":" en el medio.',
+            "Pegalo en el campo de abajo.",
+          ],
+        },
+      },
+    ],
+    select: {
+      key: "workspace_gid",
+      label: "Seleccioná el workspace a usar",
+      action: "workspaces",
+      listKey: "workspaces",
+      valueKey: "gid",
+      labelKey: "name",
+    },
+    connectedFields: [
+      { key: "user_name", label: "Conectado como" },
+      { key: "user_email", label: "Email" },
+      { key: "workspace_name", label: "Workspace" },
+    ],
+  },
+
   // 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,172 @@
+// 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" },
+  ],
+  ui: {
+    accent: "slate",
+    configFields: [
+      {
+        key: "token",
+        label: "Personal Access Token",
+        type: "password",
+        placeholder: "ghp_... o github_pat_...",
+        help: {
+          label: "¿Cómo obtener el token?",
+          url: "https://github.com/settings/tokens",
+          urlLabel: "github.com/settings/tokens",
+          steps: [
+            "Abrí github.com/settings/tokens.",
+            'Generá un token (classic o fine-grained) con scope "repo".',
+            "Copiá el token — empieza con ghp_ o github_pat_.",
+            "Pegalo en el campo de abajo.",
+          ],
+        },
+      },
+    ],
+    connectedFields: [
+      { key: "user_login", label: "Conectado como" },
+      { key: "user_name", label: "Nombre" },
+    ],
+  },
+
+  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;