Allow users to connect external tools in CORE and grant tool access to Agents/NPCs

[harshithmullapudi]

Problem

Users need a way to connect their external tools (e.g., Gmail, Calendar, Slack, GitHub, etc.) inside the CORE platform.

Goal

A user should be able to grant specific tool access to an agent (or NPC) so the agent can perform actions using those tools on the user’s behalf.

Requirements

1. Tool connection flow: user can authenticate/connect a tool provider.
2. Permissioning: user can explicitly grant/revoke access per agent/NPC, ideally scoped (read vs write, specific resources).
3. Auditability: log actions taken by agents using those tools.
4. UX: clear consent screens and visibility into what is connected and who has access.

Notes

This is for the CORE platform integration layer and the town/NPC action system.

[omjeem]

Hey, @harshithmullapudi,
Thanks for opening this! I'd be happy to work on it.
Please assign it to me, and I'll get started.

[harshithmullapudi]

@omjeem

This work needs to be in place, but I haven’t dug deep enough yet to have a solid plan for how we should do it. First step here is to come up with a feasible plan (approach + milestones) before we start implementing.

Can you propose a plan, and call out any key questions/unknowns/risks you see?

[omjeem]

Sure, I'll take a look at this and try to put together a plan - will share it soon for feedback.

[omjeem]

Hey @harshithmullapudi , I spent some time in both codebases before starting on this, and a good chunk of the plumbing already exists , wanted to confirm the direction with you before I build on it.

What I found

• CORE already exposes integration tools over the API -> GET/POST /api/v1/integration_account/:id/action lists and executes actions, and it accepts OAuth tokens. So Town doesn't need any new surface on CORE to reach the tools.

• Town's npc-tools.ts already has list_integrations, list_integration_actions, and execute_integration_action, gated by Npc.permissions.integrations (per-slug, optional action whitelist), running on the owner's token. It just never lights up because every template ships with integrations: [] and the only way to set a grant is hand-editing the NPC's .mdx and redeploying.

• IntegrationCallLog on the CORE side already has a source column for auditing, but the HTTP route never fills it, and Town never sends one.

So my plan is mostly connecting these pieces

• An owner-only panel in the Town UI to grant/revoke integrations per NPC.

  • Lists the owner's connected CORE integrations.
  • Supports an optional per-action whitelist.
  • Writes go through the same normalizePermissions() the CLI deploy path uses.

• Pass a source like town:npc:<id> through to CORE's call log, and log each execution on the Town side too (activity feed) so the owner can see what their NPCs did.

• Charge aura per executed action, same as creator mutation tools.

• Since visitors chat with NPCs on the owner's token, I'd make new grants owner only by default -> the owner has to explicitly allow visitor-triggered use per integration. Feels wrong that an anonymous guest could make an NPC send an email otherwise.

Questions before I start

1. Are you okay with the owner-only default for visitor-triggered actions, or do you want visitors allowed by default?

2. Where do you want the grant UI -> in-game panel on the NPC, or should this live in the CLI/creator flow instead?

3. Is the Town activity feed enough for the audit view for now, or do you want something in CORE's UI too?

4. What should an integration action cost in aura? I was thinking 10, same as a creator mutation.

One thing I'm intentionally leaving out (for now)

CORE has an unused OAuthIntegrationGrant model + integration scope that would let users pick which integrations an OAuth app (like Town) can touch at consent time.

Wiring that changes CORE's auth behavior, so I'd rather treat it as a follow-up if you want it at all.

---

If this sounds right I'll start with the granting UI and the audit bits.