feat(core): add request-scoped action surfaces by tillkrueger02 · Pull Request #2811 · BuilderIO/agent-native

tillkrueger02 · 2026-08-12T07:37:33Z

Summary

Add an optional resolveActionSurface callback to interactive agent chat.
Treat the returned action names as a hard, request-scoped allowlist.
Apply the allowlist consistently to direct tool schemas, tool search, action prompts, sandbox tools, and durable background continuations.

Why

Apps sometimes need to expose different actions depending on the current user, organization, thread, or agent configuration.

Previously, the interactive agent chat used one static action registry for every request. Apps could authorize actions during execution, but they could not narrow the set of actions visible to the model for an individual request.

A request-scoped action surface allows apps to expose only the actions that are relevant and permitted for the current run, without replacing or duplicating the Agent Native chat runtime.

Changes

Add the public resolveActionSurface plugin option.
Pass request identity, organization, thread, mode, and available action names to the resolver.
Validate returned names against the registered action catalog and fail closed for unknown actions.
Remove omitted actions from:
- provider tool schemas
- tool-search
- generated action prompts
- sandbox bridge registries
Preserve resolved action surfaces across durable background continuations.
Keep concurrent request surfaces isolated.
Ignore forged internal continuation fields from ordinary chat requests.
Add versioned documentation, localized documentation, and a changeset.

Tests

Targeted Core regression tests: 397 passed
Full Core test suite: 824 files / 11,190 tests passed
Core typecheck passed
Workspace typecheck passed
Core build passed
Format check passed
Oxlint passed
All 51 repository guards passed
Representative browser/visual tests: 9 passed

A full workspace pnpm run prep was also attempted. The relevant Core, typecheck, and guard phases passed. Unchanged Calendar, Content, and Slides template tests produced unrelated failures or timeouts; this PR does not modify those packages.

Risk / Rollback

Risk: An incorrect resolver could return an unavailable action name or unintentionally return an empty action surface.
Mitigation: Unknown names fail closed, empty allowlists are handled explicitly, and the callback is optional.
Backwards compatibility: Existing apps are unchanged when resolveActionSurface is not configured.
Rollback plan: Remove the resolver configuration or revert this commit.

Checklist

github-actions · 2026-08-12T07:37:43Z

Visual recap — skipped

The visual recap job did not run for this pull request. This is informational only and does not block the PR.

Recap skipped for 4de0d1e: external fork PR requires a maintainer to apply the recap label to the current head SHA.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 93639b55cc

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-08-12T07:42:02Z

+  return filterPromptActionsToSurface(
+    actions,
+    getRequestRunContext()?.allowedActionNames,
+  );


Filter agent-team child registries through the request surface

When a resolver allows agent-teams but denies a template action, this helper scopes the run-code bridges only; createTeamTools still receives the unfiltered buildSubAgentActions registry at agent-chat-plugin.ts:2922-2926, and spawning snapshots those actions in browser-team-tools.ts:515-550. The parent can therefore delegate a prompt to a sub-agent that executes an action omitted from the hard allowlist. Apply the request surface to the child registry before spawning or persisting the task.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-08-12T07:42:02Z

+        (options?.systemPrompt ??
+          (lazyContext
+            ? PROD_FRAMEWORK_PROMPT_COMPACT
+            : PROD_FRAMEWORK_PROMPT)) + resolveRequestActionsPrompt("tool");


Filter static framework guidance with the action allowlist

When the surface omits framework actions such as tool-search, agent-teams, or manage-jobs, this still prepends the unchanged production framework prompt, whose directives name and recommend those tools (framework-core.ts:147,161 and framework-core-compact.ts:121,131). This contradicts the option's promise that omitted names are not sent to the model and encourages calls to tools that are absent from the provider schema. Generate or suppress framework guidance according to the resolved surface as well as filtering the generated action list.

Useful? React with 👍 / 👎.

steve8708 · 2026-08-12T10:56:41Z

great idea, thanks @tillkrueger02!

one last piece of feedback a review agent of mine found - if you agree would be great to get the fix in, then good to merge:

[P1] Preserve the request action surface for queued run-code executions

I found one remaining authorization gap in the durable sandbox path.

The foreground run-code entry is filtered through filterRuntimeActionsToSurface(...), which reads the current request’s allowedActionNames. However, when run-code is invoked with background: true, the queued execution persists only the code, owner, organization, and thread. The background worker reconstructs a context without the action allowlist before invoking the same runner.

As a result, the worker can fall back to the full action registry. A resolver that allows run-code but omits a read-only action could queue code such as appAction("omitted-action") and execute it later. Bridge tools such as provider or workspace access may also reappear. This conflicts with the hard-allowlist and durable-continuation guarantees described by the PR.

Please propagate the resolved action surface through the sandbox queue/worker context and add a regression test covering enqueue → worker execution → denied bridge/action call. If background run-code is intentionally out of scope, it should instead be explicitly disabled when a request-scoped surface is configured.

…action-surface # Conflicts: # packages/core/src/server/agent-chat-plugin.surface.spec.ts

builder-io-integration

Builder reviewed your changes — looks good ✅

Review Details

Code Review Summary

Reviewed the latest PR #2811 head for the request-scoped action-surface feature. The implementation propagates hard action allowlists through provider schemas, direct execution, tool search, prompts, plan mode, sandbox/run-code bridges, durable continuations, and agent-team workers. It also preserves organization binding across durable execution, distinguishes explicit org-less requests from legacy payloads, rejects inherited action names, and fails closed for malformed persisted authorization data.

The previously identified trusted-shell bypass, multi-organization sub-agent binding, durable run-code restoration, malformed persisted surface, and inherited-property issues were verified as addressed. Three parallel code-review passes found no new actionable bugs or security regressions. This is a high-risk authorization-sensitive change, but the current approach and regression coverage are sound.

🧪 Browser testing: Skipped — PR only modifies backend/config/docs, no UI impact

This comment has been minimized.

Sign in to view

chatgpt-codex-connector Bot reviewed Aug 12, 2026

View reviewed changes