Choose the integration surface
Do not build a second credential store or bypass approval by moving application requests into the guest. Keep source attribution and licenses when adapting existing request mappings; current reused mappings retain their provenance under third_party/activepieces.
Define a bounded read and write operation
types.ts defines AppDefinition, AppOperation and RequestSpec. Each operation supplies a strict object input schema, a semanticwrite flag and a fixed request mapping. Encode path identifiers, bound strings and pagination, reject unknown properties, and keep host/method selection outside model arguments. A POST can be a read, as in Notion search; classify side effects by semantics rather than HTTP verb.
This illustrative excerpt belongs in an integrations/apps module. The .invalid service is deliberately unavailable; implement and test against your own controlled service before registration:
verify request. Add it to the applications list in registry.ts. A working reference is Todoist’s get_task / create_task in productivity.ts.
The current registry defaults to non-write operations. Explicitly selected writes receive approval and replay: 'never'. Its broker-facing method is derived from write; the actual upstream HTTP method comes from RequestSpec. Do not assume those are identical when auditing dispatch. Each Session binding still limits which connection and operation the Harness may use.
Add authentication and scoped verification
Default authentication is Bearer. Use AppDefinition’s auth hooks only where the provider requires a different header, compound credential or token exchange. Keep secrets out of operation arguments, schemas, result text, URLs and diagnostic output. The shared request path rejects redirects, bounds results, and redacts known credential values; that is not a substitute for reviewing provider response content and preventing secret leakage at the source. API keys use managed credential storage. OAuth uses the existing OAuth module, encrypted token envelopes and tenant/deployment app configuration. Declare actual endpoints, scopes and client authentication rules. Reuse the expiring one-use transaction bound to tenant, connection version, provider and redirect URI; do not implement an ad hoc callback or return tokens to the browser. Account/permission changes invalidate previous approvals. Token refresh has separate concurrency and version semantics. A successful identity request does not prove every selected operation is permitted. Add operation scopes, safe permission probes or metadata checks where available; otherwise leave the result unknown. Never validate write permissions by silently sending a message or creating a real object. Real acceptance writes need an explicitly authorized disposable target. Local disconnection does not establish provider-side grant revocation. Check tenant ownership at connection, Secret, OAuth transaction, Session binding and Tool-call lookup boundaries. An upstream object ID is not proof that a caller owns the Hexagon resource referring to it.Preserve approval and unknown-outcome semantics
The broker persists a call and request hash before dispatch, rejects the same call ID with different arguments, and pins dispatched connection/version and execution policy. Authorization establishes usable account access; approval permits a particular side effect. Neither replaces the other. Use the shared error classification. In the current application transport, 401 requests reauthentication; most other 4xx responses except 408 become rejected results; 5xx, transport failures and ambiguous response processing can leave the outcome unknown. Application-level error envelopes also need interpretation: a Linear mutation with GraphQL errors can have taken effect even withdata: null. Do not classify every HTTP 200 as success or every error body as proof of no write.
For a lost write response, stop and retain the original call. Query remote records using safe read operations or the provider UI. Then follow Tool reconciliation: resolve with the exact request_hash, observed outcome, result text and evidence. Resolution records an operator conclusion and does not send another upstream request. Repeating an identical resolution is idempotent; conflicting or stale decisions fail. If the remote result cannot be established, keep it unknown or cancel the Run; do not fabricate success or issue another create.
Similar waits require different decisions
Run state alone cannot distinguish approval from an unknown outcome. Inspect Tool call state, approval_id, execution_policy and resolution, and query the approval record where needed. An executing call after worker failure also requires a decision based on its persisted policy, not an assumption that no request was sent.
The broker has rules for replayable reads and explicit
idempotency_key policies. Named application writes currently use replay: never. An upstream POST used for reading can be represented as GET in the broker’s semantic policy; do not blindly copy upstream HTTP methods into replay decisions. If the invocation’s pinned connection_version differs from the current version, an unknown result cannot be replayed through the new configuration. Extending policy requires verifying upstream deduplication constraints; adding a field does not establish exactly-once effects.
Completed does not necessarily mean upstream success
A completed Tool call has a deliverable result, which can carryisError: true. AppRequestError produces a completed error result, as does authorization denial. A manual resolution with outcome: failed also completes the call and delivers failure content to the Harness.
Assert call state, isError / error code, external write count and expected Run continuation together. Checking completed alone mistakes permission denial or reconciled failure for business success.
Repeated and concurrent reconciliation
Resolve takes the same invocation lock as the broker. An in-flight request returnstool_call_in_flight, even if the worker lease has expired. The first decision requires an eligible active Run, an unknown call and its exact request_hash.
An identical saved decision can return idempotently; that check precedes the active-state requirement for a first decision. This does not let an old terminal Run accept a new decision. Different text, evidence or outcome conflicts with the prior resolution. Cancellation-race tests must distinguish returning an existing decision from submitting a new one rather than asserting that every resolve after cancellation fails.
Sources: ToolBroker, reconciliation transaction, and application request classification. See approval and Tool recovery contracts for HTTP requests and errors.
Test the concrete read/write pair
Use fake transport plus database-backed broker tests. For the example above, maintain an in-memory report store and a request counter in the test fixture. Return a known report for reads; let the write fixture store a report and deliberately lose its response to exercise uncertainty.
Existing regression entry points are:
TEST_DATABASE_URL as described in testing. Add assertions for the new provider rather than treating existing suite success as its coverage. OAuth changes also require state replay/expiry, refresh concurrency and permission-change tests.
Reuse the repository fixtures before adding another example
The report mapping above explains the extension seam; it is not a prerequisite to build a second application solely to test the broker. Reuse the existing concrete fixtures at the appropriate layer:
These suites are existing executable examples of the shared contracts, not proof that a newly added provider works. Add only the new provider’s mapping/authentication differences and any missing contract case. Database-dependent suites skip when
TEST_DATABASE_URL is absent; a skipped test cannot support an acceptance claim. Keep real-account status separate as described below.
Keep mapping tests separate from dispatch tests
Forread_report, an ID containing / must remain one encoded path segment; extra arguments must fail schema validation before any request. For create_report, inspect the fixed POST URL and JSON body independently of approval. A mapping test can prove those request shapes without an account, but it cannot prove that the broker waits, rejects a tenant mismatch or avoids a second write.
For the lost-response fixture, insert the report into the fake upstream store before throwing. Reconstruct the broker against the same database and keep the upstream store and counter. Read back the report using its business reference, then resolve the original call using its saved request_hash. Assert the upstream write counter remains one before and after resolution. Starting a new empty database or upstream store would make this test unable to detect replay. Real-account verification remains a separate step.