5 Reference

9.3.0.2

Racket

5 Reference🔗ℹ

Complete, neutral description of every module, binding, parameter, and struct exposed by Stone. Organized by module. Every binding’s documentation is co-located with its module, so require-ing a module is the way to discover the vocabulary it adds.

5.1 stone/edge🔗ℹ

(require stone/edge)

package: Stone

Composition primitives. Every binding in this module produces or consumes a ashlar-meta. See Edge Primitives for the conceptual model.

struct
(struct ashlar-meta ( fn
produces-all
queries
children
lens
name
schema
validate-walk
middleware
rebuilder)
    #:transparent)
  fn : procedure?
  produces-all : (listof symbol?)
  queries : (listof symbol?)
  children : (listof ashlar-meta?)
  lens : (or/c procedure? #f)
  name : symbol?
  schema : (or/c hash? #f)
  validate-walk : (or/c procedure? #f)
  middleware : list?
  rebuilder : (or/c procedure? #f)

The structure wrapping every ashlar. prop:procedure at position 0 means a ashlar-meta is callable: applying one to a DAG runs fn and returns a DAG.

fn — runtime function, (dag? -> (values node? dag?)).
produces-all — every node type this ashlar or its subtree can produce.
queries — node types read from the DAG that no earlier sibling produces.
children — child ashlars; '() for leaves.
lens — lens attached to the ashlar (set by ashlar-match when its extractor is a lens).
name — name used in logs and validation messages.
schema — JSON schema for structured outputs.
validate-walk — walk rule used by the validator’s driver.
middleware — middleware list when the ashlar is an agent ashlar.
rebuilder — closure that can rebuild this ashlar with substituted children or middleware; used by ashlar-with-tool-stub.

procedure
(make-ashlar fn
[ #:produces produces
#:queries queries
#:name name
#:children children
#:lens lens
#:schema schema]) → ashlar-meta?
  fn : procedure?
  produces : (or/c symbol? #f) = #f
  queries : (listof symbol?) = '()
  name : (or/c symbol? #f) = #f
  children : (listof ashlar-meta?) = '()
  lens : (or/c procedure? #f) = #f
  schema : (or/c hash? #f) = #f

Wrap a (dag? -> node?) function as a atomic ashlar. Returning a non-failure node appends it to the DAG; returning a failure node leaves the DAG unchanged. #:name defaults to #:produces, else a fresh ashlar-* id. Emits 'ashlar-start and 'ashlar-end events on each run.

syntax
(~> ashlar ...)

Sequence primitive. Runs each ashlar in order, threading the DAG. produces-all is the union of children’s produces; queries is the subset of child queries not satisfied by earlier siblings. A sequence of zero ashlars returns an 'empty-sequence failure; it stops at the first failing child.

procedure
(run-ashlar ashlar
[ dag
#:record record
#:loop loop?]) → dag?
  ashlar : ashlar-meta?
  dag : (or/c dag? #f) = #f
  record : (or/c record? #f) = #f
  loop? : boolean? = #f

Top-level entry point. Returns the produced DAG.

Bare (run-ashlar ashlar dag) — runs ashlar once over dag, pure and ephemeral (no journal, no threshold).
Durable (run-ashlar ashlar #:record r) — runs ONE forward pass over the record’s DAG, journaling progress and binding the record’s threshold as (current-threshold). Resumable: replaying over a journal that already holds atomic completions skips the recorded leaves and re-runs from the crash point. dag and #:record are mutually exclusive.
Session loop (run-ashlar ashlar #:record r #:loop #t) — folds the topology over the record unbounded until the terminal head is a session-terminal halt (a 'user-quit or 'input-ended halt node). Requires #:record. This is what run-tui drives on its background thread.

See Run a durable, resumable session for the record / journal / resume model and stone/record for open-record.

syntax
(ashlar-loop body #:until predicate #:max max-iterations)

predicate = (any-expr)

max-iterations = exact-nonnegative-integer?

Bounded repetition. #:until accepts a procedure (dag? -> any/c). Invoked after each body iteration with the loop’s accumulated DAG. The loop terminates when the predicate returns a true value or when #:max iterations have run. A failure from body aborts the loop immediately. Exhausting #:max emits a 'loop-exhausted failure. Iteration N+1 sees every node iteration N produced.

To wrap a node-shaped predicate that only inspects the latest head, see on-latest.

syntax
(ashlar-match extractor maybe-name [val branch] ...)

maybe-name =
| #:name name

Macro; branches collected statically.

extractor is either a lens? or a procedure.

A lens? is applied to the latest head’s content (the value of (node-content (dag-latest-head work-dag)) at the lens’s path).
A procedure is called with the work DAG and must return a value matching one of the val keys.

The branch whose val equals the extractor’s return value runs against the work DAG. If no branch matches, a 'match-failed failure node is appended.

Halt heads. When the latest head is a halt node, ashlar-match bypasses the extractor and routes to the branch keyed by the halt’s halt-node-kind (e.g. 'declined, 'user-quit) — so a single match can catch a cancelled ask-human alongside its normal answer branches. With no matching kind branch, the halt passes through as the terminal head.

See also Edge Primitives for the conceptual model and on-latest for wrapping a node-shaped extractor.

procedure
(on-latest pred) → procedure?
pred : procedure?

Returns a procedure that, given a DAG, applies pred to (dag-latest-head dag). Use to wrap a node-shaped predicate or extractor as a dag-shaped one when only the latest head matters. When the DAG is empty, the wrapped predicate is called with #f; callers should only use on-latest where a head is guaranteed.

procedure
(ashlar-map extractor body [#:name name]) → ashlar-meta?
  extractor : procedure?
  body : ashlar-meta?
  name : (or/c symbol? #f) = #f

Data-dependent fan-out. extractor is (node? -> list?); each lane runs against a snapshot DAG with a synthetic 'map-item node carrying the item. An empty extractor result produces 'map-empty. Must be followed by ashlar-reduce in any position where its last-result would be read.

procedure
(ashlar-parallel [#:name name] lane ...) → ashlar-meta?
name : (or/c symbol? #f) = #f
lane : ashlar-meta?

Static fan-out. Each lane runs against the pre-fan-out DAG. With zero lanes, produces 'parallel-empty. Must be followed by ashlar-reduce like ashlar-map.

procedure
(ashlar-reduce ashlar [#:name name]) → ashlar-meta?
ashlar : ashlar-meta?
name : (or/c symbol? #f) = #f

Marks ashlar as a reducer. Runtime behavior is identical to ashlar; the wrapper exists as a topology marker for the validator and forwards schema and name from its child.

procedure
(make-ask-human #:format-fn format-fn
#:name name
#:produces produces
[ #:queries queries]) → ashlar-meta?
  format-fn : (dag? . -> . string?)
  name : symbol?
  produces : symbol?
  queries : (listof symbol?) = '()

Builds an ashlar that solicits a question — built by format-fn from the current DAG — through the run’s threshold (current-threshold), blocks until a supervisor resolves it, then produces a node. An answer becomes a typed produces-node (the answer stored under both produces and 'text, so node-text reads it cleanly). A cancellation — an attended supervisor’s decline ('declined) or an unattended 'user-quit — becomes a make-halt-node of that kind, which a ~> sequence short-circuits on. There is no channels argument; the threshold is the single opening a supervisor observes and answers through (see stone/threshold and Ask Human). Under a bare (no-record) run there is no bound threshold, so an ask-human ashlar only runs inside run-ashlar #:record or run-tui.

procedure
(make-scoped-ashlar body
#:walk walk
[ #:children children
#:produces produces
#:queries queries
#:name name]) → ashlar-meta?
  body : procedure?
  walk : procedure?
  children : (listof ashlar-meta?) = '()
  produces : (or/c symbol? #f) = #f
  queries : (listof symbol?) = '()
  name : (or/c symbol? #f) = #f

The single factory underneath every ashlar in the framework. Takes a (dag? -> dag?) body plus a walk rule and returns a ashlar-meta. Most users never call this directly — reach for it when building a new composition primitive.

procedure
(ashlar-produces s) → (or/c symbol? #f)
s : any/c

Last symbol in ashlar-meta-produces-all, or #f if s isn’t an ashlar.

procedure
(ashlar-queries s) → (listof symbol?)
s : any/c

The ashlar’s queries list, or () if s isn’t a ashlar.

procedure
(ashlar-produces-all s) → (listof symbol?)
s : any/c

The ashlar’s full produces-all list, or () if s isn’t an ashlar.

5.2 stone/dag🔗ℹ

(require stone/dag)

package: Stone

Content-addressed, append-only typed DAG. See The DAG as Ashlar State for the conceptual model.

5.2.1 Nodes🔗ℹ

struct
(struct node (id parents content meta ts type)
    #:transparent)
  id : string?
  parents : (listof string?)
  content : any/c
  meta : hash?
  ts : real?
  type : symbol?

Node in the DAG. id is a SHA-1 digest over sorted parents, type, and content. type is the node-type symbol (e.g., 'data, 'failure, or any domain symbol). Prefer make-typed-node or typed-node over the raw constructor.

procedure
(make-typed-node parents type content [meta]) → node?
  parents : (listof string?)
  type : symbol?
  content : any/c
  meta : hash? = (hash)

Creates a typed node with the given type. Id is hashed from sorted parents, type, and content.

procedure
(typed-node d type content) → node?
  d : dag?
  type : symbol?
  content : any/c

Convenience wrapper over make-typed-node that defaults parents to (dag-heads d) — the ~99% case. Use this in make-ashlar bodies.

procedure
(node-get n field [default]) → any/c
  n : (or/c node? #f)
  field : symbol?
  default : any/c = #f

Pulls field out of n’s content hash. Returns default when n is #f, when content isn’t a hash, or when the key is missing.

procedure
(node-get* n path ...) → any/c
n : (or/c node? #f)
path : symbol?

Nested hash walk. Returns #f at any level that isn’t a hash or doesn’t contain the next path segment.

procedure
(node-text n) → string?
n : (or/c node? #f)

Returns the text representation of n: the raw string content, or the 'text field of a hash content, or (format "~a" content) as a fallback. Returns "" when n is #f.

procedure
(make-failure-node parents kind reason [meta]) → node?
  parents : (listof string?)
  kind : symbol?
  reason : string?
  meta : hash? = (hash)

Creates a typed node with type 'failure and content (hasheq 'kind kind 'reason reason). Invokes the failure-log-handler parameter; stone/logging installs a handler that emits an 'error-level event.

procedure
(failure-node? v) → boolean?
v : any/c

#t iff v is a node? whose node-type is 'failure.

5.2.2 DAGs🔗ℹ

struct
(struct dag (nodes heads root parent label)
    #:transparent)
  nodes : (hash/c string? node?)
  heads : (listof string?)
  root : (or/c string? #f)
  parent : (or/c dag? #f)
  label : symbol?

nodes maps ids to nodes. heads is the current head list; new nodes are appended to the end. parent points at the enclosing DAG for composites’ sub-DAGs; label is the scope label (e.g. 'root, 'loop-body).

procedure
(make-dag [#:parent parent #:label label]) → dag?
parent : (or/c dag? #f) = #f
label : symbol? = 'root

Empty DAG. The framework passes #:parent and #:label when building sub-DAGs; most user code calls (make-dag) for a fresh ashlar root.

procedure
(dag-append d n) → dag?
d : dag?
n : node?

Returns a new DAG with n in nodes, n’s parents removed from heads, and n’s id appended to the end of the heads list.

procedure
(dag-heads d) → (listof string?)
d : dag?

Accessor for the heads list.

procedure
(dag-latest-head d) → (or/c node? #f)
d : dag?

Returns the most recently appended head node, or #f if the DAG has no nodes. Shorthand for resolving the last id in dag-heads against dag-nodes.

procedure
(dag-nodes d) → (hash/c string? node?)
d : dag?

Accessor for the node table.

procedure
(dag-failed? d) → boolean?
d : dag?

#t when the most recent head is a failure node.

procedure
(dag-halted? d) → boolean?
d : dag?

#t when the most recent head is a halt node — a deliberate, non-error ending. Unlike a failure, a halt is not an error, so no failure-log handler fires.

procedure
(dag-terminal? d) → boolean?
d : dag?

#t when the most recent head ends the composition — either a failure (dag-failed?) or a halt (dag-halted?). Both short-circuit a ~> sequence; only dag-failed? signals an error.

procedure
(make-halt-node parents kind reason [meta]) → node?
  parents : (listof string?)
  kind : symbol?
  reason : string?
  meta : hash? = (hash)

Create a halt node signaling a deliberate stop. kind is one of 'agent-decided, 'declined, 'user-quit, or 'input-ended; the latter two are session-terminal (they end a run-ashlar #:loop session). make-ask-human produces a 'declined or 'user-quit halt on cancellation.

procedure
(halt-node? n) → boolean?
n : any/c

#t when n is a halt node.

procedure
(halt-node-kind n) → symbol?
n : node?

The halt node’s kind. ashlar-match can catch a halt by matching on this kind.

procedure
(halt-node-reason n) → string?
n : node?

The halt node’s human-readable reason.

procedure
(dag-nearest-ancestor d type) → (or/c node? #f)
d : dag?
type : symbol?

Walks first-parent pointers from the DAG’s most recently appended head until it finds a node whose node-type is type. Returns the node, or #f if none is reachable on the first-parent line. When the DAG has no heads, returns #f.

procedure
(dag-collect-until d
#:type collect-type
#:until sentinel-type) → (listof node?)
  d : dag?
  collect-type : symbol?
  sentinel-type : symbol?

Walks first-parent pointers from the most recently appended head, collecting nodes whose node-type is collect-type, stopping at the first ancestor whose node-type is sentinel-type. The sentinel node itself is the boundary and is excluded from the result.

Returns nodes oldest-first (the one closest to the sentinel comes first). Returns '() when no sentinel-type ancestor is reachable on the first-parent line — there is no enclosing scope, so there is nothing to collect within.

Same first-parent discipline as dag-nearest-ancestor: deterministic under loops and fan-outs, and siblings on other lanes are not visited.

procedure
(dag-query-all d type [#:scope scope]) → (listof node?)
  d : dag?
  type : symbol?
  scope : (or/c 'conversation #f) = #f

Returns every node of the given type, sorted oldest-first by timestamp. Single in-scope scan over (dag-nodes d). The #:scope argument is retained as a no-op for source compatibility; passing 'conversation yields the same result as omitting it.

procedure
(dag-select d nid) → (listof node?)
d : dag?
nid : string?

Walks first-parent pointers from nid back to the root. Returns the nodes oldest-first. Used internally to rebuild a linear conversation from a branching DAG.

procedure
(dag-select-window d nid n) → (listof node?)
  d : dag?
  nid : string?
  n : exact-nonnegative-integer?

Returns the last n nodes of (dag-select d nid). If the linear history is shorter than n, returns the whole history.

procedure
(dag-merge dags) → dag?
dags : (listof dag?)

Unions the node tables, concatenates and de-duplicates the heads, and uses the root of the first input.

procedure
(failure-log-handler)
→ (parameter/c (or/c (symbol? string? hash? . -> . any) #f))

Default #f. When set, make-failure-node calls (handler kind reason meta) before returning the node. stone/logging installs a handler at module load that emits an 'error-level 'stone-event.

5.3 stone/messages🔗ℹ

(require stone/messages)

package: Stone

A single turn in an LLM conversation. Self-contained: no link to a ashlar DAG. Used as the element type of the 'conversation list that make-agent-ashlar embeds in its result node.

struct
(struct message (role content tool-calls call-id metadata))
  role : symbol?
  content : (or/c string? hash? (listof hash?))
  tool-calls : list?
  call-id : (or/c string? #f)
  metadata : hash?

A turn in a conversation.

role — 'system, 'user, 'assistant, or 'tool.
content — free text, a parsed structured-output hash, or a list of multimodal content blocks.
tool-calls — list of tool-call records; assistant role only, '() otherwise.
call-id — tool-result correlation id; tool role only, #f otherwise.
metadata — provider-specific escape hatch. Convention: namespaced symbol keys (e.g. 'anthropic/cache-control, 'openai/logprobs, 'vllm/finish-reason) to prevent collision when multiple providers stash bits there.

procedure
(message-text m) → string?
m : (or/c message? #f)

Extract a plain-string view of m’s content, tolerating every shape content can take. When m is #f, returns "". Plays the same role for messages that node-text plays for typed nodes: when new content shapes are added, this helper grows so consumer code does not have to.

5.4 stone/llm-ashlar🔗ℹ

(require stone/llm-ashlar)

package: Stone

Bridge constructor that wraps an LLM caller into a multi-turn agent ashlar. See Agents and Tools for the conceptual model.

procedure
(make-agent-ashlar caller
#:produces produces
[ #:context ctx
#:name name
#:schema schema
#:middleware middleware
#:decide decide
#:max-turns max-turns
#:response-format response-format
#:model model
#:budget budget
#:context-budget context-budget
#:adversary adversary
#:heal-with healer
#:max-healing max-healing
#:finalize finalize])
→ ashlar-meta?
  caller : procedure?
  produces : symbol?
  ctx : context? = (context)
  name : (or/c symbol? #f) = #f
  schema : (or/c hash? #f) = #f
  middleware : (listof any/c) = '()
  decide : procedure? = continue-on-tool-use
  max-turns : exact-positive-integer? = 15
  response-format : (or/c hash? #f) = #f
  model : (or/c string? #f) = #f
  budget : exact-nonnegative-integer? = 16384
  context-budget : exact-nonnegative-integer? = 400000
  adversary : (or/c ashlar-meta? #f) = #f
  healer : (or/c ashlar-meta? #f) = #f
  max-healing : exact-nonnegative-integer? = 3
  finalize : (or/c (any/c . -> . node?) #f) = #f

Runs a multi-turn agent with its own internal loop and conversation list. The agent threads a (listof message) through each turn, preserving full structured content (including tool call blocks) across turns. Produces one typed node at the end; the agent’s conversation is embedded in the result node’s content under the key 'conversation.

caller — LLM caller built by make-openai-caller or make-anthropic-caller.
#:produces — node type of the final result.
#:context — a context data structure (from stone/context-struct) describing how the outgoing messages are projected from the DAG: (context (system ...) (history 'type) (user 'type) #:compaction ashlar). It subsumes the former #:system / #:user / #:queries keywords; the ashlar’s read-set is derived from the context’s lenses, never declared alongside it. Default is an empty context.
#:name — defaults to produces, else a fresh agent-ashlar-* id.
#:schema — JSON schema attached to metadata. Usually auto-populated from #:response-format.
#:middleware — middleware onion wrapping each turn.
#:decide — loop decision function (context? (listof recommendation?) -> recommendation?). Must be a procedure. Default is continue-on-tool-use. For single-turn behavior, pass #:max-turns 1 with empty middleware.
#:max-turns — hard cap on turns inside the agent loop.
#:response-format — when truthy, the final draft must be a hash (parsed from JSON). Failing to parse produces a 'llm-parse-failed failure.
#:model — model identifier; overrides default-model for this ashlar.
#:budget — max response tokens per turn (the response max-tokens handed to the caller).
#:context-budget — a provider-agnostic size hint the projected context is measured against. When the projection overflows and no #:compaction ashlar re-projects it small enough, the agent fails loud (a failure node becomes the head; the caller is never reached). Default is large.
#:adversary — quality-gate ashlar. Runs against the ashlar DAG when decide says 'continue. Failure node = rejection; non-failure = pass.
#:heal-with — healer ashlar. When adversary rejects, healer runs and its output enters the agent’s conversation.
#:max-healing — bounds heal cycles (reject → heal → retry), not adversary invocations. The adversary always votes at least once; the budget gates retries only. #:max-healing 0 is the gate idiom: adversary votes once; pass → done, reject → fail without retry. #:max-healing N allows up to N heal cycles, so the adversary may vote up to N+1 times. On the (+ N 1)th reject, returns a 'healing-exhausted failure node.
The threshold — the single designed opening through which the agent emits observation crossings (turns, and — via the streaming caller — tokens) and poses decisions (tool-call gates) — is not a construction argument. The agent reads (current-threshold) when it emits, a per-run resource bound by the runner (run-tui, or run-ashlar with #:record from the record’s threshold) — symmetric with current-journal. An ephemeral bare run that wants observation does (parameterize ([current-threshold th]) (run-ashlar ...)).
#:finalize — optional hook that receives the parsed final content and returns either a typed node or a failure node. The framework injects 'conversation into typed-node returns; failure-node returns pass through unchanged. Raises if the returned content already contains 'conversation. When absent, the framework builds a typed-node of type produces with the parsed content and the conversation merged in.

5.5 stone/context-struct🔗ℹ

(require stone/context-struct)

package: Stone

The context data structure an agent ashlar’s #:context is built from (see make-agent-ashlar). A context is plain, inspectable data with two readings of the same value: statically, the validator walks it to derive the ashlar’s read-set (context-read-set); at run time, the agent loop interprets it to project the outgoing messages from the DAG. It subsumes the former #:system / #:user / #:queries keywords.

Naming. stone re-exports a different, unrelated context — the per-turn middleware struct (stone). When you require both, exclude that one: (require (except-in stone context context? on-latest) stone/context-struct).

procedure
(context [ #:compaction compaction]
element ...) → context?
compaction : (or/c ashlar-meta? #f) = #f
element : context-element?

Builds a context from an ordered list of elements (each a system, user, or history). At most one 'user element is allowed, and it must be last (so the projected message tail is role 'user — the conversation-tail invariant); violations raise. #:compaction names an optional DAG→DAG ashlar run when the projected context overflows the #:context-budget hint; it appends a summary node of the history element’s type. Build its parent list with compaction-summary-parents.

procedure
(context? v) → boolean?
v : any/c

Recognizes a context.

procedure
(system arg) → context-element?
arg : (or/c string? ctx-lens?)

A 'system element. (system str) sets a literal system prompt (folded into the topology hash). (system lens) computes it via a lens.

procedure
(user arg) → context-element?
arg : (or/c symbol? ctx-lens?)

A 'user element — the latest user turn. (user 'type) is sugar for "the latest node of 'type, text-extracted"; (user lens) computes it via a lens.

procedure
(history arg) → context-element?
arg : (or/c symbol? ctx-lens?)

A 'history element — the ashlar’s prior turns of 'type, expanded into role-tagged conversation. (history 'type) reads 'type nodes; (history lens) computes the node list via a lens.

procedure
(raw-lens projector #:queries reads) → ctx-lens?
projector : (dag? . -> . any/c)
reads : (listof symbol?)

A lens with an explicit read-set. projector computes the element’s value from the DAG; #:queries is the read-set the validator checks (omitting it is a construction error — an opaque lens can’t be validated). Use it when an element must combine or transform several node types.

procedure
(on-latest type extract) → ctx-lens?
type : symbol?
extract : (node? . -> . any/c)

A lens projecting extract applied to the latest node of 'type (via dag-nearest-ancestor). Reads 'type. A bare (user 'type) / (history 'type) desugars to (on-latest type node-text).

struct
(struct context-element (role lens)
    #:transparent)
  role : (or/c 'system 'user 'history)
  lens : ctx-lens?

One element of a context: a role plus a lens.

struct
(struct ctx-lens (projector reads literal)
    #:transparent)
  projector : procedure?
  reads : (listof symbol?)
  literal : any/c

A projection over the DAG. reads is its read-set; literal carries a folded-in constant for a literal lens.

procedure
(context-elements ctx) → (listof context-element?)
ctx : context?

The context’s ordered element list.

procedure
(context-compaction ctx) → (or/c ashlar-meta? #f)
ctx : context?

The context’s compaction ashlar, or #f.

procedure
(context-read-set ctx) → (listof symbol?)
ctx : context?

The deduped union of every element’s lens read-set — the ashlar’s derived #:queries.

procedure
(compaction-summary-parents dag
condensed-turn-ids)
→ (listof string?)
dag : dag?
condensed-turn-ids : (listof string?)

The parent list a #:compaction summary node must use: the current lineage head(s) first, then the condensed turns, deduped — so a first-parent walk still reaches the latest turn after the summary becomes the newest head.

5.6 stone/threshold🔗ℹ

(require stone/threshold)

package: Stone

The threshold is the single designed opening between a running ashlar and everything outside it — one per run. It has two faces: the inside (engine) emits observations and poses decisions; the outside (supervisor) reads the crossing feed and resolves decisions. Every crossing is provenance-tagged by its span, so one threshold serves a whole nested run. See Ask Human for the conceptual model and Run a durable, resumable session for how a run binds one.

procedure
(make-threshold [#:unattended unattended]) → threshold?
unattended : hash? = (hasheq 'gate 'deny 'ask 'cancel)

Builds a fresh threshold. #:unattended is the policy consulted when no supervisor is attached: how a 'gate (default 'deny) or 'ask (default 'cancel — a 'user-quit) resolves without blocking.

procedure
(threshold? v) → boolean?
v : any/c

Recognizes a threshold.

parameter
(current-threshold) → (or/c threshold? #f)
(current-threshold th) → void?
th : (or/c threshold? #f)

The threshold in effect for the current run, bound by a driver (run-ashlar #:record, run-tui). Engine-side constructs such as make-ask-human solicit through it. #f means no run is in flight.

struct
(struct crossing (span kind payload)
    #:transparent)
  span : pair?
  kind : symbol?
  payload : any/c

One thing passing through the threshold. span is a (cons ashlar-name span-id) provenance tag; kind is a symbol ('token, 'turn, 'steer, 'ask, 'gate, …); payload is plain data. A decision crossing ('ask / 'gate) carries an 'id in its payload — the routing id a supervisor resolves by.

5.6.1 Outside: the supervisor🔗ℹ

procedure
(threshold-subscribe th) → evt?
th : threshold?

Returns a fresh subscription — a synchronizable source that yields every subsequent crossing. (sync sub) blocks until one arrives.

procedure
(threshold-attach! th) → void?
th : threshold?

Mark the threshold attended: a supervisor is present, so decisions block for it instead of auto-resolving from the unattended policy.

procedure
(threshold-detach! th) → void?
th : threshold?

Detach the supervisor and resolve every still-pending decision from the unattended policy, so nothing hangs on shutdown.

procedure
(threshold-attended? th) → boolean?
th : threshold?

Whether a supervisor is currently attached.

procedure
(threshold-answer! th id text) → void?
  th : threshold?
  id : any/c
  text : string?

Resolve a pending 'ask (by its routing id) with an answer. Single-shot; an unknown or already-resolved id is a no-op.

procedure
(threshold-cancel! th id [kind]) → void?
  th : threshold?
  id : any/c
  kind : symbol? = 'declined

Decline a pending 'ask, resolving it with a cancellation of kind — 'declined (this supervisor refused this question) or 'user-quit (end the session). make-ask-human turns the cancellation into a halt node of that kind.

procedure
(threshold-verdict! th id verdict) → void?
  th : threshold?
  id : any/c
  verdict : (or/c 'allow 'deny)

Resolve a pending 'gate (a tool-call approval) with 'allow or 'deny.

procedure
(threshold-steer! th text) → void?
th : threshold?
text : string?

Inject a user turn into a live run — the supervisor speaking into the conversation between the agent’s turns.

procedure
(threshold-request-cancel! th) → void?
th : threshold?

Ask the in-flight turn to abort cooperatively (Ctrl-C in the TUI). The streaming loop polls the flag between chunks and drops the partial turn; completed turns stay journaled, so the run stays resumable.

5.6.2 Inside: the engine🔗ℹ

These are called by the framework, not usually by user code.

procedure
(threshold-ask th question [span]) → (or/c string? cancelled?)
  th : threshold?
  question : string?
  span : pair? = DECISION-SPAN

Pose a free-text question and block until a supervisor resolves it, returning the answer string or a cancelled. Posed while unattended, resolves immediately to (cancelled 'user-quit).

procedure
(threshold-gate th tool args call-id [span]) → (or/c 'allow 'deny)
  th : threshold?
  tool : any/c
  args : any/c
  call-id : any/c
  span : pair? = DECISION-SPAN

Pose a tool-approval gate and block until a verdict. Posed while unattended, resolves immediately from policy (default 'deny).

procedure
(threshold-emit! th c) → void?
th : threshold?
c : crossing?

Push an observation crossing (non-blocking) to every subscriber.

procedure
(threshold-drain! th) → (listof string?)
th : threshold?

Take and clear the queued steer texts (the engine’s steering pickup).

struct
(struct cancelled (kind)
#:transparent)
kind : symbol?

The resolution of an unanswered decision, carrying why: 'declined or 'user-quit. A later phase maps it to a halt node of that kind.

struct
(struct run-cancelled ()
#:transparent)

The cooperative-cancel signal raised inside the streaming loop when a supervisor requested a cancel. Deliberately not an exn:fail, so it slips past generic handlers to unwind the in-flight turn; the run boundary catches it and returns cleanly.

5.7 stone/record🔗ℹ

(require stone/record)

package: Stone

A record binds the three things a durable run needs: the DAG it runs against, the append-only journal it writes progress to, and the threshold a supervisor observes and answers through. See Run a durable, resumable session for the workflow.

struct
(struct record (dag journal threshold path)
    #:transparent)
  dag : dag?
  journal : journal?
  threshold : (or/c threshold? #f)
  path : (or/c path? string?)

The durable-run binding. path is where the journal lives — the identity of the run on disk.

procedure
(open-record path [#:threshold th]) → record?
path : (or/c path? string?)
th : (or/c threshold? #f) = #f

Open (or reopen) the record at path — the single entry point for both a fresh run and a resume:

Fresh (no file at path) — an empty DAG plus a new journal opened for append.
Resume (the file exists) — the DAG is rebuilt by replaying the journal, and the same file is reopened for append so new facts extend the log.

#:threshold defaults to #f; a driver/TUI passes a real one, and a batch test may pass one to observe or answer decisions. Hand the result to run-ashlar #:record.

5.7.1 stone/journal🔗ℹ

(require stone/journal)

package: Stone

The record’s on-disk form: an append-only JSONL log of the facts a run produces. The DAG is the single source of truth; the journal is its crash-recovery projection, and replaying it is exactly what a resume does. Most users never touch this module directly — they use open-record and run-ashlar #:record. The facts (node-appended, session-started, ashlar-completed, turn-completed, decision-posed, decision-received, …) are transparent structs so equality — the round-trip contract — is structural.

procedure
(open-journal path) → journal?
path : (or/c path? string?)

Open (creating if absent) the journal file at path for append.

procedure
(journal-read path) → (listof any/c)
path : (or/c path? string?)

Read every recorded fact from the journal at path, in order.

procedure
(journal-append! j fact) → void?
j : journal?
fact : any/c

Append one fact to the journal.

procedure
(close-journal j) → void?
j : journal?

Close the journal’s file handle.

procedure
(journal? v) → boolean?
v : any/c

Recognizes a journal.

parameter
(current-journal) → (or/c journal? #f)
(current-journal j) → void?
j : (or/c journal? #f)

The journal in effect for the current run, bound by run-ashlar #:record. #f means an ephemeral run — no journaling, byte-identical to a bare run.

5.7.2 stone/tui-main🔗ℹ

(require stone/tui-main)

package: Stone

procedure
(run-tui ashlar
#:record path
[ #:threshold th
#:initial-state initial-state]) → any
  ashlar : ashlar-meta?
  path : (or/c path? string?)
  th : threshold? = (make-threshold)
  initial-state : any/c = #f

Run ashlar as a durable interactive session supervised by the terminal UI. Attaches th, opens the record at path, subscribes once, seeds scrollback from the journal, and runs (run-ashlar ashlar #:record r #:loop #t) on a background thread — looping until a session-terminal halt (the user quits). When the caller built the agent with a threshold (so the agent emits to it), it MUST pass that same threshold here. See Use the TUI.

5.8 stone/llm-types🔗ℹ

(require stone/llm-types)

package: Stone

Shared response and exception types used by the LLM caller layer. Tool authors and custom callers require this module; user ashlar code generally does not.

5.8.1 Responses🔗ℹ

struct
(struct llm-response (text tool-calls usage))
  text : string?
  tool-calls : (listof tool-call?)
  usage : hash?

Stone’s internal representation of an LLM response. text is the assistant’s text output; tool-calls is the list of tool invocations requested by the model; usage carries provider-specific token-usage stats and is opaque to Stone.

struct
(struct tool-call (id name input))
  id : string?
  name : string?
  input : hash?

A tool invocation requested by the LLM. id is an opaque identifier that round-trips through the tool result; name selects which tool to invoke; input is the hash of arguments.

5.8.2 Exceptions🔗ℹ

struct
(struct exn:fail:repetition-tripped exn:fail (hit partial)
    #:extra-constructor-name make-exn:fail:repetition-tripped)
  hit : repetition-hit?
  partial : string?

Raised by call-llm-openai when a streaming session’s watcher trips. hit is the repetition-hit from the detector; partial is the channel text streamed before the trip (response-text if the response watcher tripped; thinking-text otherwise). make-openai-caller’s retry layer catches this internally; user code only sees this exception if the retry layer itself is bypassed.

struct
(struct exn:fail:repetition-exhausted exn:fail (attempts last-hit)
    #:extra-constructor-name make-exn:fail:repetition-exhausted)
  attempts : exact-nonnegative-integer?
  last-hit : (or/c repetition-hit? #f)

Raised by make-openai-caller when the retry budget is exhausted. attempts is the configured #:max-retries value — the retry budget that was exhausted, not the actual call count. last-hit is the most recent repetition-hit, or #f if none was captured. Caught by the agent layer and converted to a 'failure-typed node with content kind 'output-degenerate.

struct
(struct exn:fail:llm-http-error exn:fail (status body)
    #:extra-constructor-name make-exn:fail:llm-http-error)
  status : exact-nonnegative-integer?
  body : string?

Raised by the streaming LLM caller when the server returns a non-2xx HTTP response. Without this, an HTTP 400 (e.g. malformed conversation) would come back as an empty SSE stream and the agent loop would silently treat it as a successful empty response, burning turns until #:max-turns exhausts. status is the HTTP status code; body is the response body (typically a JSON error).

struct
(struct exn:fail:llm-empty-response exn:fail ()
#:extra-constructor-name make-exn:fail:llm-empty-response)

Raised by the agent layer when the model produces no text AND no tool calls. The agent loop has nothing to act on; without this guard, the loop would silently advance through empty turns until #:max-turns exhausts. The agent’s outer with-handlers converts this to an 'agent-empty-response failure node.

5.9 stone/llm-client🔗ℹ

(require stone/llm-client)

package: Stone

LLM caller factories compatible with the make-agent-ashlar caller contract. See Provider constraints for per-provider knobs.

procedure
(make-openai-caller #:url url
[ #:api-key api-key
#:extra-body extra-body
#:repetition-watch repetition-watch
#:max-retries max-retries])
→ procedure?
  url : string?
  api-key : string? = ""
  extra-body : hash? = (hasheq)
  repetition-watch : (or/c (-> repetition-watcher?) #f) = #f
  max-retries : exact-nonnegative-integer? = 3

Returns a procedure with signature (messages system model max-tokens tools response-format [threshold]) -> hash?. POSTs an OpenAI-compatible chat-completion request and normalizes the response to Anthropic content-block shape. Always streams via SSE. When threshold is provided (not #f), per-token 'token crossings are also emitted through it (see stone/threshold).

#:url may be the base URL or the full /v1/chat/completions URL; /v1/chat/completions is appended when missing. #:api-key empty means no Authorization header. #:extra-body is closed over at construction time and shallow-merged into every request body; the reserved keys '(model messages max_tokens tools response_format stream) raise at call time if you try to override them.

#:repetition-watch is a zero-arg factory that returns a fresh repetition-watcher; when supplied, every call constructs independent watchers for the response and thinking channels and feeds them mid-stream. If a watcher trips, the SSE stream aborts; the caller appends an assistant turn carrying the partial output and a user turn explaining the model got stuck, then retries up to #:max-retries times. After exhaustion, raises exn:fail:repetition-exhausted. When #f (default), the retry/watch path is bypassed entirely.

procedure
(make-anthropic-caller #:api-key api-key
[ #:url url
#:extra-body extra-body
#:repetition-watch repetition-watch
#:max-retries max-retries])
→ procedure?
  api-key : string?
  url : string? = "https://api.anthropic.com/v1/messages"
  extra-body : hash? = (hasheq)
  repetition-watch : (or/c (-> repetition-watcher?) #f) = #f
  max-retries : exact-nonnegative-integer? = 3

Returns a procedure with the same signature as make-openai-caller’s. POSTs an Anthropic messages request with anthropic-version: 2023-06-01. The threshold argument is accepted but ignored — Anthropic doesn’t stream yet, so it emits no token crossings. Reserved keys '(model system messages max_tokens tools response_format) raise at call time if overridden through #:extra-body.

#:repetition-watch and #:max-retries are accepted for API symmetry with make-openai-caller but currently have no effect — they will be honored when Anthropic streaming lands.

procedure
(call-llm #:url url
#:model model
[ #:system system]
#:messages messages
[ #:max-tokens max-tokens
#:api-key api-key
#:tools tools
#:response-format response-format
#:extra-body extra-body]) → hash?
  url : string?
  model : string?
  system : string? = ""
  messages : list?
  max-tokens : exact-nonnegative-integer? = 4096
  api-key : string? = "mock-key"
  tools : list? = '()
  response-format : (or/c hash? #f) = #f
  extra-body : hash? = (hasheq)

Low-level POST against an Anthropic-compatible messages endpoint. Returns the parsed JSON response. make-anthropic-caller wraps this.

procedure
(call-llm-openai #:url url
#:model model
[ #:system system]
#:messages messages
[ #:max-tokens max-tokens
#:api-key api-key
#:tools tools
#:response-format response-format
#:extra-body extra-body
#:threshold threshold
#:response-watcher response-watcher
#:thinking-watcher thinking-watcher]) → hash?
  url : string?
  model : string?
  system : string? = ""
  messages : list?
  max-tokens : exact-nonnegative-integer? = 4096
  api-key : string? = ""
  tools : list? = '()
  response-format : (or/c hash? #f) = #f
  extra-body : hash? = (hasheq)
  threshold : (or/c threshold? #f) = #f
  response-watcher : (or/c repetition-watcher? #f) = #f
  thinking-watcher : (or/c repetition-watcher? #f) = #f

Low-level POST against an OpenAI-compatible chat-completions endpoint. Converts Anthropic tool schemas to OpenAI function schemas, POSTs the request, and normalizes the response to Anthropic content-block shape. Always streams via SSE, parsing <think>...</think> markers into 'thinking token crossings when a #:threshold is supplied. make-openai-caller wraps this.

#:response-watcher / #:thinking-watcher are optional repetition-watchers; if either trips during the SSE stream, the call raises exn:fail:repetition-tripped and closes the response. make-openai-caller’s retry layer constructs and supplies fresh watchers per attempt; supply them here directly only if you’re bypassing that layer.

procedure
(extract-text response) → string?
response : hash?

Returns the text of the first content block whose type is "text" in a normalized response, or "" if there is none.

5.9.1 Exceptions raised by the OpenAI caller🔗ℹ

This module raises exn:fail:repetition-tripped and exn:fail:repetition-exhausted from stone/llm-types under the conditions documented at stone/llm-types. The retry layer in make-openai-caller catches exn:fail:repetition-tripped internally; user code only observes it if that retry layer is bypassed.

5.10 stone/repetition-watch🔗ℹ

(require stone/repetition-watch)

package: Stone

Streaming-time detectors for degenerate LLM output: exact n-gram loops (verbatim repetition) and rambling without progress (near-repetition). Wired into call-llm-openai via the #:response-watcher / #:thinking-watcher keywords; consumed by the caller-level retry loop in make-openai-caller via the #:repetition-watch keyword.

5.10.1 Hits🔗ℹ

struct
(struct repetition-hit (kind detail position)
    #:extra-constructor-name make-repetition-hit)
  kind : symbol?
  detail : any/c
  position : exact-nonnegative-integer?

Reports what tripped the watcher. kind is 'ngram (verbatim n-gram repeat) or 'compression (sliding-window deflate ratio dropped below threshold for a streak of ticks). detail is the offending bytes? window for 'ngram hits, or a (listof real?) ratio history (head = newest) for 'compression hits. position is the total bytes seen at trip time.

5.10.2 Karp–Rabin n-gram counter🔗ℹ

Detects exact verbatim repetition. Maintains a rolling polynomial hash over the latest n bytes; trips when any window’s hash is observed threshold times (with sample-byte verification to filter hash collisions). Sticky after trip — once tripped, ngram-counter-add! is an O(1) no-op.

procedure
(make-ngram-counter [ #:n n
#:threshold threshold]) → ngram-counter?
n : exact-positive-integer? = 100
threshold : exact-positive-integer? = 4

Constructs a counter with the given window size and trip threshold. Defaults are tuned to ignore structural repetition in enumerated JSON output (e.g. descriptions in a list of behaviors) while still catching verbatim loops; the compression detector covers near-repetition that escapes this stricter bar.

procedure
(ngram-counter-add! c byte) → void?
c : ngram-counter?
byte : byte?

Feeds one byte to the counter.

procedure
(ngram-counter-tripped c) → (or/c #f repetition-hit?)
c : ngram-counter?

Returns the repetition-hit if tripped, otherwise #f.

5.10.3 Compression-ratio detector🔗ℹ

Detects rambling / near-repetition where the model produces grammatical-but-going-nowhere output. Maintains a circular byte buffer of size #:window; per tick, deflates the buffer (via file/gzip) and pushes compressed-size / window-size onto a fixed-length ratio history. Trips when the latest #:history-len ratios are all ≤ #:threshold. Sticky.

procedure
(make-compression-detector [ #:window window
#:threshold threshold
#:history-len history-len])
→ compression-detector?
  window : exact-positive-integer? = 1024
  threshold : real? = 0.18
  history-len : exact-positive-integer? = 3

Constructs a detector with the given window size, ratio threshold, and history length.

procedure
(compression-detector-add! d byte) → void?
d : compression-detector?
byte : byte?

Feeds one byte to the detector. Cheap; never runs deflate.

procedure
(compression-detector-check d) → void?
d : compression-detector?

Runs deflate on the current window, computes the ratio, and updates history. Call this on each streaming-progress tick (every current-streaming-emit-interval ms by default — i.e., once every 5 seconds in production).

Calls that complete in less than the emit interval will never engage the compression detector — by design, since short outputs are not a rambling failure mode. The n-gram detector remains active per-byte regardless.

procedure
(compression-detector-tripped d) → (or/c #f repetition-hit?)
d : compression-detector?

Returns the repetition-hit if tripped, otherwise #f.

5.10.4 Combined watcher🔗ℹ

Multiplexes both detectors behind a single API. This is what the streaming session and caller layer plug in.

procedure
(make-repetition-watcher [ #:ngram-counter ngram-counter
#:compression compression
#:on-trip on-trip])
→ repetition-watcher?
   ngram-counter : (or/c ngram-counter? #f)
= (make-ngram-counter)
   compression : (or/c compression-detector? #f)
= (make-compression-detector)
  on-trip : (-> repetition-hit? any/c) = (λ (_) (void))

Constructs a watcher. Pass #f for either detector to disable that channel. The on-trip callback is invoked at most once, on the first trip from either detector.

procedure
(repetition-watcher-add-bytes! w bs) → void?
w : repetition-watcher?
bs : bytes?

Feeds bytes to whichever detectors are non-#f. After feeding, runs the trip check; if newly tripped, fires on-trip.

procedure
(repetition-watcher-tick! w) → void?
w : repetition-watcher?

Runs compression-detector-check (no-op if compression is disabled). Called by maybe-emit-progress! inside the streaming session at the every-5s tempo.

procedure
(repetition-watcher-tripped w) → (or/c #f repetition-hit?)
w : repetition-watcher?

Returns the captured repetition-hit if either detector has tripped, otherwise #f.

5.11 stone/tools🔗ℹ

(require stone/tools)

package: Stone

Middleware constructors for LLM tool calls. See Agents and Tools for the conceptual model. Human interaction is make-ask-human (see stone/edge and Ask Human), which solicits through the run’s threshold rather than through tool middleware.

5.11.1 Tool middleware🔗ℹ

procedure
(make-tool name
#:schema schema
#:handler handler
[ #:allowed-paths allowed-paths
#:confirm? confirm?]) → any/c
  name : symbol?
  schema : hash?
  handler : (hash? . -> . any)
  allowed-paths : (or/c (listof string?) #f) = #f
  confirm? : boolean? = #f

Returns a middleware that injects schema into the context’s tools list and dispatches matching tool_use blocks to handler. handler must return (values string? hash?) — the display text shown to the next turn and a structured meta hash. #:allowed-paths rejects calls whose path argument isn’t under one of these prefixes. #:confirm? #t causes the tool to refuse to run and recommend a 'loop with category 'approval-needed.

procedure
(has-tool-call-for? ctx tool-name) → boolean?
ctx : any/c
tool-name : symbol?

#t when the last response’s content contains a tool_use block whose name equals (symbol->string tool-name).

procedure
(extract-tool-calls response) → (listof hash?)
response : hash?

Every content block in response whose type is "tool_use".

procedure
(tool-schema mw) → (or/c hash? #f)
mw : any/c

Returns the JSON-schema hash that was passed to make-tool when mw was built, or #f if mw was not registered. Backed by a process-wide weak table keyed on middleware identity.

5.11.2 Built-in tool middleware🔗ℹ

procedure
(read-file [#:allowed-paths allowed-paths]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f

Creates a read_file tool middleware. Returns file contents; supports optional offset and limit tool arguments for a line-range slice.

procedure
(write-file [ #:allowed-paths allowed-paths
#:confirm? confirm?]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f
confirm? : boolean? = #f

Creates a write_file tool middleware. Creates parent directories as needed and overwrites the target file.

procedure
(edit-file [ #:allowed-paths allowed-paths
#:confirm? confirm?]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f
confirm? : boolean? = #f

Creates an edit_file tool middleware. Refuses the call if old_string isn’t found or isn’t unique in the target file.

procedure
(delete-file* [ #:allowed-paths allowed-paths
#:confirm? confirm?]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f
confirm? : boolean? = #t

Creates a delete_file tool middleware. Note that #:confirm? defaults to #t.

procedure
(list-directory [#:allowed-paths allowed-paths]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f

Creates a list_directory tool middleware.

procedure
(mkdir* [#:allowed-paths allowed-paths]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f

Creates an mkdir tool middleware that creates a directory and any missing parents.

procedure
(file-exists* [#:allowed-paths allowed-paths]) → any/c
allowed-paths : (or/c (listof string?) #f) = #f

Creates a file_exists tool middleware returning "true" or "false".

procedure
(run-command [ #:timeout default-timeout
#:confirm? confirm?]) → any/c
default-timeout : real? = 60000
confirm? : boolean? = #f

Creates a run_command tool middleware. Runs a shell command synchronously under /bin/sh -c, waits up to timeout milliseconds, and returns the concatenated exit code, stdout, and stderr. Timed-out commands are killed.

procedure
(start-command [#:timeout default-timeout]) → any/c
default-timeout : real? = 300000

Creates a start_command tool middleware. Spawns the command in the background and returns a handle id.

procedure
(check-command) → any/c

Creates a check_command tool middleware. Given a handle id, returns "running" or the final exit/stdout/stderr.

procedure
(wait-commands) → any/c

Creates a wait_commands tool middleware. Given a list of handle ids, waits (up to each handle’s stored timeout) for them all to finish and returns a combined report.

5.12 stone/decisions🔗ℹ

(require stone/decisions)

package: Stone

Ready-made decide functions for the #:decide kwarg of make-agent-ashlar. A decide function has the signature (context? (listof recommendation?) -> recommendation?) and is called after every turn to pick 'continue, 'loop, or 'halt.

procedure
(continue-on-tool-use ctx recs) → any/c
ctx : any/c
recs : (listof any/c)

Default #:decide value on make-agent-ashlar. Halts if any middleware emitted a 'halt recommendation; loops while the recommendation list is non-empty; continues otherwise. Reach for this when the agent’s job is "think, call tools as needed, then reply" and any outstanding tool activity is the signal to keep going.

procedure
(tool-directed ctx recs) → any/c
ctx : any/c
recs : (listof any/c)

Stricter variant: loops only when a middleware explicitly recommends 'loop. An empty recommendation list means the agent is done — it’s the tool middlewares’ responsibility to ask for another turn. Use this when you want the tool layer to drive the conversation deliberately, e.g. a workflow where "no tool fired" means "time to finalize the answer."

5.13 stone/validate🔗ℹ

(require stone/validate)

package: Stone

Static checks over a composed ashlar. See Validation for the conceptual model.

procedure
(validate-ashlar ashlar) → validation-result?
ashlar : ashlar-meta?

Walks the ashlar tree, dispatching on each ashlar’s validate-walk rule. Collects a 'missing-producer error when an ashlar queries a node type no upstream sibling produces, a 'maybe-unavailable warning when a type is produced by some match branches but not all, an 'invalid-lens error when a ashlar-match has a lens whose path isn’t in the upstream schema, and a 'fanout-not-reduced error when a fan-out isn’t immediately followed by a ashlar-reduce.

struct
(struct validation-result (errors)
#:transparent)
errors : (listof validation-error?)

Container for the errors and warnings collected by validate-ashlar. Prefer validation-ok? and validation-errors for inspection.

struct
(struct validation-error (type ashlar-name queried-type message)
    #:transparent)
  type : symbol?
  ashlar-name : (or/c symbol? #f)
  queried-type : symbol?
  message : string?

type is one of 'missing-producer, 'maybe-unavailable, 'invalid-lens, or 'fanout-not-reduced. ashlar-name identifies the offending ashlar. queried-type is the node type or lens path segment at fault. message is a human-readable description.

procedure
(validation-ok? r) → boolean?
r : validation-result?

#t when r has no hard errors. 'maybe-unavailable warnings don’t make the result not-ok.

procedure
(validation-errors r) → (listof validation-error?)
r : validation-result?

Returns the error list inside r.

procedure
(enumerate-ashlars ashlar) → (listof symbol?)
ashlar : ashlar-meta?

Every named ashlar in the tree, depth-first pre-order. Unnamed ashlars are skipped. See Validate a topology for the orphan-ashlar guard pattern built on this.

procedure
(enumerate-paths ashlar) → (listof (listof symbol?))
ashlar : ashlar-meta?

Every distinct execution path through the ashlar as a list of ashlar names. A match with n branches contributes n paths; a sequence concatenates its children’s paths; loops and reduce pass through their child’s paths.

5.14 stone/test🔗ℹ

(require stone/test)

package: Stone

Test harness for Stone ashlars. See The test harness for the conceptual model and Test ashlars that use tools for the how-to.

A tool-call record is an immutable hasheq with keys 'name (symbol), 'input (hash), 'result-text (string), and 'result-meta (hash). tool-calls and friends return lists of these records in call order.

5.14.1 Harnesses🔗ℹ

syntax
(with-live-harness #:caller caller
                   maybe-strict
                   maybe-timeout
                   body ...)

maybe-strict =
| #:strict-tools? strict?

maybe-timeout =
| #:timeout seconds

Starts a recorder on stone-logger, parameterizes harness-current-caller, and evaluates body. When #:strict-tools? #t, every recorded tool call must have been installed via ashlar-with-tool-stub; otherwise the harness raises on exit. #:timeout runs body on a background thread; exceeding seconds breaks the thread and raises.

syntax
(with-mock-harness #:caller caller
                   maybe-strict
                   body ...)
(with-mock-harness #:responses responses
                   maybe-strict
                   body ...)

maybe-strict =
| #:strict-tools? strict?

Same setup as with-live-harness but synchronous with no timeout. Exactly one of #:caller or #:responses must be supplied. #:responses installs an internal caller that pops one response per call from the list; running the queue to empty raises.

procedure
(ashlar-with-tool-stub s
tool-name
stub-handler) → ashlar-meta?
  s : ashlar-meta?
  tool-name : symbol?
  stub-handler : (hash? . -> . any)

Returns a new ashlar identical to s except the tool middleware named tool-name is replaced by a fresh middleware built with the stored schema and stub-handler. Recurses through composition children. Raises when tool-name isn’t found, when multiple middlewares share the name, or when an ashlar has no rebuilder.

5.14.2 Assertions🔗ℹ

procedure
(tool-calls) → (listof hash?)

Every recorded tool-call record in call order. Drains pending log events before reading. Returns '() when called outside a harness.

procedure
(tool-calls-by-name name) → (listof hash?)
name : symbol?

Filters (tool-calls) down to records whose 'name key is eq? to name.

procedure
(tool-call-count name) → exact-nonnegative-integer?
name : symbol?

(length (tool-calls-by-name name)).

syntax
(check-tool-called? name)
(check-tool-called? name msg)

Rackunit-style assertion. Passes when (tool-call-count name) > 0.

syntax
(check-tool-not-called? name)
(check-tool-not-called? name msg)

Rackunit-style assertion. Passes when (tool-call-count name) is zero.

syntax
(check-tool-call-count name n)
(check-tool-call-count name n msg)

Rackunit-style assertion. Passes when (tool-call-count name) equals n.

5.14.3 Stub helpers🔗ℹ

procedure
(stub-answer s) → (hash? . -> . any)
s : string?

Returns a constant tool handler that ignores its input and returns (values s (hasheq 'stub #t)).

procedure
(stub-fn f) → (hash? . -> . any)
f : (hash? . -> . any)

Identity passthrough; returns f unchanged. Exists so tests can opt into the explicit (stub-fn ...) form alongside (stub-answer ...) for documentation value.

5.14.4 Response builders🔗ℹ

procedure
(llm-text s) → any/c
s : string?

An llm-response with content s and no tool calls.

procedure
(llm-tool-call tool-name
[ #:id id
#:question question
#:input input]) → any/c
  tool-name : (or/c symbol? string?)
  id : string? = (fresh-call-id)
  question : (or/c string? #f) = #f
  input : (or/c hash? #f) = #f

An llm-response carrying exactly one tool-call block and an empty text body. #:question is sugar: when non-false and #:input is false, builds (hasheq 'question question) as the input.

procedure
(llm-multi text-or-response resp ...) → any/c
text-or-response : (or/c string? any/c)
resp : any/c

Variadic combiner. If the first argument is a string, it becomes the text of the new response and tool calls are collected from the remaining arguments. If it’s an llm-response, its text is dropped and its tool calls plus every subsequent response’s tool calls are concatenated.

5.14.5 Parameters🔗ℹ

parameter
(harness-current-caller) → (or/c procedure? #f)
(harness-current-caller c) → void?
c : (or/c procedure? #f)
= #f

Bound by with-live-harness and with-mock-harness to the caller installed for the harness. Read inside body to pass the caller to make-agent-ashlar.

5.15 stone/logging🔗ℹ

(require stone/logging)

package: Stone

Structured logging on a dedicated Racket logger. See Observability for the design.

value
stone-logger : logger?

Racket logger named ashlar, created with #:parent #f so events do not propagate to the root logger. Attach a log receiver to this logger to collect events.

syntax
(log-stone-debug arg ...)

syntax
(log-stone-info arg ...)

syntax
(log-stone-warning arg ...)

syntax
(log-stone-error arg ...)

syntax
(log-stone-fatal arg ...)

Level-specific macros generated by define-logger for stone-logger. See Racket’s define-logger for argument shapes. Prefer stone-event for structured events.

procedure
(stone-event level event data) → void?
  level : (or/c 'debug 'info 'warning 'error 'fatal)
  event : symbol?
  data : hash?

Adds event, trace-id, span-id, parent-span-id, and timestamp to data, then logs via stone-logger only when level is enabled.

parameter
(current-trace-id) → (or/c string? #f)
(current-trace-id id) → void?
id : (or/c string? #f)
= #f

Identifies a full ashlar run; set once at the top and inherited by every ashlar below.

parameter
(current-span-id) → (or/c string? #f)
(current-span-id id) → void?
id : (or/c string? #f)
= #f

Identifies the currently executing ashlar. make-ashlar’s wrapper parameterizes this to a fresh span-* id for each invocation.

parameter
(current-parent-span-id) → (or/c string? #f)
(current-parent-span-id id) → void?
id : (or/c string? #f)
= #f

Holds the enclosing ashlar’s span id. make-ashlar’s wrapper sets this from the caller’s current-span-id before allocating a new span.

procedure
(generate-id [prefix]) → string?
prefix : string? = ""

Returns "<prefix><ms>-<random>" where <ms> is the truncated millisecond clock and <random> is a 5-digit number. Not cryptographically strong; intended for log correlation.

5.16 stone/trace🔗ℹ

(require stone/trace)

package: Stone

Public API for reading and analyzing Stone’s trace.jsonl files. A trace is produced by attaching a logger to stone-logger (see Trace a run for emission); this module covers the consumption side.

The raco stone trace subcommands (tally, lifecycle, payload) are thin wrappers over the data API below — if you want to build a custom inspection tool, require this module and work with the primitives directly.

5.16.1 Loading🔗ℹ

procedure
(load-trace path) → (listof hash?)
path : path-string?

Read a JSONL trace file into a list of event hashes, in file order. Each event is a hash with keys 'level, 'message, 'topic, and 'data; the event-specific payload lives under 'data. Use the accessors below to read fields without digging.

5.16.2 Event accessors🔗ℹ

Each accessor takes one event hash (as returned by load-trace) and returns a normalized field. Use these rather than hash-refing directly so callers stay robust against future trace-shape changes.

procedure
(event-data e) → hash?
e : hash?

Return the event-specific payload hash. Most events carry their fields here; the other accessors all read from this.

procedure
(event-type e) → string?
e : hash?

The event-type string (e.g. "api-call", "tool-dispatch"). Empty string if absent.

procedure
(event-timestamp e) → real?
e : hash?

Millisecond-epoch timestamp. 0 if absent.

procedure
(event-ashlar-name e) → string?
e : hash?

Best-effort ashlar/agent/tool name. Falls back through 'ashlar-name, 'agent-ashlar-name, and 'tool-name because different event types use different keys. Empty string if none of those are present.

procedure
(event-turn-number e) → (or/c exact-nonnegative-integer? #f)
e : hash?

LLM turn number for api-call/api-response events. #f for events that don’t carry one.

5.16.3 Aggregators🔗ℹ

procedure
(tally-events events)
→ (listof (cons/c string? exact-nonnegative-integer?))
events : (listof hash?)

Return an alist of (cons event-type count) sorted by count descending. The shape used by raco stone trace tally and useful for a first-pass overview of what happened.

procedure
(lifecycle-events events) → (listof hash?)
events : (listof hash?)

Filter events down to the ones that tell the story of how the orchestrator progressed: ashlar lifecycle, tool dispatch, api-call/response, streaming progress, and known failure events. Excludes noise like middleware-run. The set is defined inside stone/trace and not configurable; if you need different filtering, use filter with your own predicate.

procedure
(find-payloads events
[ #:ashlar ashlar
#:turn turn]) → (listof hash?)
  events : (listof hash?)
  ashlar : (or/c string? #f) = #f
  turn : (or/c exact-nonnegative-integer? #f) = #f

Return "api-call-payload" events in file order, optionally filtered by ashlar name and/or turn number. Useful when you want to inspect the exact messages an ashlar sent to its caller.

Note that "api-call-payload" events are only emitted at the 'debug log level; calls captured at the default 'info level have headers ("api-call") but not full message contents.

5.16.4 Formatting🔗ℹ

procedure
(format-lifecycle-line e) → string?
e : hash?

Render one lifecycle event as a single human-readable line with a HH:MM:SS local-time prefix, the event type, the ashlar name, and event-type-specific extras (e.g., turn=5 msgs=19 for "api-call"). Used by raco stone trace lifecycle.

5.16.5 CLI entry points🔗ℹ

These are the implementations of the raco stone trace subcommands; they’re provided so other tools (test harnesses, ad-hoc scripts) can invoke them programmatically with the same behavior as the CLI.

procedure
(stone-trace-cli) → any

Dispatch the trace subcommand based on current-command-line-arguments. Reads the next argv token as the sub-subcommand name ("tally", "lifecycle", "payload") and forwards remaining args to the matching runner.

procedure
(run-tally path) → any
path : path-string?

Print the total event count and the type tally to current output. Equivalent to raco stone trace tally <path>.

procedure
(run-lifecycle path) → any
path : path-string?

Walk lifecycle events in chronological order, one format-lifecycle-line per output line. Equivalent to raco stone trace lifecycle <path>.

procedure
(run-payload path
[ #:ashlar ashlar
#:turn turn
#:last? last?]) → any
  path : path-string?
  ashlar : (or/c string? #f) = #f
  turn : (or/c exact-nonnegative-integer? #f) = #f
  last? : boolean? = #f

Print a single "api-call-payload" event: ashlar, turn, model, system prompt (first 400 chars), and one line per message with role + content preview + tool-call count.

By default picks the first matching payload; pass #:last? #t for the most recent. Equivalent to raco stone trace payload <path> with –ashlar, –turn, and –last flags.

5.17 stone/lens🔗ℹ

(require stone/lens)

package: Stone

Lightweight path accessor used by ashlar-match extractors and validator lens checks. Re-exported from stone for convenience.

procedure
(lens path ...) → any/c
path : symbol?

Returns a lens that, applied to a node, walks the node’s content hash through the given path. Used as the extractor in (ashlar-match (lens 'field) ...) to branch on a field value.

procedure
(lens? v) → boolean?
v : any/c

#t iff v was built by lens.

procedure
(lens-path l) → (listof symbol?)
l : any/c

Returns the path list stored in l, or #f if l isn’t a lens.

5.18 stone🔗ℹ

(require stone)

package: Stone

Umbrella module. Re-exports every public binding from stone/edge, stone/dag, stone/decisions, and stone/lens, plus the runtime types documented here (default-model, make-json-schema, and the middleware / context / recommendation support for custom multi-turn behavior).

For code meant to be compact, (require stone) pulls the core vocabulary. Reach for the per-module requires (stone/llm-ashlar, stone/llm-client, stone/tools, stone/test, stone/validate, stone/logging) for the modules the umbrella doesn’t cover.

5.18.1 Parameters🔗ℹ

parameter
(default-model) → (or/c string? #f)
(default-model m) → void?
m : (or/c string? #f)
= #f

Global fallback model identifier, read by make-context when #:model is absent and by make-agent-ashlar when #:model is absent.

5.18.2 Schema builder🔗ℹ

procedure
(make-json-schema name properties required) → hash?
  name : string?
  properties : hash?
  required : (listof (or/c symbol? string?))

Returns a hash shaped as

(hasheq 'type "json_schema"
        'json_schema
        (hasheq 'name name
                'strict #t
                'schema (hasheq 'type "object"
                                'properties properties
                                'required required
                                'additionalProperties #f)))

suitable for the #:response-format argument of make-agent-ashlar or a caller directly. Symbols in required are coerced to strings.

5.18.3 Middleware onion types🔗ℹ

These are the types make-agent-ashlar uses internally. Most users never construct them directly — reach for them when building a custom decide function or a middleware that needs to inspect context state.

struct
(struct context ( messages
system
tools
response-format
model
budget
meta
dag
node-draft
threshold)
    #:transparent)
  messages : (listof hash?)
  system : string?
  tools : (listof hash?)
  response-format : (or/c hash? #f)
  model : (or/c string? #f)
  budget : exact-nonnegative-integer?
  meta : hash?
  dag : (or/c dag? #f)
  node-draft : (or/c hash? #f)
  threshold : (or/c threshold? #f)

Per-turn state threaded through the middleware onion. This is the runtime message-assembly context — distinct from the context data structure of stone/context-struct that make-agent-ashlar takes as #:context. dag is the effective DAG the turn runs against; threshold is the run’s threshold (see stone/threshold). meta holds 'trace-id, 'span-id, 'agent-name, 'turn-number, 'last-response, 'recommendations.

struct
(struct middleware (name guard handler)
    #:transparent)
  name : symbol?
  guard : (context? . -> . boolean?)
  handler : (context? (context? . -> . context?) . -> . context?)

Middleware record.

struct
(struct recommendation (type source reason)
    #:transparent)
  type : (or/c 'continue 'halt 'loop)
  source : any/c
  reason : any/c

Recommendation emitted by middleware or a decide function.

procedure
(make-context [ #:messages messages
#:system system
#:tools tools
#:response-format response-format
#:model model
#:budget budget
#:meta meta
#:dag dag
#:node-draft node-draft
#:threshold threshold]) → context?
  messages : list? = '()
  system : string? = ""
  tools : list? = '()
  response-format : (or/c hash? #f) = #f
  model : (or/c string? #f) = (default-model)
  budget : exact-nonnegative-integer? = 4096
  meta : hash? = (hash)
  dag : (or/c dag? #f) = #f
  node-draft : (or/c hash? #f) = #f
  threshold : (or/c threshold? #f) = #f

Default constructor. #:model is read from default-model at call time when not supplied.

procedure
(context-set ctx
[ #:messages messages
#:system system
#:tools tools
#:response-format response-format
#:model model
#:budget budget
#:meta meta
#:dag dag
#:node-draft node-draft
#:threshold threshold]) → context?
  ctx : context?
  messages : any/c = #f
  system : any/c = #f
  tools : any/c = #f
  response-format : any/c = #f
  model : any/c = #f
  budget : any/c = #f
  meta : any/c = #f
  dag : any/c = #f
  node-draft : any/c = (void)
  threshold : any/c = (void)

Returns a new context with the specified fields changed. Most fields use (or new old), so passing #f means "keep," not "clear." #:node-draft and #:threshold use private sentinels, so passing #f for either clears it (both #f values are meaningful — "no draft," "no threshold").

procedure
(make-middleware name guard handler) → middleware?
  name : symbol?
  guard : (context? . -> . boolean?)
  handler : (context? (context? . -> . context?) . -> . context?)

Constructor.

procedure
(run-onion middleware-list ctx caller) → context?
  middleware-list : (listof middleware?)
  ctx : context?
  caller : (context? . -> . context?)

Executes the middleware chain around caller. For each middleware whose guard returns #t, the handler is invoked with (ctx inner-call); otherwise the handler is bypassed and the inner call runs directly. Emits 'middleware-run debug events.

procedure
(recommend ctx type source reason) → context?
  ctx : context?
  type : (or/c 'continue 'halt 'loop)
  source : any/c
  reason : any/c

Appends a recommendation to the 'recommendations list under (context-meta ctx).

5.19 Command-line interface🔗ℹ

Stone’s command-line surface: the raco stone TUI launcher and the validate, trace, and install-skill subcommands.

5.19.1 raco stone🔗ℹ

Synopsis: raco stone [flags...]

Loads a Stone configuration (if present), merges any command-line flag overrides, allocates (or resumes) a session journal, and launches the Stone TUI with the resulting agent ashlar.

Flag	Argument	Description
–url	url	LLM API endpoint URL. Overrides url in config.
–model	model	Model identifier. Overrides model in config and sets default-model.
–continue	[id]	Resume a recorded session (most-recent when no id).

–url and –model are #:once-each. No positional arguments are accepted.

5.19.1.1 Configuration🔗ℹ

On startup the CLI looks for .stone/settings.rkt (walking up from the current directory to $HOME). If found, it’s loaded with dynamic-require and expected to provide a zero-argument procedure named build-agent. The CLI invokes build-agent with no arguments; its return value is an ashlar-meta? — the topology to run. The CLI builds a single threshold for the run and hands it to run-tui, which binds it per run (as current-threshold) and subscribes to it. The agent reads current-threshold when it emits, so its observation crossings reach the TUI without the config threading a threshold — symmetric with current-journal.

#lang racket

(require stone/llm-ashlar stone/llm-client stone/context-struct)

(provide build-agent)

(define caller (make-openai-caller #:url "http://localhost:8000"))

(define (build-agent)

(make-agent-ashlar caller

#:produces 'response

#:context (context (system "You are helpful.")

(history 'response)

(user 'prompt))))

5.19.1.2 Sessions🔗ℹ

Each raco stone run is a durable session: its journal lives at .stone/sessions/<id>.jsonl, resolved next to the loaded .stone/settings.rkt (or .stone/sessions/ under the current directory when there is no config). A bare raco stone allocates a fresh session id; raco stone –continue reopens the most-recent session (or the one named by –continue <id>) and resumes it — the journal replays as scrollback and the run picks up where it stopped, as long as the topology is unchanged. List recorded sessions with raco stone sessions (below). See Run a durable, resumable session for the durability model.

5.19.1.3 Exit codes🔗ℹ

Code		Meaning
0		Normal TUI exit, or fall-through when no agent is configured.

The CLI does not call exit itself; exit status is whatever the TUI or the Racket runtime returns on termination.

5.19.2 raco stone sessions🔗ℹ

Synopsis: raco stone sessions

Lists the recorded sessions under the current sessions directory (.stone/sessions/), newest activity first, as a fixed-width table with columns ID, STARTED, LAST-ACTIVITY, and LABEL (the first user prompt, truncated). Prints No recorded sessions. when the directory is empty or absent. Pair it with raco stone –continue <id> to resume a specific session.

5.19.3 raco stone validate🔗ℹ

Synopsis: raco stone validate <ashlar-file>

Loads a Racket file, extracts the binding named ashlar, and runs validate-ashlar on it. Prints errors and warnings; sets exit code from the result.

5.19.3.1 Ashlar file requirements🔗ℹ

The file is loaded via dynamic-require. It must:

Be a valid Racket module that racket can dynamic-require.
provide a binding named exactly ashlar.
Bind ashlar to a ashlar-meta? value.

If the file doesn’t export ashlar, the CLI prints Error: <file> does not export ’ashlar and exits 1.

5.19.3.2 Validation categories🔗ℹ

Category	Error types	Affects exit code
Hard errors	missing-producer, invalid-lens, fanout-not-reduced	yes — exit 1
Warnings	maybe-unavailable	no — exit 0

5.19.3.3 Output🔗ℹ

On success:

Ashlar is valid.

When hard errors are present, a header and one line per error, formatted as [<type>] <ashlar-name>: <message>:

Errors (2):

[missing-producer] classify: classify queries 'ticket but no upstream Stone produces it

[invalid-lens] dispatch: lens path '(category) not found in upstream schema properties

When warnings are present, an analogous Warnings (N): block prints. Both blocks may appear in the same run; the hard-error block (if any) prints first.

5.19.3.4 Exit codes🔗ℹ

Code		Meaning
0		Ashlar valid, or only maybe-unavailable warnings present.
1		Missing ashlar-file argument, file doesn't export ashlar, hard errors reported, or subcommand other than validate supplied.

5.19.4 raco stone trace🔗ℹ

Synopsis: raco stone trace <subcommand> <path> [opts...]

Inspect a trace.jsonl file produced by a Stone run with stone-logger attached. Three subcommands cover the default investigation flow:

Subcommand		Description
tally <path>		Print total event count and per-event-type counts. First-pass overview of what happened during the run.
lifecycle <path>		Print the filtered story of the run, one event per line: ashlar start/end, tool dispatch, api-call/response, streaming progress, and failure events. Excludes noise like middleware-run.
payload <path> [opts]		Dump a single api-call-payload event: ashlar, turn, model, system prompt, and one line per message with role + content preview + tool-call count.

5.19.4.1 payload options🔗ℹ

Flag	Argument	Description
–ashlar	name	Filter to payloads from the named ashlar.
–turn	n	Filter to the named LLM turn.
–last		Pick the most recent matching payload (default is the first).

"api-call-payload" events are only emitted at the 'debug log level; if payload returns No api-call-payload found, re-run with STONE_LOG_LEVEL=debug in the environment to capture them.

The underlying data API is documented at stone/trace — if you want to script trace analysis beyond what these subcommands provide, require stone/trace and use the primitives directly.

5.19.4.2 Exit codes🔗ℹ

Code		Meaning
0		Subcommand ran successfully.
1		Missing path, missing required option value, unknown subcommand, or unrecognized argument.

5.19.5 raco stone install-skill🔗ℹ

Synopsis: raco stone install-skill [–force] [–target-dir DIR]

Install the bundled Claude Code skills into ~/.claude/skills/ by default. Two skills ship with Stone and work as a pair: scope-ashlar (the guided interview that scopes an ashlar tree) and build-ashlar (which translates a scoped tree into a runnable Racket scaffold). build-ashlar also carries a scribblings snapshot for primitive lookup; scope-ashlar does not (it writes no Racket).

Flag		Description
–force		Overwrite existing skill bodies. Without this, an already-installed skill body is left untouched.
–target-dir DIR		Install under DIR instead of HOME/.claude/skills/. The skills end up at DIR/scope-ashlar/ and DIR/build-ashlar/.

The command is safe to re-run. Without –force, an already-installed skill body is left untouched, and build-ashlar’s scribblings snapshot is refreshed so it tracks your current Stone version — so a bare re-run after upgrading Stone is the normal way to update the docs. With –force it wipes and re-ships the skill bodies as well.

5.19.5.1 Exit codes🔗ℹ

Code		Meaning
0		Install, forced re-install, or bare scribblings refresh succeeded.
1		Unknown flag, bad argument, or filesystem error during install.

1	Why Stone
2	Reading Racket
3	Tutorials
4	How-to guides
5	Reference
6	Explanation

5.1	stone/ edge
5.2	stone/ dag
5.3	stone/ messages
5.4	stone/ llm-ashlar
5.5	stone/ context-struct
5.6	stone/ threshold
5.7	stone/ record
5.8	stone/ llm-types
5.9	stone/ llm-client
5.10	stone/ repetition-watch
5.11	stone/ tools
5.12	stone/ decisions
5.13	stone/ validate
5.14	stone/ test
5.15	stone/ logging
5.16	stone/ trace
5.17	stone/ lens
5.18	stone
5.19	Command-line interface