Author an add-on

Start with a small managed script

A package directory contains addon.yaml and declared source files. This example is a private, local JSON echo tool, with no network or credentials. Create my-package/addon.yaml:

id: example_echo
version: 1.0.0
ward_api_version: 2
private: true
defaults:
  runtime: python
  run: [echo.py]
addons:
  echo:
    title: Echo
    description: Return the supplied text for a local test
    audience: owner_only
    tools:
      echo:
        stdin: {}
        input:
          text:
            max_length: 256
        output_schema:
          type: object
          properties:
            text:
              type: string
          required: [text]
          additionalProperties: false

Create my-package/echo.py:

import json
import sys

value = json.load(sys.stdin)
print(json.dumps({"text": value["text"]}))

Add my-package/README.md describing the tool, its inputs, outputs, runtime requirements and private/local purpose. The package validator requires a README even for this private example.

ward_api_version is the exact manifest key supported by this release. It is a retained contract name, not an instruction to install Ward. There is no nookins_api_version alias. Do not rename fields inside working manifests as a branding cleanup.

Validate and install the package using the extension guide. Configure an instance with package: example_echo and addon: echo, attach that instance to one agent, and preview/apply. Running the tool also requires the managed Python/workspace runtime and supported isolation; validation alone does not execute it.

Manifest fields

The running Forge contract and package validator determine the accepted schema. Defaults inherit from package to add-on to tool. Environment maps merge; scalar/run values use the nearest declaration. Standard runtime defaults are 30 seconds, 1 MiB per stream, JSON output and risk-based approval. Do not change approval requirements just to make a package validate.

API v1 and v2

API v1 inputs are required strings by default. position or flag maps them to argv; constraints such as min_length, max_length, minimum, maximum and enum produce JSON Schema. Use output: text for text stdout when appropriate.

API v2 selects runtime: python or runtime: node, with a normalized package-relative UTF-8 entrypoint. Dynamic inputs arrive as JSON on stdin, not dynamic argv. Fixed arguments remain fixed. A managed script sees only the verified runtime, read-only package, declared inputs, scratch/output areas and allowed network relay—not the Nookins home or host environment.

{package} and {data} are documented placeholders for package/data locations in applicable profiles; they do not grant arbitrary host paths. Public packages require provenance, compatible rights and publication-ready payloads. Do not edit generated package.yaml to grant capabilities; Nookins verifies authoritative source and payload digests.

Durable workflows

A public workflow uses private start, poll and optional finalize profiles with validated JSON-pointer mappings. It declares provider task ID/state/result/receipt pointers, terminal states, polling bounds and deadline. The task returns a Nookins job ID and resumes polling after restart.

A restart after a paid start request but before a provider ID is confirmed leaves an ambiguous outcome. It must not automatically replay the paid request. Poll retries are bounded and respect backoff/deadline. Another paid invocation needs a fresh approval. Keep receipts and operation IDs for recovery.

For agent-authored installation, enable forge deliberately and have the agent read Nookins.forge.contract, validate its source and present an exact proposal. The owner reviews all source files and permissions before installation.