Commit graph

52 commits

Author SHA1 Message Date
Bryan Helmkamp
e7d64136b3 Rewrite changelog entries with improved style and structure
Each major feature gets its own H2 heading with narrative depth
and code examples instead of dense bullet lists under category
headers. Minor improvements and fixes go at the bottom as a flat
list. Style inspired by Qlty, Linear, Vercel, and Resend changelogs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 03:13:42 -05:00
Bryan Helmkamp
45a7762a17 changelog 2026-03-05 03:00:37 -05:00
Bryan Helmkamp
26f08a904e Rename GET /runs/{id}/files to GET /runs/{id}/compare
Rename the endpoint, schema (RunFiles -> RunCompare), operation ID,
handlers, and frontend route across the full stack.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 00:53:45 -05:00
Bryan Helmkamp
a40c6bdd29 Add QuestionType enum to OpenAPI spec replacing stringly-typed field
The question_type field on ApiQuestion was a bare string serialized via
Debug formatting. Define a proper enum in the spec so typify generates a
typed QuestionType, then map from the workflow enum in the handler.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 00:49:03 -05:00
Bryan Helmkamp
14322f40c2 Wrap non-paginated list endpoints in paginated response shape
Wrap 4 list endpoints that returned bare arrays in the standard
paginated `{ data, meta: { has_more } }` shape so adding real
pagination later is additive rather than a breaking change.

Endpoints: GET /runs/{id}/questions, /runs/{id}/stages,
/runs/{id}/verifications, and /verifications.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 00:41:32 -05:00
Bryan Helmkamp
af12b0b697 Add offset-based pagination to 9 list endpoints
Apply the same page[limit]/page[offset] pagination pattern from
GET /runs to: workflows, workflow runs, retros, sessions, projects,
branches, saved queries, query history, and stage turns.

Each endpoint now returns { data, meta: { has_more } } instead of
a bare array. Includes OpenAPI spec updates, demo handler changes,
regenerated TS client, updated frontend consumers, and a new
pagination conformance test.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 23:56:32 -05:00
Bryan Helmkamp
b268efd85f Add global concurrency limiter with queued/starting run states
Runs now go through a state machine (queued → starting → running →
completed/failed/cancelled) instead of spawning immediately. A background
scheduler promotes queued runs when capacity is available, defaulting to
4 concurrent runs. Configurable via --max-concurrent-runs CLI flag or
max_concurrent_runs in server.toml.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 22:56:19 -05:00
Bryan Helmkamp
1d0e45ffdf Add offset-based pagination to GET /runs
Introduce page[limit]/page[offset] query params and { data, meta: { hasMore } }
response wrapper for the /runs endpoint, establishing the pagination pattern
for all future list endpoints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 22:32:57 -05:00
Bryan Helmkamp
43a0c18161 Add GET /usage endpoint for aggregate token/cost accounting across runs
Tracks total runs, input/output tokens, cost, and runtime in-memory
(resets on server restart). Accumulates from checkpoint node_outcomes
when runs complete. Includes per-model breakdown.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 21:56:50 -05:00
Bryan Helmkamp
3e68c41f4e Adopt uniform error response format across Arc API
All API errors now return a consistent JSON shape:
{"errors": [{"status": "4xx", "title": "...", "detail": "..."}]}

Introduces ApiError type with IntoResponse impl, replaces bare
StatusCode returns and ad-hoc {"error": "..."} responses in all
handlers and auth extractors. Updates OpenAPI spec and regenerates
TypeScript client.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 21:32:24 -05:00
Bryan Helmkamp
bb0fdfe972 Add /, /health, /openapi.json, /user endpoints to Arc API
Add discovery, health check, OpenAPI spec, and current user endpoints.
The first three are public; /user requires authentication and returns
the login extracted from JWT sub claim, mTLS CN, or "demo" in demo mode.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-04 21:10:59 -05:00
Bryan Helmkamp
72d71525f5 agent-design-memo.md 2026-03-03 12:44:28 -05:00
Bryan Helmkamp
ead284cc39 Add icons to sidebar groups, move Deployment to Guides
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-03 10:35:32 -05:00
Bryan Helmkamp
d450695a20 Scaffold Mintlify docs site with full navigation structure
Replace boilerplate Mintlify starter with Arc docs outline:
- Switch to almond theme (sidebar search, card-based layout)
- Top nav: Documentation, Guides, API Reference, Changelog
- Documentation sidebar: Getting Started, Core Concepts, Defining
  Workflows, Executing Workflows, Agents, Administration, Deployment,
  Reference
- Guides tab with example workflows
- Get Started button in navbar
- 48 MDX stub pages across 9 directories

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-03 10:33:09 -05:00
Bryan Helmkamp
82643d80c3 Add icons to API reference sidebar categories
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-02 23:28:06 -05:00
Bryan Helmkamp
b694c20b53 Explicitly order API reference groups in docs.json
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:56:57 -05:00
Bryan Helmkamp
169da74f0e Reorder API tags: HIL before Run Internals, Run Outputs before Retros, Projects before Settings
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:55:15 -05:00
Bryan Helmkamp
64dd9b925b Move Preview URL to Human-in-the-Loop, Retrieve Run Usage to Run Outputs
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:52:38 -05:00
Bryan Helmkamp
8f684e6c48 Reorder OpenAPI tags for Mintlify nav sidebar
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:46:26 -05:00
Bryan Helmkamp
5164b73c58 Move List Run Files and Verifications to Run Outputs tag, rename Retrieve Run SVG to Render SVG
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:40:55 -05:00
Bryan Helmkamp
3d27d1fb72 Move preview URL endpoint to new Sandbox tag and shorten summary
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:40:12 -05:00
Bryan Helmkamp
4fdcd77dde Auto-copy OpenAPI spec to docs when generating API client
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:38:48 -05:00
Bryan Helmkamp
7df7a1e8de Replace docs OpenAPI spec copy with symlink to source of truth
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:36:08 -05:00
Bryan Helmkamp
4cd601833a Sync Mintlify docs OpenAPI spec with source of truth
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 16:33:44 -05:00
Bryan Helmkamp
1fa26aa1ec Rename API operationIds and summaries to follow consistent conventions
Use List/Retrieve/Start/Stream/Cancel naming. Add new tags: Run Internals,
Human-in-the-Loop, Usage. Regenerate TypeScript client.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 12:24:32 -05:00
Bryan Helmkamp
ffa9d1d505 Rename docs site from Mint Starter Kit to Arc
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-02 11:21:33 -05:00
Bryan Helmkamp
802727ac07 docs 2026-03-02 11:01:38 -05:00
Bryan Helmkamp
5c54f37a7c Add mintlify docs 2026-03-02 09:59:44 -05:00
Bryan Helmkamp
a456672959 move docs -> docs-internal 2026-03-02 09:59:00 -05:00
Bryan Helmkamp
4849dd8488 draft-api-design.md 2026-03-02 09:41:01 -05:00
Bryan Helmkamp
7002f0638a Rename ManagerLoopHandler to SubWorkflowHandler
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 23:39:58 -05:00
Bryan Helmkamp
e00898d266 Document event enum tracing and double-logging prevention
Update logging strategy to explain that event enums have trace()
methods called automatically at emit sites, and that wrapper
variants are no-ops to prevent double-logging.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 19:18:01 -05:00
Bryan Helmkamp
303c78e584 Add logging strategy document
Defines structured logging conventions for the team: level guidelines
(INFO for production, DEBUG for on-demand investigation), structured
field patterns, and per-crate examples.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 18:29:14 -05:00
Bryan Helmkamp
8aa56285f4 Rename remaining attractor references to arc
- AttractorError → ArcError across 30 source files
- .attractor/ → .arc/ for artifacts and skills paths
- ATTRACTOR_NODE_ID → ARC_NODE_ID env var
- attractor-rust → arc in Cargo.toml repository URLs
- attractor-spec.md → arc-spec.md with content updates
- Update server banner, test comments, README examples, and docs

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-01 12:11:24 -05:00
Bryan Helmkamp
2a82a4e147 Change default_max_retry from 50 to 3
Aligns with the kilroy implementation of the Attractor spec. A default
of 50 retries is far too aggressive for most workflows.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 18:02:30 -05:00
Bryan Helmkamp
7ad750c5b6 Rename tool handler to script handler and add language attribute
Rename the entire "tool" concept to "script": ToolHandler → ScriptHandler,
tool_command attribute → script, tool.output → script.output, and all
related artifact filenames. Add a language attribute (shell | python,
default shell) so script nodes can run Python via python3 -c natively.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 09:50:39 -05:00
Bryan Helmkamp
1e3726b7f3 Add missing data to agent events and cost tracking in pipeline logs
Enrich three AgentEvent variants with payload data (UserInput.text,
TurnLimitReached.max_turns, SteeringInjected.text) and forward
UserInput/SteeringInjected to the pipeline event stream. Add cost
field to StageUsage (computed from model pricing catalog) and
total_cost to PipelineCompleted (summed from stage outcomes).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Entire-Checkpoint: adb2363c9ec4
2026-02-25 17:17:13 -05:00
Bryan Helmkamp
74a6b219cc Fix spec: FAIL does not trigger retries, only RETRY does
The test criteria incorrectly said FAIL outcomes should be retried.
The pseudocode (Section 3.5) and the C reference implementation both
return immediately on FAIL. Only RETRY status triggers the retry loop.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 16:19:10 -05:00
Bryan Helmkamp
94326f5438 docs/specs 2026-02-23 10:17:40 -05:00
Bryan Helmkamp
d3e396753c Remove stale review docs, add spec DoD pipeline definitions
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 09:47:50 -05:00
Bryan Helmkamp
30cf3a6787 Rename coding-agent-loop crate to agent
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 09:17:48 -05:00
Bryan Helmkamp
5932b500e7 Implement GET /pipelines/{id}/graph endpoint for SVG rendering
Stores DOT source in ManagedPipeline and pipes it through `dot -Tsvg`
on request. Returns image/svg+xml on success, 502 if graphviz is
unavailable, 404 if pipeline not found. Resolves spec gap #1.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 09:13:36 -05:00
Bryan Helmkamp
54d0c887dc Add end-to-end test for subgraph class derivation, update spec gap analysis
Closes the subgraph class derivation test gap by adding a parse() pipeline
test that verifies DOT subgraph labels produce correct CSS-like classes on
contained nodes. Updates gap analysis to remove resolved items, add spec
contradictions section, and narrow remaining gaps to SVG rendering and
retry predicate customization.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 08:39:42 -05:00
Bryan Helmkamp
a917a8d615 Implement 6 spec gaps: preamble synthesis, thread_id plumbing, cancellation, recording replay, retry presets, inform()
- Gap 1: Real preamble synthesis per fidelity mode (truncate, compact,
  summary:low/medium/high) in new preamble.rs module, replacing placeholder
- Gap 2: Pass thread_id to CodergenBackend.run() so backends can reuse
  LLM sessions across nodes sharing the same thread
- Gap 7: Engine cancellation via AtomicBool token checked between nodes,
  wired to server cancel endpoint, new Cancelled error variant
- Gap 8: RecordingInterviewer serialization (to_json/from_json, file I/O)
  and new ReplayInterviewer for replaying recorded Q&A sessions
- Gap 12: Preset retry policies selectable from DOT via retry_policy attr
  (none, standard, aggressive, linear, patient)
- Gap 15: Engine calls Interviewer.inform() at pipeline start, stage
  start, and stage complete lifecycle points

37 new tests (450 unit + 49 integration, all passing).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-23 08:23:27 -05:00
Bryan Helmkamp
a2f9e87b7c Close spec compliance gaps: retry context, thread resolution, fan-in logging
Fix 3 confirmed gaps from spec compliance review (85 items, 91.8% aligned):

- Write internal.retry_count.<node_id> to PipelineContext after retries
  so handlers and conditions can access retry counts (spec 5.1)
- Add graph-level default_thread (step 3) to 5-step thread ID resolution,
  pass graph param to resolve_thread_id (spec 5.4)
- Write prompt.md/response.md in fan_in LLM evaluation path (spec 5.6)

Also includes pre-existing improvements: checkpoint stores node_outcomes
and next_node_id for correct resume, engine timeout enforcement,
auto_status support, fidelity degradation on resume, preamble injection,
is_retryable error classification, stylesheet specificity correction,
full stylesheet parse validation, direction_valid lint rule, pre-hook
returns Skipped not Fail, fan-in score-based sorting and all-fail
detection, manager_loop child autostart and steer cooldown.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 10:49:21 -04:00
Bryan Helmkamp
34836200e5 Implement attractor crate: DOT-based pipeline runner with full spec compliance
Adds the attractor crate implementing all 11 sections of the attractor spec:
- DOT parser (lexer, grammar, semantic analysis) for strict DOT subset
- Pipeline execution engine with edge selection, goal gates, retry logic,
  failure routing, checkpoint save/resume, and loop_restart
- 9 node handlers: start, exit, codergen, wait_human, conditional, parallel
  (concurrent with join/error policies), fan_in (with LLM eval), tool, manager_loop
- State management: PipelineContext, Outcome, Artifact store, fidelity resolution
- Human-in-the-loop: Interviewer trait with auto_approve, callback, queue,
  recording, and console implementations, plus timeout enforcement
- Validation: 14 built-in lint rules with custom rule registration API
- Model stylesheet with universal/shape/class/ID selectors and specificity
- Transforms: variable expansion, stylesheet application, preamble; plus
  PipelineBuilder with register_transform and prepare_pipeline
- Condition expression language with =, !=, bare-key truthiness, && combinator
- Event system with all 16 event types emitted by engine and handlers
- Tool call hooks (pre/post) for CodergenHandler
- Run directory with manifest.json and per-node status.json

370 tests (354 unit + 16 integration) covering all spec sections.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-21 12:17:32 -04:00
Bryan Helmkamp
db32f00cd0 Simplify coding-agent-loop: deduplicate mocks, narrow traits, type events
- Extract shared test infrastructure (MockExecutionEnvironment, TestProfile,
  MockLlmProvider) replacing 11 duplicate mock implementations across tests
- Deduplicate tool execution logic between sequential and parallel paths
- Narrow ProviderProfile trait from 14 to 7 required methods via
  ProfileCapabilities struct and default implementations
- Replace stringly-typed HashMap event data with typed EventData enum
- Extract shared assemble_system_prompt helper and register_subagent_tools
  default method, eliminating copy-paste across all 3 profiles
- Replace fragile shell-based glob with glob crate, fix rg detection
- Add delete_file to ExecutionEnvironment, wire git context into env block
- Remove dead code (AgentError::Io, count_turns, trivial derived-trait tests)
- Use match-based lookups in truncation instead of per-call HashMap allocation

Net reduction: -1,401 lines across 20 files. All 180 tests pass.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 16:34:29 -04:00
Bryan Helmkamp
1ffc954a0f Add knowledge_cutoff to ProviderProfile, fix subagent default max_turns
- Add knowledge_cutoff() method to ProviderProfile trait so session can
  populate EnvContext from the profile instead of leaving it empty
- Set subagent default max_turns to 50 per spec (was using session
  factory default which could be 0/unlimited)
- Add corrected spec compliance review after manual verification found
  the initial 5-agent review was largely false positives

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 16:02:20 -04:00
Bryan Helmkamp
82572678c0 Fix model alias resolution and invalid gpt-5.2-mini model ID
resolve_model() was passing raw alias strings (e.g. "gpt5") directly to
APIs instead of resolving them to actual model IDs (e.g. "gpt-5.2").
Also rename gpt-5.2-mini to gpt-5-mini, which is the correct OpenAI
model ID.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 14:01:30 -04:00
Bryan Helmkamp
978a477d1e Fix 8 spec compliance gaps in unified-llm
- Enforce stream_read timeout (30s default) in all 4 providers' streaming code
- Add with_timeout() builder method to all adapter constructors
- Fix ResponseFormatType::JsonObject to serialize as "json" per spec
- Add STEP_FINISH to StreamEventType enum in spec doc
- Add UnsupportedToolChoice error and enforce in all adapters via validate_tool_choice()
- Fix error classification to check status code before message content
- Add stop_sequences support to OpenAI Responses API adapter
- Handle Gemini thought parts (thought: true) in both complete and streaming paths

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-20 12:41:41 -04:00