Skip to content

Agent Interface Contract

Assertions

AIF-001 - One immutable registry owns every agent operation

Contract: MCP and GPT Actions MUST derive tool names, schemas, effects, handlers, and exposure from one ordered immutable registry and invoke handlers through one validating executor. HTTP adapters MUST NOT maintain a second operation list or bypass schema validation and failure classification.

Evidence:

AIF-002 - MCP follows its advertised HTTP and stdio lifecycles

Contract: mcp serve MUST expose MCP Streamable HTTP on loopback /mcp by default. mcp stdio MUST exchange one JSON-RPC message per line over stdin/stdout, write no non-protocol content to stdout, open no MCP, Actions, health, or readiness listener, require no bearer credential for those absent interfaces, and stop cleanly at stdin EOF. Both transports MUST negotiate only supported protocol versions, implement initialize/initialized, tools/list, and tools/call, and return both text content and structuredContent. The server MUST advertise both transports through CLI capabilities and MUST NOT require a Markdown workspace.

Evidence:

AIF-003 - MCP exposes complete Joplin object workflows

Contract: MCP MUST support validated note, notebook, tag, and resource read/write workflows, relationship traversal, search, trash/restore for notes and notebooks, and permanent deletion only where Joplin has no trash API. Binary content MUST enter and leave as bounded base64 data, never a server-side path. Explicit create operations MUST compare their normalized natural identity before mutation, including matching trashed objects, and MUST return a non-retryable *_ALREADY_EXISTS error with every existing ID and the matching update tool rather than create or silently reuse a duplicate. Create preflight and mutation MUST be serialized within one bridge process.

Evidence:

AIF-004 - Invalid operations fail before side effects

Contract: Tool definitions and instances MUST pass the supported JSON Schema subset before handler execution. Unknown objects, invalid content, unsupported combinations, and Joplin failures MUST return structured stable domain errors rather than transport crashes or partial writes.

Evidence:

AIF-005 - Joplin outages do not terminate the bridge

Contract: Binding the agent listener MUST NOT require Joplin availability. Each call MAY perform a bounded availability wait and retry reads. An outage MUST return a retryable structured tool error and later calls MUST recover. Writes MUST be sent once after preflight; ambiguous outcomes MUST be non-retryable and exposed for operator inspection.

Evidence:

AIF-006 - Actions authentication is independent and fail-closed

Contract: GPT Actions MUST remain disabled unless explicitly enabled with a dedicated protected bearer file. Authentication MUST occur before route lookup, files MUST be re-read per request for rotation, malformed or duplicate authorization MUST fail closed, and Joplin, MCP, and Actions credentials MUST remain independent.

Evidence:

AIF-007 - OpenAPI is generated, deterministic, and secret-free

Contract: The Actions OpenAPI 3.1 document MUST be generated from the exposed registry for one strict production HTTPS origin. It MUST be deterministic and contain no credential, note data, local path, upstream Joplin URL, MCP route, or health route. Disabled operations MUST not be exported.

Evidence:

AIF-008 - Public transports enforce bounded resource use

Contract: MCP and Actions MUST bound request size, decoded resource size, JSON nesting, active handlers, and stalled connections. Actions MUST also bound response size, concurrent execution, and authenticated request rate. Oversized successful write results MAY be replaced by an explicit omitted result but MUST NOT be reported as a failed write.

Evidence: