@plurnk/plurnk-contracts 3.3.0 → 4.0.0

package/.env.defaults

@@ -9,3 +9,20 @@ PLURNK_PORT=1066
 # The whole URL a client dials instead: a remote portal, or a daemon bound to an address no
 # client can dial (0.0.0.0). Unset = http://$PLURNK_HOST:$PLURNK_PORT/agui.
 # PLURNK_AGUI_URL=
+
+# Whether the daemon authenticates ({§credential-authority}): 1 = every request to the client
+# interface and to the hosted agent presents a credential this daemon issued, and the daemon serves
+# the authorization server that issues them; 0 = no credential exists and every request is
+# anonymous, for a harness driving a daemon of its own. The posture is this value, never inferred
+# from what else is set.
+PLURNK_AUTH=1
+# The operator's client secret ({§agui-oauth-clients}): what the terminal client and every other
+# tool of yours exchanges for access tokens. Unset, the daemon mints one at every boot into the
+# file `secret` beside its database (0600), where a tool running as you reads it. Set it here, and
+# the same value in the tool's environment, for a tool on another host or under another user.
+# PLURNK_SECRET=
+# The operator's browser sign-in ({§agui-oauth-login}): the password a browser signs in with,
+# compared in constant time at the authorization endpoint. No browser is the operator without it:
+# while it is empty, the sign-in page says so and where to set it, and admits nobody
+# ({§agui-oauth-session}). The terminal client and your other tools use PLURNK_SECRET instead.
+PLURNK_PASS=

package/README.md

@@ -52,7 +52,9 @@ Validator.assertOperationResult(result);
 
 Generated wire types, constructors, and validators share the package root entry
 point described by SPEC {§wire-entrypoint}. Owning JSON Schemas use the published
-`@plurnk/plurnk-contracts/schema/*.json` subpaths.
+`@plurnk/plurnk-contracts/schema/*.json` subpaths. The root is runtime-neutral, so
+a browser type-checks it without Node; the application port that modules consume,
+which names Node's HTTP types, is `@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}).
 
 ## Development
 

package/SPEC.md

@@ -16,7 +16,7 @@ runtime-neutral wire envelopes; `@plurnk/plurnk-parser` implements the language
 | Stopped-world client contract                                                   | `ProposalDisposition`, `ProposalProjection`         |
 | Client-owned interaction contract                                               | `ClientInteractionRequest`, `ClientInteractionProjection`, `ClientInteractionResolution` |
 | Client capability presentation                                                 | `ClientDisplayCapabilities`                         |
-| Exterior adapter application calls                                             | `ApplicationPort`                                   |
+| Exterior adapter application calls                                             | `ApplicationPort`, from `@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}) |
 | Workspace MCP configuration                                                    | `McpServerDefinition`, `McpOAuth` |
 | Worker Agent Skills definition                                                 | `SkillDefinition` |
 | Worker outbound A2A agent definition                                           | `A2aAgentDefinition` |
@@ -295,11 +295,11 @@ wider bare fence nests where closing there would cost the reading more
 ({§fence-pairing}). A nested block ends at its first valid closer, as a CommonMark code block
 does. So a wider outer fence holds any narrower body, finished or not, and equal widths nest
 when every inner block closes. Preserve every nested body byte, including apparent operations
-and known executors, without dispatching them. These rules apply equally to model programs,
+and executor invocations, without dispatching them. These rules apply equally to model programs,
 stored programs, client operations, and reasoning quotations.
 
 §operation-fences **Accept three or more backticks; teach and render three.** A line-start fence
-of three or more backticks naming a native operation or registered executor opens that
+of three or more backticks carrying an operation heading ({§executor-heading}) opens that
 operation ({§indented-fences}), and no width draws a receipt. Three is the taught form and the
 rendered form; a wider fence is the same statement, and it is how a body holding fence lines of
 its own is held: an opener wider than any of them ({§balanced-fences}). Enclosing quotations
@@ -328,7 +328,7 @@ aside, an operand, or other heading text does not qualify and remains the unfenc
 read this way.
 
 §fence-heading-in-body Outside a complete nested block ({§balanced-fences}), a fence
-line of three or more backticks and a name that is a native operation or a known executor
+line of three or more backticks carrying a heading under {§executor-heading}
 is a heading. Inside an open block it either ends that block without closing it and opens the
 next statement, or it is a literal example held by the block. {§fence-pairing} chooses between
 the two. Fence lines of
@@ -356,8 +356,8 @@ input at once by {§fence-pairing}:
 | Indented four spaces or more, or by a tab | Body ({§indented-fences}) |
 | Fewer backticks than the block's own, or another character | Body, or the opener of a nested block |
 | At least the block's backticks, bare | The block's closer, or the opener of a nested block |
-| Labeled, naming nothing known | The opener of a nested block, or body |
-| Three or more backticks naming a native operation or known executor | A heading that ends the block, or a literal example |
+| Labeled, without an operation heading | The opener of a nested block, or body |
+| Three or more backticks with an operation heading ({§executor-heading}) | A heading that ends the block, or a literal example |
 
 ### §fence-pairing Fence pairing
 
@@ -499,12 +499,11 @@ by the next opener is {§inline-chain}, and by nothing is the ordinary {§fence-
 no ambiguity to resolve: a slot begins with `<` or `[` and an opener with a backtick run, so the
 shapes are disjoint.
 
-§executor-case **An executor tag in any case.** A fence tag that matches a
-registered executor's name case-insensitively opens that executor (`SH` opens
-`sh`), and the statement's `executor` is the registered spelling, so a lookup
-by that name never misses. Operation names stay uppercase by teaching and were
-never written otherwise in 12,000 fences; one `SH` in 1,300 `sh` fences was. An unregistered name without an accepted spelling
-({§executor-js-spelling}) is still prose ({§interstitial-fence}).
+§executor-case **An executor tag in any case.** An executor heading matches a
+known executor's name case-insensitively (`SH` opens `sh`); its AST carries the
+registered spelling when known, otherwise the lowercase name. Native operation
+names remain case-sensitive. Recognition follows {§executor-heading}; availability
+and permission are checked at dispatch, not granted by a recognized spelling.
 
 §executor-js-spelling When `node` is registered and `js` is not, `js` names
 `node` under {§executor-case}. Parsing normalizes the runtime before admission
@@ -529,8 +528,8 @@ line takes the rest of the line as the aside, with one warning-severity advisory
 A closed aside followed by more text is unchanged.
 
 §quotation **A fence that opens no operation quotes.** Outside a body, a line-start fence that
-is not an operation heading — unlabeled, tagged like a code block (`ts`, `json`), or naming
-nothing registered — opens a
+is not an operation heading ({§executor-heading}) — unlabeled or tagged like an unknown
+code language (`ts`, `json`) without invocation slots — opens a
 quotation that runs to its matching closer (same character, width at least the opener's) or to
 the end of the input. Everything inside is data: no operation runs there and native tool-call
 markup is not read ({§native-tool-calls}). An operation fenced inside an unlabeled code block
@@ -552,23 +551,29 @@ belongs in a properly nested body ({§balanced-fences}) or a quotation ({§quota
 So a model may show plurnk's own operations in an answer. Two exceptions keep programs whole:
 CommonMark's own rule that a backtick opener's line carries no further backtick, so
 ```` ```READ (x)``` ```` is inline code and quotes nothing after it; and a bare fence directly under
-a line carrying a fence run, which is an orphaned closer and quotes nothing. An unknown tag at
-any width is a code block and draws nothing, unless its line carries a target slot, `(…)`: that
-is an operation the model missed by its tag, and it draws one warning — `` `OP` is not an
-operation or a known executor here. `` An offset example draws nothing either
+a line carrying a fence run, which is an orphaned closer and quotes nothing. An unknown tag
+without invocation slots is a code block and draws nothing. An offset example draws nothing either
 ({§indented-fences}). Quotation outside an operation is
 response text under {§response-text}, not an executable program or a completion envelope.
 
 `plurnk.md` names the tab offset as the form for an example, in the aside of its nesting
 example, and shows its own examples offset; the other quoting fences are untaught: a tilde
-fence, an unlabeled fence and an unknown tag all quote. Each is a shape a model reaches for from ordinary Markdown rather than from this
+fence, an unlabeled fence and an unknown tag without invocation slots all quote. Each is a shape a model reaches for from ordinary Markdown rather than from this
 teaching, so honouring it protects an example the model already believed was safe
 ({§outside-text} places the scale). The offset is the one form that survives every
 fence style.
 
-§interstitial-fence Only a native operation or a known executor opens a block. A fence naming
-anything else, or nothing at all, opens no operation: outside a block it quotes under
-{§quotation}, inside a body it is body.
+§executor-heading **Syntax identifies an invocation; dispatch resolves its runtime.** A native
+operation or a known executor name opens a heading. An otherwise unknown fence name also opens an
+executor heading when the next non-horizontal-whitespace character starts an invocation slot:
+`(` for the target, `[` for metadata, or `<` for scope (not `<!--`, an aside). The same slot grammar
+then validates and binds it, including malformed-slot diagnostics and permitted slot ordering.
+Availability does not affect that parse. Known executors are the host's supplied vocabulary plus
+`sh`; knowing a name also permits its targetless, slotless form. Enclosing quotations, indented
+examples and reasoning-channel restrictions remain unchanged.
+
+§interstitial-fence Only a heading under {§executor-heading} opens an operation. Any other fence
+opens no operation: outside a block it quotes under {§quotation}, inside a body it is body.
 
 §closer-aside A closing fence followed on its line by one aside and nothing else
 is the closer; the aside is outside text. Read as body, that line would be written
@@ -655,7 +660,7 @@ beside owner metadata, not only a matcher carried inside its `pattern` option.
 
 | Element | Contract |
 |---|---|
-| Fence name | Reserved native OP, otherwise a registered executor or attached MCP service |
+| Fence name | Reserved native OP, otherwise an executor name under {§executor-heading} |
 | `(path)` | Target/program/tool slot; COPY and MOVE each have two resource operands |
 | `[metadata]` | One owner-interpreted block; options, never the op's input |
 | `<scope>` | Operation-specific numeric or anchored coordinates |
@@ -722,20 +727,18 @@ compact empty block or permit unmatched fences.
 | KILL on a log target | The matcher. Beside an option block's `pattern`, the first line of the distillation ({§log-kill-distillation}). |
 | EDIT | A sigil-led matcher ({§edit-pattern}), unless an option block carries the `pattern`; otherwise the body. |
 | COPY, MOVE | Ignored ({§transfer-resource-selections}). |
-| SEND, WORK, FORK, BARE, executors | One JSON object is the option block where the heading admits one ({§bare-option-object}); otherwise the body. |
+| SEND, WORK, FORK, BARE | One JSON object is the option block where the heading admits one ({§bare-option-object}); otherwise the body. |
+| executors | The input body, including an unbracketed JSON object; metadata requires brackets. |
 | NOTE, WAIT, KILL without a target | The body. |
 
 §bare-option-object A bare option object is the option block, where the house option array owns the
-block. On an operation that takes an option block and no bare matcher — SEND, BARE, WORK, FORK and
-every executor fence — heading text after the slots that is exactly one JSON object `{…}`, where the
+block. On SEND, BARE, WORK and FORK, heading text after the slots that is exactly one JSON object `{…}`, where the
 heading admits a block (BARE, WORK and FORK only after their target), is read
 as `[{…}]`: the AST carries the array form, the written heading renders it, and one
 warning-severity receipt names the indulgence in place of the {§heading-inline-body} advisory:
-"`SEND` took a bare option object; the taught form is `[{…}]`." The option array is a house
-convention, not a language rule ({§scheme-metadata-modifier}): an executor whose declared body is
-JSON ({§executor-invocation}), an MCP tool, reads the object as its body instead — its arguments,
-written on the heading line — under {§heading-inline-body}. The host names those executors to the parse
-(`ParseOptions.jsonBodyExecutors`). A heading that already carries a block keeps the object as
+"`SEND` took a bare option object; the taught form is `[{…}]`." Executor headings always read an
+unbracketed object as input under {§heading-inline-body}, regardless of registration or input media
+type; their metadata is only the bracketed slot ({§scheme-metadata-modifier}). A heading that already carries a block keeps the object as
 inline body. On FIND, READ and KILL the same text is the matcher
 ({§naked-pattern}), because a search for JSON text is legitimate; a bare matcher
 that parses as a JSON object draws one advisory saying so: "`{…}` was read as the
@@ -856,9 +859,10 @@ reasoning operations contribute neither execution nor normalization notices.
 
 §exec-executor-slot The fence name selects the executor directly: for example,
 `python3 (tools/report.py)` or `gitea (issue_list)` on the opening fence line.
-Reserved native OP names take precedence. Any other name is an executor fence: its
-AST carries the `runtime` tag and no operation keyword, then `target`, metadata, timing and body fields.
-Registration is checked by the runtime, not by the syntax parser. An attached
+Reserved native OP names take precedence. An executor heading's AST ({§executor-heading})
+carries the `runtime` tag and no operation keyword, then `target`, metadata, timing and body fields.
+Registration is checked at the invocation's execution point, after earlier operations settle
+({§op-execution-order}), not by the syntax parser. An attached
 MCP service uses that executor path and its owner validates the named tool and
 input-body JSON against its schema. Unknown names do not fall back to a shell.
 There is no runtime-less form: every execution names its runtime, and canonical
@@ -1094,8 +1098,7 @@ ingestion restriction: the parser decomposes arbitrary URL authorities.
 ## §matcher-prefix-claims 6. Bulk pattern matching
 
 FIND, READ, KILL, EDIT, and the COPY/MOVE operands accept an optional matcher
-through the `pattern` option ({§matcher-option}); the client-tier LOOK still
-carries its matcher as a body. AstBuilder assigns the dialect from the
+through the `pattern` option ({§matcher-option}). AstBuilder assigns the dialect from the
 matcher's leading characters. A leading prefix claims its dialect. Invalid
 claimed syntax never falls back to glob matching: it is the operation's own
 refusal ({§matcher-refusal}), not a parse error.
@@ -1160,8 +1163,8 @@ statements remain recoverable when their boundaries are trustworthy.
 
 - §pattern-body-single-line Every matcher is one physical line. On the protocol
   operations it is the heading line's text ({§naked-pattern}) or the `pattern` option's
-  JSON string ({§matcher-option}), one line by construction; the client-tier LOOK still carries its matcher as a body, and AstBuilder
-  rejects a multiline one before dialect classification. A regex that matches a
+  JSON string ({§matcher-option}); AstBuilder rejects a multiline one before dialect
+  classification. A regex that matches a
   newline uses the two-character `\n` escape. Non-matcher operation bodies remain
   multiline.
 
@@ -1178,7 +1181,7 @@ The operation column names the canonical AST operation after
 | Operation             | Canonical components                   | Meaning                                                                    |
 |-----------------------|----------------------------------------|----------------------------------------------------------------------------|
 | FIND                  | 0–2 positions                          | Inclusive resource or exact-target location positions ({§find-result-unit}; markerless first page under {§markerless-first-page}) |
-| READ / client LOOK    | 0/1/2/4 text coordinates               | Text projection from one exact selected file, entry, or log item           |
+| READ                  | 0/1/2/4 text coordinates               | Text projection from one exact selected file, entry, or log item           |
 | EDIT                  | 0/1/2/4 text coordinates               | Text replacement, deletion, prepend, or append                             |
 | COPY/MOVE source      | 0/1/2/4 text coordinates               | Region copied or moved from the selected source                            |
 | COPY/MOVE destination | 0/1/2/4 text coordinates after target  | Region replaced or insertion point at the destination                      |
@@ -1199,7 +1202,7 @@ body, while unsupported arity is a runtime failure.
 spelled `@` followed by exactly five Base62 characters (`0-9A-Za-z`) wherever
 its `L`, `SL`, or `EL` position denotes a line. Columns, prepend `0`, and append
 `-1` remain numeric. Exact READ, EDIT, COPY/MOVE source and destination,
-KILL, and client LOOK preserve these positions in `TextLineMarker`; core resolves them
+and KILL preserve these positions in `TextLineMarker`; core resolves them
 against the addressed current text before operation-specific numeric scope
 semantics run. FIND's result positions remain numeric and reject anchors. Numeric text scopes remain
 canonical and fully supported. Parser acceptance does not imply model-facing
@@ -1386,8 +1389,8 @@ reports how many recorded turns concluded in a way the current contract would re
 
 ## 12. Public API
 
-The package root is the single JavaScript and TypeScript entry point. Shared AST
-and wire types come from generated schemas; the small hand-maintained parser
+The package root is the single JavaScript and TypeScript entry point for the language and wire
+contracts ({§runtime-neutral-root}). Shared AST and wire types come from generated schemas; the small hand-maintained parser
 types cover ordered parse items and `PlurnkParseError`, which JSON Schema cannot
 express. Consumers never receive ANTLR parse-tree or token types.
 
@@ -1415,7 +1418,6 @@ blocks themselves are the program.
 |--------------------------------|----------------------------------------------------------------|-----------------------|
 | `PlurnkParser.parse`           | One model turn, including recoverable outside text and operation diagnostics | `PlurnkStatement`     |
 | `PlurnkParser.parseStatements` | Zero or more protocol statements                              | `PlurnkStatement`     |
-| `PlurnkParser.parseClient`     | Executable blocks, including the read-shaped LOOK command        | `ClientStatement`     |
 
 Every entry point returns ordered `statement` and `error` items. The model-turn
 entry point also returns `text` items under {§response-text}. When present,
@@ -1423,6 +1425,14 @@ entry point also returns `text` items under {§response-text}. When present,
 extent. The statement `op` field discriminates the generated per-operation
 union.
 
+§runtime-neutral-root **The package root is runtime-neutral.** A browser type-checks it with DOM
+libraries and no Node globals: nothing it reaches names a Node module or global. The application port
+({§application-port}), whose HTTP host hands an adapter Node's request and response ({§http-host}), is
+the one Node-bound contract and its own types-only entry, `@plurnk/plurnk-contracts/port`, with
+`HttpHost` and `HttpRouteHandler`; the types it speaks stay in the root. A helper that reads a request
+takes only its headers (`RequestHeaders`), which a Node request satisfies. Lint checks the root's whole
+source graph under those settings (`tsconfig.browser.json`).
+
 §root-value-api The package-root runtime namespace is closed. Its exact membership has one home,
 `src/index.test.ts`, which fails on any addition or removal; the table names the families and
 their owners. All other root exports are TypeScript types. `PlurnkParser` and `parsePath` are not
@@ -1443,8 +1453,8 @@ among them: the parser is `@plurnk/plurnk-parser`'s ({§parser-consumers}).
 
 The remaining values are small pure helpers over those contracts (`isExecution`, `writtenOp`,
 `lifecycleOfLoopStatus`, `selectWorkerLoop`, `renderJsonResult`, `formatJsonDocument`,
-`aguiConformanceReport`) and the closed name patterns and vocabularies (`RUNTIME_TAG`,
-`SKILL_NAME`, `EFFORTS`).
+`aguiConformanceReport`, `requestOrigin` for {§http-request-origin}) and the closed name patterns
+and vocabularies (`RUNTIME_TAG`, `SKILL_NAME`, `EFFORTS`).
 
 §parser-construction-boundary Parser construction components are internal rather
 than alternate consumer entry points:
@@ -1678,7 +1688,8 @@ authority, and optional local `cardPath`, `headers`, and bearer
 
 `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
+implements it; AG-UI, A2A, and other interface modules consume it from
+`@plurnk/plurnk-contracts/port` ({§runtime-neutral-root}). 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
@@ -1700,13 +1711,13 @@ it; Core validates and records it through the same prompt admission path.
 `runLoop.attachments` carries typed bytes selected by the adapter;
 `runLoop.envelope` retains opaque protocol evidence under
 {§message-envelope-evidence}. `readMessages` projects durable inbox messages
-and successful conversation replies independently of log visibility, retaining
+and successful replies independently of log visibility, retaining
 each reply's `answers` addresses (empty for incoming messages).
 `resolveClientInteraction` may carry the accepted answer's message evidence;
 Core validates the resolution, retains the arrival, then resumes the operation.
 
 §application-worker-observation Worker observation exposes durable identity,
-origin, immediate parent identity, minted `kind` (`conversation`; `fork` for a
+origin, immediate parent identity, minted `kind` (`root` for a worker with no parent; `fork` for a
 child carrying a fork boundary; `work` for any other child), and `lifecycle`,
 the worker's representative work loop projected through {§loop-lifecycle-vocabulary} (`idle`
 when it has none). `selectWorkerLoop` chooses running before parked before queued;
@@ -1729,7 +1740,11 @@ in `@plurnk/plurnk-contracts` is that projection's one owner.
 
 §application-loop-observation Loop observation exposes the durable scheduler
 state of work loops (excluding maintenance-only administrative loops), nullable
-`waitUntil` (the durable observation deadline in Unix milliseconds), exact terminal `OperationResult`, and exact count of packet-bearing
+`waitUntil` (the durable observation deadline in Unix milliseconds), the times a loop first
+ran (`claimedAt`, {§loop-claim-latency}) and concluded (`terminatedAt`), ISO 8601 UTC and null
+until they happen, exact terminal `OperationResult`, the operation that opened the loop
+(`invocation`: its Worker and log address, {§worker-obligations}; null when no Worker's operation did),
+and exact count of packet-bearing
 Turns for one owned Worker. Packetless producer Turns and physical provider
 retries do not contribute to `packetCount`. Exterior
 adapters consume this projection instead of reconstructing lifecycle from
@@ -1756,8 +1771,8 @@ class PlurnkParseError extends Error {
 ```
 
 §parse-admission **A diagnostic's severity does not describe whether an operation ran.**
-`operationOmitted` identifies unexecuted unfenced operations, unknown operation-shaped
-tags and unrecovered native calls. A warning about a retained operation or a quoted
+`operationOmitted` identifies unexecuted unfenced operations and unrecovered native
+calls. A warning about a retained operation or a quoted
 example does not set it. This fact survives serialization when true; consumers do
 not infer it from diagnostic wording. It does not independently prescribe a strike.
 
@@ -1969,6 +1984,11 @@ intent ({§diagnostic-observation}).
 Unexpected top-level text immediately after a closed operation identifies that
 operation's opening line, closing line, and matching backtick count.
 
+§parse-attempt A hard fact that refused a statement the parser opened carries its `attempt`: the
+statement's text exactly as written, from its opening fence as far as the parser read it, and the
+`verb` that fence names, an operation keyword or an execution's runtime tag. A diagnostic that refused no opened
+statement, such as a lost boundary or a stray character outside every statement, carries none.
+
 Examples of canonical hard facts:
 
 - `unrecognized character '<' in target`