Onboarding: Generate real REST handlers for OpenAPI-discovered agents

[TalZaccai]

Summary

When the onboarding pipeline discovers an integration from an OpenAPI spec, the
scaffolder previously emitted only a stub action handler: the generated
agent could translate an utterance into an action, but the handler never called
the API. This PR adds a deterministic, fetch-based REST handler generator so
an OpenAPI-discovered agent issues real HTTP requests end to end.

What changed

• Discovery (parseOpenApiSpec) now captures the two things a REST handler
  needs:

  • Base URL — resolved from servers[0].url, with server-variable
    substitution and relative-URL resolution against the spec's fetched
    location; falls back to the spec origin when there is no servers entry.
    Left unset when it can't resolve to a well-formed http/https URL.
  • Parameter location — each parameter records its wire in
    (path/query/header/cookie, or body for request-body fields). Path-level
    and operation-level parameters are merged, and local
    #/components/parameters/* $refs are resolved inline.
  • Both are persisted on the ApiSurface and survive approval.

• Scaffolder routes to the new REST generator when the surface has a
  resolved baseUrl and REST-shaped actions; otherwise it falls back to the
  existing stub. Explicit non-REST patterns (websocket-bridge, native-platform)
  keep their own builders.

• Generated handler (from restHandler.template) builds the request URL
  from path/query parameters, sends a JSON body for POST/PUT/PATCH, applies a
  30s timeout, and returns truncated/pretty-printed responses with HTTP errors
  surfaced.

Scope / v1 limitations

• JSON OpenAPI 3 specs only (Swagger 2 and YAML yield no actions).
• Scalar path/query params only (no arrays/objects/style/explode).
• Header/cookie params: required ones fail the action, optional ones are
  dropped. No auth headers. DELETE requests carry no body.
• Non-local $refs (external files, deeper pointers) are skipped; an action
  whose path placeholder can't be resolved falls back to the stub handler.

Testing

Adds a tsx --test runner and 30 unit/integration tests: OpenAPI action
extraction, base-URL resolution, api-surface preservation, scaffolder REST
routing, codegen fixes, generated-handler compilation, and live
execution/E2E against the Open Library /api/books endpoint. All 30 pass.

[Copilot]

Pull request overview

This PR upgrades the onboarding pipeline for OpenAPI-discovered integrations so that, when discovery can resolve an absolute HTTP(S) baseUrl, the scaffolder generates a deterministic fetch-based REST action handler (instead of a stub), enabling true end-to-end HTTP execution for generated agents.

Changes:

• Extend OpenAPI discovery to (a) resolve/persist a baseUrl and (b) record each parameter’s wire location (in: path/query/header/cookie/body), including inline resolution of local #/components/parameters/* refs.
• Add a REST handler generator (restHandler.template + buildRestHandler) and route scaffolding to it only for REST-shaped patterns when apiSurface.baseUrl is available.
• Add a tsx --test test runner and a suite of unit/integration/E2E tests covering discovery, preservation, routing, codegen correctness, compilation, and execution.

Show a summary per file

File	Description
ts/pnpm-lock.yaml	Adds the tsx dependency to the workspace lockfile.
ts/packages/agents/onboarding/package.json	Adds test/test:local scripts using tsx --test and includes tsx in devDependencies.
ts/packages/agents/onboarding/src/scaffolder/scaffolderHandler.ts	Routes scaffolding to REST handler generation when apiSurface.baseUrl is present and the pattern is REST-appropriate.
ts/packages/agents/onboarding/src/scaffolder/restHandlerTemplate.ts	Introduces deterministic REST handler codegen and REST-action filtering for safe generation.
ts/packages/agents/onboarding/src/scaffolder/restHandler.template	New generated handler template implementing fetch requests with timeout, formatting, and error surfacing.
ts/packages/agents/onboarding/src/discovery/discoveryHandler.ts	Adds baseUrl + parameter in capture, local $ref param resolution, and exposes pure helpers for testing.
ts/packages/agents/onboarding/test/restRouting.spec.ts	Verifies buildHandler routing decisions between stub vs REST generator across patterns/baseUrl presence.
ts/packages/agents/onboarding/test/restHandlerExecution.spec.ts	Offline execution tests against a local HTTP server for path/query/body wiring.
ts/packages/agents/onboarding/test/restHandlerE2EBooks.spec.ts	End-to-end pipeline test: discovery → scaffolding → type-check → real local HTTP execution.
ts/packages/agents/onboarding/test/restHandlerCompile.spec.ts	Ensures generated handler type-checks via tsc --noEmit.
ts/packages/agents/onboarding/test/restHandlerCodegenFixes.spec.ts	Regression tests for codegen string correctness (path param substitution, no GET/DELETE bodies).
ts/packages/agents/onboarding/test/openApiExtraction.spec.ts	Unit tests for OpenAPI action extraction, param merging/ref resolution, and base URL resolution.
ts/packages/agents/onboarding/test/apiSurfacePreservation.spec.ts	Ensures baseUrl and parameter in survive discovery → approval persistence round-trip.
ts/packages/agents/onboarding/test/fixtures/openapi/book-api.json	Adds an OpenAPI fixture for extraction/base-url tests (relative server URL).
ts/packages/agents/onboarding/test/fixtures/openapi/book-api-absolute-server.json	Adds an OpenAPI fixture for persistence tests (absolute server URL).

Review details

Files not reviewed (1)

• ts/pnpm-lock.yaml: Generated file

Comments suppressed due to low confidence (1)

ts/packages/agents/onboarding/src/scaffolder/restHandlerTemplate.ts:176

• There are two consecutive, duplicated JSDoc blocks describing filterRestActions. Keeping both is redundant and makes future edits error-prone; remove the extra block so there is only one doc comment.

/**
 * Returns the subset of `actions` this generator can actually handle:
 * actions from the parseOpenApiSpec arm with a recognized HTTP method and a
 * `path`. Used by scaffolderHandler to decide whether to route to the REST
 * generator at all.
 */
/**

• Files reviewed: 14/15 changed files
• Comments generated: 1
• Review effort level: Low

[robgruen]

Mabe move this to the aiclient and maybe spec it out based on model...right now a lot of these are just arbitrary and don't really match the selected mode. We should have a function or config that sets this that callers can use instead of embedding this constant all over the place.

[TalZaccai]

Agreed the magic 4000 shouldn't be embedded. Pulled it into a single named DEFAULT_MAX_RESPONSE_CHARS in agent-sdk (next to the shared truncateText) so it lives in one place and callers reference it. Full model-aware sizing (budget derived from the selected model) really belongs in the host/dispatcher truncating tool results — the generated REST handler has no model context — so I've tracked that as a follow-up rather than bake fake model-awareness into standalone codegen. Happy to pick it up there if you'd like it in this PR. (8503913)