Commit graph

1060 commits

Author SHA1 Message Date
Bryan Helmkamp
24f0fa7ca0 Add Daytona network access control and fill in execution docs
- Add DaytonaNetwork enum (block/allow_all/allow_list) with custom serde
  Deserialize for TOML string-or-table syntax
- Wire network config through run_config defaults merging and base_params
- Document network access in sandboxing, environments, and run-configuration
- Fill in execution docs: checkpoints, environments, failures, interviews,
  run configuration, observability, retros
- Rename compounding.mdx → retros.mdx, insights.mdx → observability.mdx
- Use DaytonaConfig::default() in tests to reduce boilerplate

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 18:31:19 -05:00
Bryan Helmkamp
735b4648a0 Rename script.output/script.stderr context keys to command.output/command.stderr
Aligns context key names with the handler name (CommandHandler), which was
previously inconsistent.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 18:09:42 -05:00
Bryan Helmkamp
7505cb4ce1 Fill in Agents, Human-in-the-Loop, Stylesheets, Variables pages
- Agents: agent loop, built-in tools, prompts, sub-agents, skills, hooks
- Human-in-the-Loop: gates, accelerators, freeform input, auto-approve
- Stylesheets: selectors, specificity, properties, cascading, full examples
- Variables: run config vars, $goal expansion, variable merging
- Remove model stylesheets section from core workflows page (now dedicated page)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 17:42:19 -05:00
Bryan Helmkamp
dd797cca1a Fill in core docs: How Arc Works, Models, Workflows, Nodes & Stages, Transitions
- How Arc Works: end-to-end architecture with diagram, execution loop, retries,
  sandboxes, observability, and resume
- Models: multi-provider rationale, full catalog table, stylesheets, overrides
  via CLI and TOML, ensemble SVG
- Workflows: anatomy SVG, key node types, branching/loops SVG, parallel SVG,
  model stylesheets, goal gates
- Nodes & Stages: all node types with attributes, fidelity/thread_id tables,
  join/error/retry policy tables
- Transitions: edge selection priority, condition expression language, agent
  transitions, human gates, weight tiebreaking
- Remove workflows/ingestion page

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 17:29:57 -05:00
Bryan Helmkamp
6970a7c0f6 Draft Quick Start page: install, configure, CLI, API server, and web frontend
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:56:14 -05:00
Bryan Helmkamp
d91e0ea6fd Restructure Getting Started docs: add Introduction, rename Overview to Why Arc, add Models placeholder
- Add Introduction page with four card links (Why Arc, Quick Start, Workflows, Agents)
- Rename Overview to Why Arc with updated frontmatter
- Add rendered SVG workflow graph to Why Arc page
- Add Core Concepts > Models placeholder page
- Remove getting-started/workflows page

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:53:53 -05:00
Bryan Helmkamp
9ebc84db67 Draft Getting Started overview page for docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:43:21 -05:00
Bryan Helmkamp
da5752bfc8 Fix Mintlify dev server: valid navbar URL and ignore AGENTS.md
The navbar href must be a full URL (not a relative path) and AGENTS.md
contains HTML comments that are invalid in MDX.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:29:50 -05:00
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