feat(appkit): fromPlugin() DX, runAgent plugins arg, shared toolkit-resolver

[MarioCadenas]

DX centerpiece. Introduces the symbol-marker pattern that collapses
plugin tool references in code-defined agents from a three-touch dance
to a single line, and extracts the shared resolver that the agents
plugin, auto-inherit, and standalone runAgent all now go through.

fromPlugin(factory, opts?) — the marker

packages/appkit/src/plugins/agents/from-plugin.ts. Returns a spread-
friendly { [Symbol()]: FromPluginMarker } record. The symbol key is
freshly generated per call, so multiple spreads of the same plugin
coexist safely. The marker's brand is a globally-interned
Symbol.for("@databricks/appkit.fromPluginMarker") — stable across
module boundaries.

resolveToolkitFromProvider(pluginName, provider, opts?)

packages/appkit/src/plugins/agents/toolkit-resolver.ts. Single source
of truth for "turn a ToolProvider into a keyed record of ToolkitEntry
markers". Prefers provider.toolkit(opts) when available (core plugins
implement it), falls back to walking getAgentTools() and synthesizing
namespaced keys (${pluginName}.${localName}) for third-party
providers, honoring only / except / rename / prefix the same
way.

Used by three call sites, previously all copy-pasted:

1. AgentsPlugin.buildToolIndex — fromPlugin marker resolution pass
2. AgentsPlugin.applyAutoInherit — markdown auto-inherit path
3. runAgent — standalone-mode plugin tool dispatch

AgentsPlugin.buildToolIndex — symbol-key resolution pass

Before the existing string-key iteration, buildToolIndex now walks
Object.getOwnPropertySymbols(def.tools). For each FromPluginMarker,
it looks up the plugin by name in PluginContext.getToolProviders(),
calls resolveToolkitFromProvider, and merges the resulting entries
into the per-agent index. Missing plugins throw at setup time with a
clear Available: ... listing — wiring errors surface on boot, not
mid-request.

hasExplicitTools now counts symbol keys too, so a
tools: { ...fromPlugin(x) } record correctly disables auto-inherit
on code-defined agents.

Type plumbing

• AgentTools type: { [key: string]: AgentTool } & { [key: symbol]: FromPluginMarker }. Preserves string-key autocomplete while
  accepting marker spreads under strict TS.
• AgentDefinition.tools switched to AgentTools.

runAgent gains plugins?: PluginData[]

packages/appkit/src/core/run-agent.ts. When an agent def contains
fromPlugin markers, the caller passes plugins via
RunAgentInput.plugins. A local provider cache constructs each plugin
and dispatches tool calls via provider.executeAgentTool(). Runs as
service principal (no OBO — there's no HTTP request). If a def
contains markers but plugins is absent, throws with guidance.

Exports

fromPlugin, FromPluginMarker, isFromPluginMarker, AgentTools
added to the main barrel.

Test plan

• 14 new tests: marker shape, symbol uniqueness, type guard,
  factory-without-pluginName error, fromPlugin marker resolution in
  AgentsPlugin, fallback to getAgentTools for providers without
  .toolkit(), symbol-only tools disables auto-inherit, runAgent
  standalone marker resolution via plugins arg, guidance error when
  missing.
• Full appkit vitest suite: 1311 tests passing.
• Typecheck clean.

Signed-off-by: MarioCadenas MarioCadenas@users.noreply.github.com

PR Stack

1. Shared agent types + LLM adapters — feat(appkit): shared agent types and LLM adapter implementations #301
2. Tool primitives + ToolProvider surfaces — feat(appkit): tool primitives and ToolProvider surfaces on core plugins #302
3. Plugin infrastructure (attachContext + PluginContext) — feat(appkit): plugin infrastructure — attachContext + PluginContext mediator #303
4. agents() plugin + createAgent(def) + markdown-driven agents — feat(appkit): agents() plugin, createAgent(def), and markdown-driven agents #304
5. fromPlugin() DX + runAgent plugins arg + toolkit-resolver (this PR)
6. Reference app + dev-playground + docs — feat(appkit): reference agent-app, dev-playground chat UI, docs, and template #306

Demo

agent-demo.mp4

[pkosiec]

Honestly, I still don't like the fromPlugin API. Asked an agent if that's just me and looks like the community usually takes a similar approach to the one I suggest 😄 See the report at the end of the comment.

My suggestion is to: instead of

const support = createAgent({                                                                      
  instructions: "You help customers with data and files.",                                         
  model: "databricks-claude-sonnet-4-5",                  // string sugar                          
  tools: {                                                                                         
    ...fromPlugin(analytics),                             // all analytics tools                   
    ...fromPlugin(files, { only: ["uploads.read"] }),     // filtered subset                       
    get_weather: tool({                                                                            
      name: "get_weather",                                                                         
      description: "Weather",                                                                      
      schema: z.object({ city: z.string() }),                                                      
      execute: async ({ city }) => `Sunny in ${city}`,                                             
    }),                                                                                            
  },                                                                                               
});                                                                                                
                                                                                                   
await createApp({                                                                                  
  plugins: [server(), analytics(), files(), agents({ agents: { support } })],                      
});    

go with this:

  const analyticsPlugin = analytics();
  const filesPlugin = files();

  const support = createAgent({
    instructions: "You help customers with data and files.",
    model: "databricks-claude-sonnet-4-5",
    tools: {
      ...analyticsPlugin.toolkit(),
      ...filesPlugin.toolkit({ only: ["uploads.read"] }),
      get_weather: tool({
        name: "get_weather",
        description: "Weather",
        schema: z.object({ city: z.string() }),
        execute: async ({ city }) => `Sunny in ${city}`,
      }),
    },
  });

  await createApp({
    plugins: [server(), analyticsPlugin, filesPlugin, agents({ agents: { support } })],
  });

What do you think?

---

The chicken-and-egg problem

The tension: agent definitions need plugin tools, but plugins need AppKit context (WorkspaceClient, PluginContext, OBO) to be functional. So at definition time, nothing is "ready."

Common JS patterns for this

1. Two-phase init (your preference)

Create a handle, wire references, then initialize. This is how Express, Fastify, and Koa work — you instantiate middleware/plugins, compose them, then call listen():

const auth = passport();           // create
const app = express();
app.use(auth);                     // wire
app.listen(3000);                  // initialize

In AppKit terms, your preferred API would look like:

const analyticsPlugin = analytics({});
const filesPlugin = files({ volumes: { uploads: {} } });

const agent = createAgent({
  tools: {
    ...analyticsPlugin.toolkit(),
    ...filesPlugin.toolkit({ only: ["uploads.read"] }),
  },
});

createApp({ plugins: [server(), analyticsPlugin, filesPlugin, agents({ agents: { agent } })] });

This is totally achievable — analytics() already returns a data bag. It could also expose .toolkit() that returns the same lazy markers fromPlugin creates internally. Same resolution mechanism, more explicit surface.

2. DI container / token-based (Angular, NestJS, InversifyJS)

Register by class or token, resolve lazily:

@Injectable()
class MyAgent {
  constructor(@Inject(AnalyticsPlugin) private analytics: AnalyticsPlugin) {}
}

This is basically what fromPlugin does — reference-by-name, resolve-at-startup — but dressed up with decorators. Heavy for a non-decorator codebase.

3. Builder / fluent API (Hono, tRPC)

Collect everything, resolve at .build():

const app = AppKit.builder()
  .plugin("analytics", analytics({}))
  .plugin("files", files({ ... }))
  .agent("support", { tools: ["analytics", "files.uploads.read"] })
  .build();

Clean, but loses the "agents are plain objects" composability.

4. String references (Terraform, Spring, Django settings)

Just use names, resolve later. This is what markdown agents already do with toolkits: [analytics] in frontmatter — it's the YAML equivalent of fromPlugin(analytics).

My honest assessment

fromPlugin is pattern #2 disguised as a spread operator. It works, but has two DX friction points:

1. It's an unusual pattern — ...fromPlugin(analytics) looks like it's doing something, but it's just creating a { [Symbol]: { pluginName: "analytics" } } marker. The magic is hidden.

2. It introduces a separate concept — you need to learn fromPlugin as a standalone primitive. In your preferred approach (chore: rework TelemetryManager to use Node SDK #1), .toolkit() is a method on the thing you already have — no new import, no new concept.

The good news: these aren't mutually exclusive. The factory data bag returned by analytics() could grow a .toolkit() method that produces the same markers. fromPlugin could remain as a lower-level escape hatch (e.g., for dynamic plugin names). This is actually a very small surface change — toPlugin just needs to stamp a .toolkit() method alongside the existing .pluginName.

What the broader JS community leans toward

Explicit instance references (your preference) is the dominant pattern. Express, Fastify, Hono, tRPC, Drizzle, Prisma — almost nobody uses magic marker/symbol indirection. The standard expectation is: "I created it, I hold a reference to it, I pass that reference where it's needed."

The fromPlugin pattern is closer to how Terraform or Pulumi work (reference by logical name, resolve in a plan phase), which makes sense for infrastructure-as-code but feels foreign in a JS application SDK.

[pkosiec]

Agentic review:

Fix Plan: Code Review Findings for agent/v2/5-fromplugin-runagent

Context

Code review of branch agent/v2/5-fromplugin-runagent vs agent/v2/4-agents-plugin identified 16 findings across 12 parallel reviewers (correctness, testing, maintainability, project-standards, agent-native, learnings-researcher, security, api-contract, reliability, adversarial, kieran-typescript, performance). This plan addresses all actionable findings in priority order.

P1 — High Priority Fixes

Fix 1–2: Wrap threadStore calls in route handlers with try-catch

Files:

• packages/appkit/src/plugins/agents/agents.ts — _handleChat (~line 700) and _handleInvocations (~line 740)

Problem: If threadStore.get(), .create(), or .addMessage() throws (e.g., DB unavailable), the async Express handler propagates uncaught and the client connection hangs with no HTTP response.

Fix:

• In _handleChat: wrap lines 702–718 (threadStore.get → threadStore.create → threadStore.addMessage) in a try-catch that returns res.status(500).json({ error: "Thread operation failed" })
• In _handleInvocations: wrap lines 740–764 (threadStore.create → for-loop of addMessage) in a try-catch that returns res.status(500).json({ error: "Thread operation failed" })

Fix 3: Early hosted-tool rejection in runAgent()

File: packages/appkit/src/core/agent/run-agent.ts — buildStandaloneToolIndex() (~line 144)

Problem: Hosted/MCP tools are included in the standalone tool index but error only at dispatch time. The adapter sees these tools, may try to use them, and gets a confusing mid-conversation error.

Fix: After the tool classification loop (after line 184), scan the index for kind: "hosted" entries. If any exist AND they weren't produced by toolkitEntryToStandalone (which already warns in the description), collect their names and throw:

runAgent: agent definition includes hosted/MCP tools [${names}] which are not supported in standalone mode. Use createApp({ plugins: [agents(...)] }) for MCP support.

Fix 4: Replace countUserStreams() O(n) scan with per-user counter

File: packages/appkit/src/plugins/agents/agents.ts

Problem: countUserStreams() (line 143) iterates all active streams on every chat request. At scale this is O(n) where n = total concurrent streams across all users.

Fix:

• Add a private field: private userStreamCounts = new Map<string, number>()
• In _streamAgent where activeStreams.set(requestId, ...) is called (line 779): increment the counter for userId
• In the finally block where activeStreams.delete(requestId) (line 895) and in _handleCancel where activeStreams.delete(streamId) (line 1081): decrement the counter for userId
• Replace countUserStreams(userId) body with: return this.userStreamCounts.get(userId) ?? 0

P2 — Moderate Fixes

Fix 5: Extract shared toolkit filtering helper

Files:

• packages/appkit/src/core/agent/toolkit-resolver.ts (lines 41–61)
• packages/appkit/src/core/agent/build-toolkit.ts (lines 25–62)

Problem: Both files independently implement identical prefix/only/except/rename filtering for ToolkitOptions. Bug fixes must be applied in two places.

Fix: Extract a shared helper function (e.g., filterToolkitKeys) that takes (localName: string, opts: ToolkitOptions, pluginName: string) => string | null (returns the final key or null if filtered out). Use it in both buildToolkitEntries() and the fallback path of resolveToolkitFromProvider().

Fix 6: Use isToolProvider type guard in resolveStandaloneProvider

File: packages/appkit/src/core/agent/run-agent.ts — resolveStandaloneProvider() (line 280–298)

Problem: instance as unknown as ToolProvider bypasses TypeScript entirely. A proper type guard exists at core/plugin-context.ts:308.

Fix: Import isToolProvider from ../plugin-context (or extract it to a shared location if circular imports are a concern). Replace the manual guard (lines 285–296) with:

if (!isToolProvider(instance)) {
  throw new Error(`runAgent: plugin '${pluginName}' is not a ToolProvider ...`);
}
// instance is now narrowed to ToolProviderPlugin
cache.set(pluginName, instance);
return instance;

Note: isToolProvider checks for asUser which standalone providers won't use. May need a lighter guard (isToolProviderLike) that only checks getAgentTools + executeAgentTool. Evaluate at implementation time.

Fix 7–8: Add missing tests

File: packages/appkit/src/core/agent/tests/run-agent.test.ts

Test 7: Plugin without ToolProvider methods

it("throws when plugin lacks getAgentTools/executeAgentTool", async () => {
  // Create a PluginData with a class that doesn't implement ToolProvider
  // Call runAgent with fromPlugin referencing it
  // Assert throws with "not a ToolProvider" message
});

Test 8: Sub-agent recursive execution

it("executes sub-agent tools via recursive runAgent", async () => {
  // Define parent agent with agents: { helper: childDef }
  // Mock adapter to call "agent-helper" tool
  // Verify child agent runs and returns text
});

P2 — Advisory (No Code Changes)

• (9) fromPlugin marker uses Symbol.for — forgeable in theory. Agent defs come from developer code; acceptable risk.
• (10) Sub-agent runner uses global agent registry — names come from static config, not runtime input.
• (11) New approval_pending event type in unions — downstream consumers with exhaustive switches need updating. Document in changelog.
• (12) AgentsPlugin 1200+ lines — consider future extraction. Not blocking.

P3 — Low Priority (Deferred)

• (13) New optional effect field — backward compatible, no action needed.
• (14) Cache getPluginNames() at setup time — minor optimization.
• (15) defineTool() trivial wrapper — DX decision, defer.

Verification

1. Build: pnpm build
2. Lint + typecheck: pnpm check:fix && pnpm -r typecheck
3. Tests: pnpm test — ensure all existing tests pass and new tests (7, 8) pass
4. Manual smoke test: Run pnpm dev and verify agents plugin loads, chat endpoint works, and sub-agent delegation works