For AI agents: the complete documentation index is available at https://a3s-lab.github.io/ash/v0.1.0/en/llms.txt, the full documentation bundle is available at https://a3s-lab.github.io/ash/v0.1.0/en/llms-full.txt, and this page is available as Markdown at https://a3s-lab.github.io/ash/v0.1.0/en/guide/protocol.md.
ash
  • English
  • v0.1.0

      • ASH/1 protocol

      ASH/1 is the local machine protocol between a Coding Agent Harness and ash. It is not a POSIX shell language and does not parse Bash, Zsh, PowerShell, or CMD.

      Two transports

      • ash rpc: long-lived session. Every ASON document has a four-byte big-endian length; handshake comes first, then concurrent requests.
      • ash run: reads one bare canonical ASON document from standard input, executes it, and exits.

      The first rpc frame must be a handshake request. The server chooses a compatible protocol version, limits, and capability intersection, then returns one canonical handshake response. Noncanonical ASON, oversized frames, and unknown required fields fail before large allocation.

      Core operations

      OperationContract
      execDirect executable + argv, environment delta, stdin, deadline, and process-tree cancellation
      readBounded byte or line ranges and projection
      listStable directory traversal and metadata
      searchBounded text search, match context, and complete-result reference
      patchCompare-and-swap multi-file patch with preimage digests
      fsFile-only create/copy/move/remove transaction
      snapshotWorkspace manifest and reference-based delta
      batchAcyclic dependency graph, ready-node concurrency, and failed-descendant skipping
      refData formulas over retained evidence, including projection and safe materialization
      cancelCancel queued or active requests and descendants

      Data formulas

      Reference work uses one typed prefix operator instead of a numeric mode with unused nullable fields:

      a{p}:
[@7,d,0,64,p,l,t]

      This is the compact wire form of π_{p,l,t}(d[0:64]) over @7. Operators b/l/g/d/p/w mean byte slice, line slice, search, release, table projection, and workspace materialization. Formula arity is exact. Materialization also requires workspace-write capability and follows the journaled no-overwrite transaction path.

      Concurrency and order

      A persistent RPC session can run independent requests concurrently. Final frames still follow stable input sequence, so the model side spends no tokens recovering from scheduler races. Cancellation control frames bypass final-response ordering to stop target work promptly.

      Capabilities and permits

      Handshake admits only capabilities supported by both sides. When policy requires approval, ash returns a typed challenge. A trusted Harness signs a one-time permit bound to session, request, canonical action, policy fingerprint, and expiry. Replay, cross-session reuse, and modified actions fail.

      Exact fields and canonical fixtures live in docs/protocol.md and spec/fixtures/ason.