@plurnk/plurnk-contracts 1.8.0 → 1.9.1

package/SPEC.md

@@ -15,7 +15,12 @@ is the single code API for those contracts.
 | Stopped-world client contract                                                   | `ProposalDisposition`, `ProposalProjection`         |
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
 | Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
+| Exterior adapter application calls                                             | `ApplicationPort`                                   |
 | Workspace MCP configuration                                                    | `McpServerDefinition`, `McpServerOptions`, `McpConfigurationOverlay` |
+| Worker Agent Skills definition                                                 | `SkillDefinition` |
+| Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
+| Worker Functionality lifecycle projections (family-neutral)                     | `FunctionalityCandidate`, `FunctionalityDiscoverQuery`, `FunctionalityDiscoverResult`, `FunctionalityDefinitionState`, `FunctionalityListResult`, `FunctionalityMutationResult` |
+| AG-UI discovery, client accounting, and shared conformance specimens           | `AguiDiscovery`, `AguiClientConformance`, `AguiConformanceKit` |
 | JSON Schemas                                                                    | `@plurnk/plurnk-contracts/schema/*.json`            |
 | Generated JSON result rendering                                                 | `renderJsonResult`                                  |
 | Local-model rails                                                               | `@plurnk/plurnk-contracts/plurnk.{gemma,qwen}.gbnf` |
@@ -25,6 +30,45 @@ is the single code API for those contracts.
 generated from the schemas; ANTLR is authoritative for accepted model-language
 syntax; GBNF remains the bounded generation aid described in §1.2.
 
+§agui-discovery-contract `AguiDiscovery` is the complete installed AG-UI+
+surface at one instant. `schemaVersion` identifies its discovery shape;
+`actions` maps each unique public name to exactly one `scope`, `inputSchema`,
+and `outputSchema`; `notifications` maps each unique event-family name to one
+`payloadSchema`; and `display` carries {§client-display-capabilities} without
+another presentation mechanism. The AG-UI owner supplies the built-in registry;
+an extension contributes the same schema-bearing action descriptor through its
+core module registration rather than creating a second action type.
+
+§agui-action-schema-enforcement The JSON Schema values in
+{§agui-discovery-contract} are executable boundary contracts, not prose or
+hints. The AG-UI boundary rejects an action input before dispatch when it does
+not satisfy the advertised `inputSchema`, rejects an owner's successful output
+when it does not satisfy `outputSchema`, and validates a known notification
+before projecting it to AG-UI. Schemas are discovery values owned by their
+registrants; validation must not annotate or otherwise mutate them.
+
+§agui-client-conformance `AguiClientConformance` is a language-neutral JSON
+document accounting for every action and notification in one
+{§agui-discovery-contract}. Each name is classified as `native` (dedicated
+client behavior), `generic` (lossless protocol support without dedicated UI),
+or `unsupported` with an explicit reason, and cites nonempty verification
+evidence. Each disposition declares the exact verification dimensions its
+evidence covers; native behavior includes admission and presentation, every
+action includes projection plus success and failure, and every notification
+includes framing plus projection. Validation requires exact action and
+notification key equality with the installed discovery surface; adding or
+removing a public capability therefore breaks every stale client matrix
+visibly. The contracts-owned report procedure resolves every cited evidence
+path and emits one record per member with its posture and verified dimensions;
+a stale or fictional citation fails the report.
+
+§agui-conformance-kit `AguiConformanceKit` is the one versioned,
+language-neutral corpus of raw SSE boundary specimens and AG-UI lifecycle
+sequences used by every client transport. Its JSON resource is test input, not
+a third protocol implementation: each client feeds the same chunks and events
+through its production parser and projection seam, then verifies the declared
+outcome. Specimen names are unique within their transport or lifecycle family.
+
 §json-result-rendering `renderJsonResult` is the one presentation serializer
 for generated JSON operation results. A top-level array remains one valid,
 compact JSON value but places each item on its own physical line by adding only
@@ -83,7 +127,7 @@ The schemas own the runtime-neutral shapes; core owns their stateful values.
 | ------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
 | `LoopFlags`               | Complete effective `mode`, `auto`, `noWeb`, `noInteraction`, and `noProposals`  | Validate/expand persisted partial policy before use                                    |
 | `ProposalDisposition`     | Client authority, or the loop's exact automatic accept/reject                   | Compute precedence from effective loop policy, proposal kind, and stale-target truth   |
-| `ProposalProjection`      | Identity, review target/body/attrs, effective flags, stale signal, disposition  | Derive one validated projection for live delivery and durable reconnect discovery      |
+| `ProposalProjection`      | Identity, `{ scheme, authority, pathname }` review target, body/attrs, effective flags, stale signal, disposition | Derive one validated projection for live delivery and durable reconnect discovery |
 | `ProviderUsage`           | Conventional input/output totals with cache and reasoning details                | Preserve observed quantities without replacing absence with zero                        |
 | `ProviderCost`            | Exact charged, estimated, or unknown monetary evidence                           | Normalize one monetary disposition for each physical provider request                    |
 | `ProviderRequestAccounting` | Usage and cost evidence for one physical provider request                      | Preserve request order across retries, failover, success, and failure                    |
@@ -250,7 +294,9 @@ separator is syntax rather than body content, while any additional preceding
 blank lines remain body content.
 
 §empty-section An empty section has no body lines between its heading and the next
-structural heading, tolerated separator, or EOF and normalizes to a null body.
+structural heading, tolerated separator, or EOF. Optional operation bodies normalize
+to null; PLAN admission normalizes its required semantic body to `[]`
+under {§plan-value}.
 
 | Element      | Canonical contract                                                        |
 |--------------|---------------------------------------------------------------------------|
@@ -324,7 +370,7 @@ governed by {§canonical-statement}; runtime conditions remain explicit below.
 
 | OP   | `[signal]`                    | `(path)`                                     | `<scope>`                       | `body`                         |
 |------|-------------------------------|----------------------------------------------|---------------------------------|--------------------------------|
-| PLAN | none                          | none                                         | none                            | required intended goals        |
+| PLAN | none                          | none                                         | none                            | required Plurnk Plan JSON array |
 | FIND | optional add log tags         | required target or glob                      | optional result range           | optional matcher               |
 | READ | optional add log tags         | required target                              | optional text region            | empty                          |
 | EDIT | optional add log tags         | required file or entry                       | required for an existing target | literal text                   |
@@ -345,10 +391,33 @@ Directed SEND and KILL delegate any present code to the addressed target's
 operation contract; a live process may interpret a KILL code as a Unix signal,
 but that interpretation does not define KILL generally.
 
-§plan-intended-goals **PLAN records working-state deltas.** Its concise body adds
-new material conclusions or unresolved questions and the current turn's priorities;
-it does not restate settled context. PLAN is public, durable log content—not provider
-reasoning. Dispatch records it and has no other runtime effect.
+§plan-value **PLAN carries one complete Plurnk Plan.** Its entries are the
+model's current working-memory inventory: durable findings are `memory`, finished
+actions are `completed`, open inquiries are `pending`, and active priorities are
+`in_progress`. Admission parses the JSON body — one JSON array document in any whitespace layout, including the {§json-result-rendering} spread the log projects — and supplies the neutral `medium`
+priority to each entry that omits it, and validates the canonical bare array:
+every entry has string `content`, `priority` in
+`high | medium | low`, and `status` in
+`pending | in_progress | completed | memory`. A nonempty plain-text,
+malformed-JSON, or otherwise invalid body becomes one `medium`, `in_progress`
+entry whose content is the exact authored body; admission performs no partial
+repair or list inference. An empty body becomes the planless `[]`
+value. Each PLAN completely replaces the current Plan; it never expresses a
+delta. The exact `turnOps` source remains forensic program evidence, while the
+normalized array is the sole semantic value used by AST, persistence, durable
+log bodies, and model-packet materialization. PLAN is public log content—not
+provider reasoning—and Plurnk initially mints no `_meta` values. Dispatch records
+the canonical value and has no other runtime effect.
+
+§plan-acp-projection **Only an ACP-facing boundary projects the model-native
+Plan.** It constructs ACP's `{ "entries": [...] }` Plan object from the internal
+array, maps each `memory` entry to ACP `completed`, and prefixes its content with
+exact "Memory: " framing without duplicating an existing prefix. Every other
+entry field remains unchanged, and the internal value is not mutated.
+The projected value validates against the separately owned ACP Plan schema pinned
+to ACP v1
+[`schema-v1.21.0`](https://github.com/agentclientprotocol/agent-client-protocol/tree/schema-v1.21.0)
+commit `272bf799f35a258c6a4107a0410ed361e83683d3`.
 
 §log-tag-signal FIND, READ, EDIT, COPY, MOVE, and BARE canonically express additions
 as `+tag`. Because those operations have no tag-selection semantics, ANTLR also
@@ -431,7 +500,7 @@ Mutation semantics:
 | WORK | Spawn acknowledgement; the deliverable arrives through the log                    |
 | FORK | Spawn acknowledgement; the inherited worker's deliverable arrives through the log |
 | KILL | Status of deletion or termination                                                 |
-| PLAN | Status of durable intended-goals logging                                          |
+| PLAN | Status of durable complete-Plan logging                                           |
 
 §find-result-unit For FIND, authored target shape fixes the paginated result
 unit. An exact target with a matcher pages flat match locations; a glob or
@@ -640,11 +709,11 @@ Example — a lane-0 turn stored inside a lane-2 EDIT body:
 
 ```plurnk
 # PLAN2
-Store the quoted turn.
+[{"content":"Store the quoted turn.","status":"in_progress"}]
 
 ## EDIT2 (worker:///quoted.plurnk)
 # PLAN0
-Answer from memory.
+[{"content":"Answer from memory.","status":"in_progress"}]
 
 ## SEND0 [200]
 Paris.
@@ -904,7 +973,7 @@ enforces both the schema and the relational endpoint invariants.
 ### §entry-read-result 13.3 Client entry reads
 
 `EntryReadResult` is the exact transport-neutral projection of one entry. It
-does not expose workspace IDs, storage owner IDs, split scheme/pathname fields,
+does not expose workspace IDs, storage owner IDs, split persistence-coordinate fields,
 scope, or other persistence columns.
 
 | Outcome | Exact shape                                                      |
@@ -1033,6 +1102,48 @@ environment declarations, then validates the resulting
 `McpServerDefinition`. Carrying the overlay does not connect, persist, or
 expand credentials by itself.
 
+`SkillDefinition` is the one definition the Worker `skills` Functionality
+family accepts and persists: the standard Agent Skills `name` (the directory
+name), the universal root `scope` (`project` or `global`), and — for a
+Worker-installed skill — the standard installer package `source` that
+provides it. `Validator.assertSkillDefinition` is the family's admission
+boundary; the filesystem under the scope's root, never the definition, is the
+truth about installation.
+
+`A2aAgentDefinition` is the one definition the Worker `a2a` Functionality
+family accepts and persists: the local alias `name` (the `a2a://<name>`
+authority), the remote `url` whose standard Agent Card remains the protocol
+authority, and optional local `cardPath`, `headers`, and bearer
+`authorization` whose token is a symbolic `${NAME}` reference.
+`Validator.assertA2aAgentDefinition` is the family's admission boundary.
+
+### §application-port 13.9 Exterior application port
+
+`ApplicationPort` is the single transport-neutral TypeScript contract through
+which an exterior adapter drives and observes the Plurnk application. Core
+implements it; AG-UI, A2A, and other interface modules consume it. The port
+contains typed application calls and a scoped event subscription, not wire
+route names, protocol framing, persistence access, or adapter-specific methods.
+An exterior adapter owns its own protocol validation, identity binding, and
+projection while reusing the same workspace, worker, loop, operation, proposal,
+interaction, and event owners through this port.
+
+`runLoop.source` is trusted causal provenance supplied by an adapter, distinct
+from user-authored prompt content. An adapter may expose no public means to set
+it; Core validates and records it through the same prompt admission path.
+
+§application-worker-observation Worker observation exposes durable identity,
+origin, and immediate parent identity. `readWorker` resolves exactly one id or
+name and returns `null` when absent. `listWorkers` filters collections by origin
+or lineage position; an omitted parent filter means every position and an
+explicit `null` means roots. Singular and plural cardinalities are distinct
+contracts. Observation is not a client binding or permission grant.
+
+§application-loop-observation Loop observation exposes the durable scheduler
+state and exact terminal `OperationResult` for one owned Worker. Exterior
+adapters consume this projection instead of reconstructing lifecycle from
+events or persistence; events remain the live notification edge.
+
 ## 14. Parse diagnostics
 
 §parse-diagnostics `PlurnkParseError` is a JSON-serializable Error subclass.