adapter.toml reference

A Level-1 adapter is a single adapter.toml manifest. It is pure data, never executed; a generic engine interprets it to find, extract, and materialize JSONL sessions. This page is the schema reference; the workflow around it (create, validate, install, publish) is in Building adapters, and the contract it implements is the PAC specification.

A complete manifest

[adapter]
name = "myharness"           # registry name, [a-z0-9-]+
harness_id = "myharness"     # provenance id written into portable contexts
version = "0.1.0"
author = "you"
description = "myharness session adapter"

[session]
# Where the harness keeps its sessions. {home} (the user home dir) is the
# ONLY interpolation; no env vars, no command substitution, by design.
root = "{home}/.myharness/sessions"
glob = "**/*.jsonl"          # ** spans directories, * stays in one component
cwd_field = "/cwd"           # JSON pointer into the FIRST line (the header)

[extract]
session_id_field = "/session_id"   # header pointer; file stem when absent
role_field = "/role"               # per-line pointer to the message role
user_role = "user"                 # the role value marking a user message
content_field = "/content"         # the first user line's content = the task

[materialize]
# Templates for the forged session, one JSON object per line. Placeholders:
# {session_id} {cwd} {task} {digest} {ts_ms}. String values are JSON-escaped
# on insert, so keep them inside quotes ({ts_ms} is a bare number). The
# header line MUST carry {cwd} at cwd_field or the round-trip fails.
lines = [
  '{"session_id":"{session_id}","cwd":"{cwd}","ts":{ts_ms}}',
  '{"role":"user","content":"{task}"}',
  '{"role":"assistant","content":"{digest}"}',
]

`[adapter]`

Field	Meaning
`name`	The adapter’s registry name, `[a-z0-9-]+`. This is what you pass to `session export --harness` and `session materialize --into`.
`harness_id`	The provenance id written into portable contexts this adapter captures.
`version`	The manifest version string.
`author`	Who wrote it.
`description`	One line describing the adapter.

`[session]`

Field	Meaning
`root`	Where the harness keeps its sessions.
`glob`	The session file pattern under `root`. `*` spans directories; `` stays in one path component.
`cwd_field`	A JSON pointer into the FIRST line of the file (the header) that yields the session’s working directory.

`[extract]`

Field	Meaning
`session_id_field`	JSON pointer into the header line for the session id; the file stem is the fallback when absent.
`role_field`	Per-line JSON pointer to the message role.
`user_role`	The role value that marks a user message.
`content_field`	JSON pointer to the content of the first user line; that content becomes the task.

`[materialize]`

lines is a list of templates for the forged session, one JSON object per line. Available placeholders: {session_id}, {cwd}, {task}, {digest}, {ts_ms}. String values are JSON-escaped on insert, so keep them inside quotes; {ts_ms} is a bare number. The header line MUST carry {cwd} at cwd_field, or the round-trip fails.

How the engine uses the manifest

find: newest file under root matching glob whose header line’s cwd_field equals the working directory.
extract: session id from the header (file stem fallback); the task is the first line whose role_field equals user_role, read via content_field. Plan and file lists are honest-empty at Level 1: a manifest cannot describe tool-call schemas.
materialize: renders the lines templates with the context’s values and writes the forged session under root (into the glob’s leading literal directories, so the manifest’s own glob finds it).

tally adapter validate proves the manifest with the PAC conformance smoke: it materializes a marker context into a temp directory, extracts it back, and asserts the task is recovered verbatim, plus per-line JSON validity and the find path.

The shell-pattern scan

The manifest is pure data and is never executed, but tally adapter install refuses manifests containing shell-exec patterns unless you pass --allow-shell after reviewing the manifest. The refused patterns: $(, backticks, | sh, | bash, &&, curl, and ; inside templates.