Assistant Spec v1

Request the smallest useful authority

Every project starts with shimpz.assistant.toml. Unknown fields, duplicate identifiers, mutable release tags, unsafe paths, embedded credentials, and unsupported values fail validation.

schema_version = 1
id = "hello-pulse"
title = "Hello Pulse"
version = "0.1.0"
summary = "A minimal Assistant with one safe operation and one owner-disabled routine."
skill = "assistant/SKILL.md"

[artifact]
mode = "development"
source = "."
port = 8080
health_path = "/health"
architectures = ["linux/amd64", "linux/arm64"]

[[operations]]
id = "hello"
summary = "Return a friendly greeting."
input_schema = "schemas/hello.input.schema.json"
output_schema = "schemas/hello.output.schema.json"
approval = "none"

[permissions]
egress = []
services = []
assistants = []

[[routines]]
id = "pulse"
operation = "hello"
interval_seconds = 300
timeout_seconds = 10
jitter_seconds = 15
enabled_by_default = false
single_flight = true
idempotency_key = "{assistant_id}:{routine_id}:{scheduled_at}"

The machine-readable shape is the Assistant Manifest v1 JSON Schema. The SDK parser remains authoritative for cross-field, filesystem, and secret-safety checks that JSON Schema alone does not express.

Develop from source; release by digest

• development accepts only source = "." inside the project.
• release accepts only an immutable OCI image@sha256 reference.
• The internal port, health path, and Linux architectures are explicit and bounded.
• There is no manifest field for shell commands, arbitrary URLs, or dependency installation.

Expose names and closed data shapes

An operation has one stable identifier, input schema, output schema, summary, and approval policy. Its JSON schemas are local, bounded, and closed so an apparently harmless payload cannot become a generic credential or command channel.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "hello.input.schema.json",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 80
    }
  },
  "additionalProperties": false
}

approval = "none" means the operation itself asks for no user confirmation. It does not bypass a future controller grant. once and each-run describe requested approval behavior; their enforcement runtime is still pending.

Bind capabilities, never provider keys

A Service permission names the Service interface and exact operations. A credential reference is only a logical Capsule binding chosen by the owner. Meta, Cloudflare, Telegram, or other provider values stay in the responsible Service credential store and never enter this file, an Assistant environment, or logs.

[[permissions.services]]
id = "meta-ads"
interface = "shimpz.meta-ads/v1"
operations = ["meta-ads.read"]
credential_refs = ["primary-account"]

This fragment defines the target contract; it is not proof that the meta-ads Service or credential binding is released. The current SDK validates the request but cannot grant or execute it.

Schedule a declared operation, not arbitrary code

• A routine points to an operation already declared by the same Assistant.
• Intervals start at 60 seconds; timeout and jitter must fit inside the interval.
• Every routine starts disabled and requires an explicit owner decision.
• single_flight = true prevents overlapping executions.
• The idempotency template includes scheduled_at to make retries deterministic.

Spec v1 validates this contract. A persistent scheduler, pause/resume state, missed-run policy, and execution ledger are controller work still to be released.

Declare another Assistant's operation

permissions.assistants uses the same interface-and-operation allowlist. It never grants another Assistant's workspace, container, database, secrets, or generic network address. The mediated call transport and replay-safe capabilities are architecture only today; Redpanda does not replace caller identity or authorization.

Create and validate locally

From the root of a checked-out shimpz-sdk repository with Python 3.14: