Skip to content

fix(runtime): make the WriteStdin contract derivable and drift-proof - #4378

Open
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:fix/write-stdin-contract-conformance
Open

fix(runtime): make the WriteStdin contract derivable and drift-proof#4378
liugddx wants to merge 1 commit into
apache:mainfrom
liugddx:fix/write-stdin-contract-conformance

Conversation

@liugddx

@liugddx liugddx commented Aug 31, 2026

Copy link
Copy Markdown
Member

What

WriteStdin exposes a loose provider schema (so providers that inject null/0/'' placeholders are tolerated) and enforces a separate strict validator. The two schemas were built inline inside buildWriteStdinTool, and the tool description carried no concrete payload. The net effect: a model cannot derive a single legal call from the tool alone — the published schema advertises shapes the strict layer rejects, and nothing tied the documented form to what the runtime actually accepts.

This change makes the contract derivable and keeps it from drifting:

  • Extract the two-layer schema pair into createWriteStdinSchemas() so the provider (loose) schema and the strict validator can be exercised together.
  • Add a concrete minimal example to the tool description: {"ref":"maka://runtime/background-tasks/<id>","actions":[{"type":"key","key":"enter"}]}.
  • Pin one minimal legal payload per action type in WRITE_STDIN_MINIMAL_EXAMPLES — text, named key, key chord, mouse click, mouse move, mouse scroll, and resize-only.

Why it's safe

Presentation- and test-only. No schema semantics, permission classification, or runtime behavior changes. The strict validator, its normalization, and byte caps are untouched — the factory extraction is a pure refactor, verified by the existing buildWriteStdinTool still consuming the same pair.

Tests

New describe('WriteStdin provider/strict contract conformance') in shell-tools.test.ts:

  1. every documented minimal example is accepted by BOTH layers — each of the 7 pinned payloads passes providerParameters and strictParameters.
  2. the description advertises a ref/actions example the schemas actually accept — the concrete example parsed out of the live description round-trips through both layers, so the doc can never drift from the runtime.
  3. provider null/0/'' placeholders are normalized away — a key action padded with every optional field set to a placeholder round-trips to the minimal {type:'key',key:'enter'}.
  4. strict validation is not vacuous (negative control) — a mouse click without a button, a non-canonical ref, and input+actions together are all rejected.

Causal proof (fail-without / pass-with): temporarily replacing the advertised description example with a strict-invalid shape (a mouse click missing its button) makes test 2 fail (# fail 2); restoring it returns the suite to green (# pass 14, the sole remaining failure being an unrelated pre-existing /bin/echo spawn test that only runs on POSIX). So the conformance tests gate the documented shape against the real schema rather than passing vacuously.

Part of #4267. Closes #4354.

WriteStdin publishes a loose provider schema and enforces a separate
strict validator, but the two were built inline in buildWriteStdinTool
and the description carried no concrete payload. A model could not
derive a single legal call from the tool alone: the published schema
accepts shapes the strict layer rejects, and nothing pinned the
documented form to what the runtime actually accepts.

Extract the pair into createWriteStdinSchemas() so both layers can be
exercised together, add a concrete minimal example to the description,
and pin one minimal legal payload per action type (text, named key,
key chord, mouse click/move/scroll, resize-only) in
WRITE_STDIN_MINIMAL_EXAMPLES.

Add a contract-conformance test asserting every documented example is
accepted by BOTH the provider and strict layers, that the advertised
description example round-trips through both, that provider null/0/''
placeholders are normalized away, and — as a non-vacuous control —
that genuine contract violations (mouse click without a button, a
non-canonical ref, input+actions together) are still rejected.

This is presentation- and test-only: no schema semantics, permission
classification, or runtime behavior change.

Part of apache#4267. Closes apache#4354.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/M Under 500 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

harness: WriteStdin provider schema and strict validator conformance (item 7 of #4267)

1 participant