Connections and hooks

The connection's name in the tenant, in its callback's URL: lowercase letters, digits and dashes, starting with a letter, at most 31. The tenant secrets its steps save start with it in capitals.

This plugin's tools whose calls may get its token.

What an admin gives when connecting: name, description, default, required, and choices, the values it may take when it is one of a few (the web UI shows a select). A default may name the tenant, such as "{tenant}-oz0". max_length is the most characters the param may have, such as an app name the other system limits: a longer value given is refused, and a {tenant} default is shortened to fit.

The steps the admin's browser goes through: name, description, browser, pkce, callback, exchange, save, and when, the params and values the step runs with ({account: user}); a flow skips a step whose params differ, and needs the params the steps it runs read.A guided step has no browser and runs on the edge's own page instead: create (a link that makes the app on the other system, json_query for a URL-encoded JSON document), copy (values to copy into its settings), paste (fields the admin pastes back, each a secret or a value with a format) and verify (checks that must pass: a request with expect, or a signed delivery to one of the plugin's event sources).A pasted field may be both a secret and a value.A guided step may offer a package: label, file (a .zip name), manifest (a JSON template) and icons (color, outline), which the edge builds. See guided steps.

What a call gets: kind (secret, jwt-exchange, client-credentials, identity, on_behalf_of or federated), secret, fallback_secret, jwt, the token request (method, url, headers, scope_field, resource_field, token_field, expires_field), for client-credentialsclient_id, client_secret (a tenant secret's name, which stays on the edge) and scope, with client_auth: private_key_jwt and client_key_id to sign a client assertion with a private key instead of sending a secret (private key), and pass.A client-credentialsurl names its host literally, or https://{params.<name>}/ when a guided step pastes the client secret (sent only to the origin it was pasted for).refresh renews a secret token a step saved: url, secret (the refresh token's tenant secret, saved by a step, which reaches no node), client_id, client_secret (a confidential client's; none for a public client; with a url on https://{params.<name>}/, a guided step pastes it, and it goes only to the host it was pasted for), scope and resource (refresh tokens).secret and fallback_secret are named with the connection's prefix and are never jwt.key; no step saves the fallback_secret; and requires.secrets may not name jwt.key, which reaches no node.For identity, use profile and audience; on_behalf_of exchanges a delegated token at url, with optional scope and client credentials. See Identity tokens.The federated kind uses the federated block for a cloud's short-lived credential and requires a credential-injection binding; see Clouds.

Which functions get a token: functions (<tool>.* for every function of a remote tool on the connection), and the scope and resource of each one's token.

Functions of the connection's tools that run once each time its last step is done, each as a tool job of its own: call (<tool>.<function>) and arguments, each a template of {params.*} and {values.*}. At most four (after connecting).

pre_tool_call, post_tool_call, job_start or job_end. pre_llm_call is accepted and does not run yet.

The function that answers, <tool>.<function>, of one of this plugin's tools (or its address with this plugin's own name).

For tool events: the <tool>.<function> names the hook applies to, or their addresses (github/oz0_github.*); * matches any function. Empty means every call. Each is at most 256 bytes (Addresses).

Only these agents' calls and jobs, by name or address (github/oz0-github). Empty means every agent of the tenant.

How long the hook may take, such as 2s. The default is 2 seconds, the most 30.

What a hook that does not answer in time, fails, or gives no decision counts as: allow, deny (the default) or escalate.

[allow, escalate] for a hook that may only let a call through or send it to a person: any other answer, a failure and a timeout count as escalate, its on_timeout must be escalate or left out, and its pre_tool_call event carries the job's request. No other list is accepted (Hooks that may only escalate).

[secrets] on a post_tool_call or job_end hook: the node tells the hook where the tenant's own secrets are in the result or the output, by path, position and name, never by value. plugin inspect lists it among the permissions, and a hook answered by a remote (url) tool may not ask for it (Known secrets in a result).