Dependencies and cross-plugin access

For: Plugin authors looking up manifest fields.

Look up the fields for dependencies and cross-plugin access.

requires

requires:
  optional_secrets: [WEB_SEARCH_KEY]
  settings:
    - name: WEB_SEARCH_URL
      description: The search backend's base URL
      format: url
      required: true
      example: https://search.example.com
    - name: WEB_SEARCH_BACKEND
      description: searxng or brave
      format: one_of
      values: [searxng, brave]
    - name: WEB_SEARCH_RESULTS
      description: How many results a search returns
      format: integer
      min: 1
      max: 50
      default: "10"
      group: Results
      label: Results per search
    - name: WEB_SEARCH_TIMEOUT
      description: How long a search may take
      format: duration
      min: 1s
      max: 2m
      default: 20s
      group: Results

uses

What the plugin's agents and flows use of other plugins, by the used plugin's name (its manifest's name, not its hub name). From v1.0 they reach their own plugin's tools and agents, oz.*, and what this lists, once a tenant admin grants it at install.

uses:
  github:
    version: ">=1.0, <2"
    source: hub:ai.oz0/github
    tools: [oz0_github.get_pull_request, oz0_github.merge_pull_request]
    agents: [oz0-github]

plugin lint checks the shape, and warns about an agent's tool, a flow's tool step, a delegation, a reviewer, a candidate, a colleague or a flow's agent step that names another plugin's tool or agent without uses: listing it, with the address to write. An address whose plugin uses: does not list is an error that gives the uses: line to add. A flow step whose agent is a ${{ expression }} reaches only agents it was granted at run time.

uses:
  email:
    version: ">=1.0, <2"
    tools: [oz0_email.send]
  servicenow:
    version: ">=1.0, <2"
    optional: true          # asked for only where the tenant has ServiceNow
    tools: [servicenow.get_incident, servicenow.update_incident]

A used plugin may have a uses: of its own: an install of this plugin grants the whole tree as one decision and installs what the tenant lacks, bottom-up. What an admin granted can be narrowed or revoked later (oz0 plugin revoke); the next install of a version that still lists it asks again.

Addresses

Every part has one address, <plugin>/<part>, and every field that names a part takes it beside the bare name:

• A bare name means this plugin's part. A bare name of another plugin's function or agent still works, since names are unique in a tenant, and plugin lint warns (OZ-S019): an error for verified plugins. plugin lint --fix writes the address.
• The plugin in an address is this plugin or one listed under uses:. Another is an error that gives the uses: line to add. A field marked "own only" takes only this plugin's name. A hook's match.tools and match.agents may name any plugin: a match only watches calls, and a uses: entry would also let the plugin's agents make them.
• What nodes see does not change. The loader writes each address's bare form into the bundle nodes get, so running jobs, recorded histories and older nodes see the names they saw before; the plugin's files keep what you wrote. Tool IDs and agent and flow names stay unique in a tenant: an address names the plugin, not a second part of the same name.
• A flow step whose agent is a ${{ expression }} is checked when it renders.
• Patterns and names are short. A function's name or pattern, in any field above that takes one (an agent's tools, built-ins such as oz.delegate too, a hook's match.tools, uses.<plugin>.tools, policy[].match), is at most 256 bytes, address included, and so is a flow step's agent: 256 bytes hold the longest address, <plugin>/<tool>.<function>.
  The edge matches these against tool calls, on every call, so loading a plugin refuses a longer one, at its place. A version installed before this bound that holds a longer one is left out where it is read (the edge serves none of it, and logs it) until it is installed again from a fixed manifest.

Back to oz0-plugin.yaml.