Decision D039 · accepted in part
Tools for agents and people: diagnostics that name the fix, introspection, quiet output
A record of the language's design, as it stood on 2026-11-18: written for the people who build Diaspar, and kept as it was written. Its code is a sketch, not a program of the site, and an older record may show syntax that a later one changed. It names files of the language's source, which is not public yet.
Status: accepted (2026-11-18) for the answers to questions 1, 3, 4, 7, 8, 9, 10 (D041), 12 and 16 of design/ai.md section 8; proposed for questions 2, 5, 6, 11, 13, 14 and 15, with that document's recommendations. Research: reports/Diaspar for AI agents.md.
Coding agents fail on names more than on syntax (invented functions, wrong arity, missing imports), learn an unknown language from a fast loop of trying and being told the fix, and degrade as their context grows. Diaspar is new, so no model knows it, and it is close to Clojure, so models write Clojure. The answer is the same for agents and people: errors that name the fix, introspection at hand, short output, and one evaluation loop.
Decision
- Tier 1 comes before the debugger and the live protocol in stage D (design §3): diagnostics with candidates and fixes; a table of foreign habits;
diaspar checkreporting every error with--jsonand from text;doc,apropos,sourceand earlier results in the REPL and asdiaspar doc;(reload)with a report of what changed; tests on the evaluator; budgets and quiet output; a guide inside the binary (diaspar doc --guide, the differences from Clojure first);diaspar repl --json. They serve the terminal too, and the protocol's tools then stay thin. - Diagnostics know foreign habits (design §3.2): a data table, Clojure first, with a test per entry, adds a
help:line to an error that happens anyway:{:a 1}keeps its error and gains "maps are written #{:a 1}". It is not legacy (roadmap): no former Diaspar name is kept; it teaches the language to people and models that know another one. :candidatesand:fixin the diagnostic's data now (D014): the names a misspelled name may mean, and edits with three levels of applicability (:safe,:likely,:guess), as rustc's machine-applicable suggestions.diaspar fixcomes later and applies only:safeedits by default.- Quiet output by one rule, never by detecting an agent: when the stream is not a terminal,
test,benchandcheckprint the failures and one summary line; a terminal gets the full report. No reading ofAI_AGENT,CLAUDECODEor the like: the same command behaves the same for every reader. - JSON keys are kebab-case everywhere, the names of the keywords of the data they come from (
duration-ms, notduration_ms);test --jsonchanges accordingly. diaspar newwrites anAGENTS.mdof under 15 lines, static: the commands to build, test and check, and the pointer todiaspar doc --guide. Never a generated overview of the project.- An agent's session is granted
:clock,:random,:term, and:fswithin the package by default (D025's effect names); more is granted by the person.
Amendments: D014 gains :kind, :candidates and :fix in a diagnostic's data; D016 gains quiet output for streams that are not terminals; D020's MCP adapter has the eight tools of design §4.1 (eval, check, doc, search, test, load, debug, status), each also a command with --json.
Proposed (design §8's recommendations, not yet answered)
A stable :kind keyword per diagnostic, explained by diaspar doc --error KIND (2); session names for doc, apropos, source, reload, result over std.meta functions that return data (5); diaspar test compiled by default, the evaluator for --interp, (run-tests), the MCP test tool and doc: examples (6); REPL sessions in a package's listed Markdown files as tests (10); diaspar mcp with its own runtime, --attach for a running one without redefine unless granted (11); state identifiers and scratch evaluations first (13); inferred signatures and effects shown before deciding on written annotations (14); todo holes later, the name reserved (15).
Rejected alternatives
Design §7 lists them: structural editing tools for agents, silent repair of brackets, many fine-grained tools, a long generated context file, behaviour that changes when an agent is detected, a model inside the toolchain.