refactor(appkit): restructure supervisor-api adapter per PR databricks#345 review#400
Open
hubertzub-db wants to merge 3 commits into
Open
refactor(appkit): restructure supervisor-api adapter per PR databricks#345 review#400hubertzub-db wants to merge 3 commits into
hubertzub-db wants to merge 3 commits into
Conversation
Apply Mario's defensive/correctness fixes from the supervisor API adapter
review without touching the public API shape (sections 1-8 will land in a
stacked branch). Highlights:
High
- Route the three SSE error-leak sites in supervisor-api.ts (streamBody
catch, mapEvent "error", output_item.done with id="error") through a
single emitError helper that returns a stable client-facing code
(`Supervisor API error (transport|upstream_failed|upstream_tool|
upstream_unknown)`) and logs the verbose detail server-side only.
Addresses CWE-209 verbatim-upstream-error-text leak.
Medium
- Gate the terminal {status:"complete"} emission on lastCompleted.status
/ .error / .incomplete_details so a `response.completed` with a nested
failed status no longer silently succeeds; surface as upstream_failed
instead. Regression tests added.
- Skip the terminal error in the streamBody catch when signal.aborted —
consumer-initiated aborts now end with a clean stop, not a contradictory
terminal error event. Regression test added.
- Tighten the output_item.done error match: require item.type === "error"
(or pair the reserved id="error" with a non-message type) so a stray
assistant message with id="error" is not mis-classified.
- Add maxLineChars / maxBufferChars caps to readSseEvents with 1 MiB / 8
MiB defaults; throw on overflow. Addresses CWE-770. Tests added.
- Docs: add a CWE-1427 callout warning that hosted-tool `description` is a
prompt-injection sink — do not derive it from untrusted input.
- Redact the no-delta warning log: summariseErrorPayload extracts a short
`type: message` line; full payload only via DEBUG. Addresses CWE-532.
- Gate the buffer-level CRLF normalize in sse-reader on `\r` presence to
skip the regex on LF-only steady state.
Low
- mapEvent("error") fallback no longer wraps "Unknown error" with literal
JSON quotes (uses string branch).
- Drop the misleading "we await the factory at module init" comment in
dev-playground; the code never awaits.
- Fix @example imports in supervisor-api.ts JSDoc to use
@databricks/appkit/beta (the actual public re-export).
- Replace trimStart() with single-U+0020 strip in sse-reader per the SSE
spec; remove the now-dead per-line `\r$` strip after the buffer-level
CRLF normalise.
- Flag streamPath as @internal in connectors/serving/client.ts noting the
CWE-918 SSRF risk if it ever leaks to user-controlled input.
- Add JSDoc warning to workspaceClient on SupervisorApiAdapterOptions:
passing a per-request OBO client would leak identity across requests
(CWE-664).
Signed-off-by: Hubert Zub <hubert.zub@databricks.com>
hubertzub-db
changed the title
…s#345 review Address structural feedback from Mario Cadenas' review of PR databricks#345 (sections 1-8). Stacked on top of the §9 defensive fixes commit. API changes (BETA surface only): - Add `DatabricksAdapter.fromSupervisorApi` static factory for discoverability alongside `.fromChatCompletions`. - Shrink `SupervisorApiAdapterOptions` to `{ model, workspaceClient? }`; tools no longer live on the adapter. - Hosted tools (`supervisorTools.*`) now return tagged `HostedSupervisorTool` records and accept named options instead of positional args. - Declare hosted tools on the agent's `tools` map (same place as function tools / sub-agents); the agents plugin and `runAgent` route them to the adapter via the new `AgentInput.extensions[SUPERVISOR_EXTENSION_KEY]`. - Add capability-negotiation fields to `AgentAdapter`: `acceptsExtensions?` + `consumesInputTools?`. The agents plugin and `runAgent` warn at registration when adapter capabilities don't match declared tools. Internals: - Extend `ResolvedToolEntry` / `StandaloneEntry` with a `hosted-supervisor` branch; `classifyTool` matches it before MCP hosted-tool rejection so standalone `runAgent` supports supervisor tools. - Defense-in-depth: both indexers throw if a `hosted-supervisor` entry is ever dispatched as a callable function. - `DatabricksAdapter.fromSupervisorApi` uses a dynamic import to avoid load-time cycles. Docs: - Rewrite supervisor-API section in docs/plugins/agents.md for the new shape. - Add cross-adapter sub-agent composition note (one-directional: chat parents can call supervisor children, not vice-versa, until SA's function-call events are routed back through `context.executeTool`). Playground: - Update dev-playground supervisor agent to the new shape (`DatabricksAdapter.fromSupervisorApi(...)` + tools on `createAgent`). Tests: - Rewrite supervisor-api.test.ts factory + adapter tests for the new shape. - Add `isSupervisorTool` and `DatabricksAdapter.fromSupervisorApi` tests. - New regression tests in `run-agent.test.ts` covering the hosted-supervisor extension-routing path and both capability-mismatch warnings. - New agents-plugin tests covering the same warning paths and the new `hosted-supervisor` tool-index branch. Signed-off-by: Hubert Zub <hubert.zub@databricks.com>
hubertzub-db
force-pushed
the
agent/v2/sa/1-adapter-fixes
branch
from
e86255e to
abe6d76
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Address structural feedback from Mario Cadenas' review of PR #345 (sections 1-8). Stacked on top of the §9 defensive fixes commit.
API changes (BETA surface only):
DatabricksAdapter.fromSupervisorApistatic factory for discoverabilityalongside
.fromChatCompletions.SupervisorApiAdapterOptionsto{ model, workspaceClient? }; tools no longer live on the adapter.supervisorTools.*) now return taggedHostedSupervisorToolrecords and accept named options instead of positional args.toolsmap (same place as function tools / sub-agents); the agents plugin andrunAgentroute them to the adapter via the newAgentInput.extensions[SUPERVISOR_EXTENSION_KEY].AgentAdapter:acceptsExtensions?+consumesInputTools?. The agents plugin andrunAgentwarn at registration when adapter capabilities don't match declared tools.Internals:
ResolvedToolEntry/StandaloneEntrywith ahosted-supervisorbranch;classifyToolmatches it before MCP hosted-tool rejection so standalonerunAgentsupports supervisor tools.hosted-supervisorentry is ever dispatched as a callable function.DatabricksAdapter.fromSupervisorApiuses a dynamic import to avoid load-time cycles.Docs:
context.executeTool).Playground:
DatabricksAdapter.fromSupervisorApi(...)+ tools oncreateAgent).Tests:
isSupervisorToolandDatabricksAdapter.fromSupervisorApitests.run-agent.test.tscovering the hosted-supervisor extension-routing path and both capability-mismatch warnings.hosted-supervisortool-index branch.