Commit graph

569 commits

Author SHA1 Message Date
Bryan Helmkamp
a9645132fc Add Last-Event-ID support to Sessions SSE endpoint
Each SSE frame now includes a sequential numeric id: field. Clients can
reconnect with the Last-Event-ID header to resume the stream after the
last received event, skipping already-processed events.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 10:00:07 -05:00
Bryan Helmkamp
c738d45c1c Use model slugs in Sessions API examples instead of display names
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 09:55:31 -05:00
Bryan Helmkamp
92dc29eb6f Sessions API review fixes: add updated_at to create response, UUID session IDs, remove misleading SSE schemas
- Add updated_at to CreateSessionResponse for consistency with SessionListItem/SessionDetail
- Add format: uuid to session ID fields and parameter across the OpenAPI spec
- Remove SessionEvent discriminated union and SessionEvent* wrapper schemas that conflated
  SSE transport-level event names with JSON data payload fields
- Update demo data to use proper UUIDs instead of string IDs
- Add uuid dependency to arc-types crate

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 09:51:50 -05:00
Bryan Helmkamp
3a2e91a123 Fix react-doctor warnings: remove dead code, fix keys and accessibility (92→99)
Delete unused files (run-logs.tsx, welcome/), remove unused mock data
and functions from data modules, un-export internal types, replace array
index keys with stable identifiers, fix label/htmlFor association, add
role+onKeyDown to click-intercepting div, and convert anchor to button
in settings sidebar nav.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 09:40:20 -05:00
Bryan Helmkamp
a637a90ec6 Enrich Sessions API: timestamps on all turns, SSE event docs, richer responses
- Add created_at to AssistantTurn and ToolTurn schemas (matching UserTurn)
- Document SSE event types (assistant_turn, tool_turn, done, error) with
  SessionEvent discriminated union schema
- Add title and model to CreateSessionResponse
- Add model and last_message_preview to SessionListItem
- Update demo data with timestamps, model, and preview fields
- Regenerate TypeScript API client

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 09:32:49 -05:00
Bryan Helmkamp
14a8071dc1 Add SVGs and simplify DoD example to two specs
Remove the third attractor spec layer from both single-model and
multi-model variants, keeping just unified-llm and agent-loop.
Add workflow diagram SVGs with dark mode support.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 09:13:01 -05:00
Bryan Helmkamp
4a908db67e Add Definition of Done example workflow to docs
Single-model and multi-model variants showing spec checklist audit,
triage, fix, and verify loops.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:42:10 -05:00
Bryan Helmkamp
64b45d1670 Rename NLSpec Convergence to NLSpec Conformance in docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:41:20 -05:00
Bryan Helmkamp
5eaa653d1f Move OpenAPI spec from openapi/ into docs/api-reference/
Mintlify requires all referenced files under docs/, so consolidate to a
single copy and eliminate the symlink and the copy step in the generate
script.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:35:28 -05:00
Bryan Helmkamp
681791db3f Improve Sessions API schema: discriminated turns, date-time formats, consistent naming
- Refactor SessionTurn into discriminated union (UserTurn, AssistantTurn, ToolTurn)
  using oneOf + discriminator so invalid states are unrepresentable
- Add format: date-time to all timestamp fields for proper codegen types
- Rename CreateSessionRequest.prompt to .content for consistency with SendMessageRequest
- Change sendSessionMessage from 200 to 202 (async processing via SSE)
- Extract inline response to SendMessageResponse schema
- Add updated_at to SessionListItem for sort-by-activity support
- Extract SessionId parameter to components/parameters (DRY)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:33:51 -05:00
Bryan Helmkamp
a4f119ad79 Keep submit button right-aligned on start page when session_sandboxes is off
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:17:06 -05:00
Bryan Helmkamp
6de8307cdb Add security schemes (JWT + mTLS) to OpenAPI spec
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:11:12 -05:00
Bryan Helmkamp
e569770c36 Enrich Sessions API: add ToolUse fields, timestamps, descriptions, and flatten list endpoint
- Add id, is_error, duration_ms to ToolUse; rename args to input
- Add created_at/updated_at timestamps to session schemas; replace time/date display strings
- Add descriptions and examples to all Sessions API fields and endpoints
- Flatten List Sessions response from grouped SessionGroup[] to SessionListItem[]
- Move date grouping (Today/Yesterday/etc.) to React client via groupSessionsByDate()
- Symlink docs/api-reference/arc-api.yaml to canonical openapi/arc-api.yaml
- Update React ToolRow components with duration display and error styling

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 08:01:55 -05:00
Bryan Helmkamp
e4babddd5e Add icons to top nav tabs in Mintlify docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:39:28 -05:00
Bryan Helmkamp
3fe77b6d5f Add session_sandboxes feature flag to gate project/branch pickers
Add a FeatureFlags config section with a session_sandboxes boolean
(default false) to both the Rust server config and web app config.
Gate the project/branch picker UI behind this flag. Set it to false
in the Docker demo config.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:34:32 -05:00
Bryan Helmkamp
699c519c97 Update web UI sessions to use created_at timestamps
Adapt session detail and sidebar to the new schema: use created_at/
updated_at instead of repo/time, display relative timestamps via a new
timeAgo() helper, and remove repo badges from the UI.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:34:25 -05:00
Bryan Helmkamp
9fe17c9a7e Redesign session schemas: replace repo/time with timestamps
Replace `repo` and `time` with ISO 8601 `created_at`/`updated_at`
timestamps across session schemas. Remove `project`/`branch` from
CreateSessionRequest and add optional `model`. Add descriptions and
examples to all session-related OpenAPI schemas and endpoints.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:34:18 -05:00
Bryan Helmkamp
7696644d7e Add "Using the API" section to API Reference docs
Add three new pages under a "Using the API" group in the API Reference
tab: API Overview (base URL, authentication, errors, pagination,
versioning), Demo Mode, and Client SDKs. Nest "Run Internals" as an
expandable sub-group under "Run Outputs" in the nav.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:32:29 -05:00
Bryan Helmkamp
b601df47e5 Per-request demo mode with UI toggle
Replace the server-level `--demo` flag with per-request demo dispatch.
The Rust API builds both a demo and real router; incoming requests with
the `X-Arc-Demo: 1` header hit the demo router (auth disabled, static
data), all others hit the real router with normal auth.

The React web app gets a beaker icon toggle in the top nav bar (next to
the theme toggle) that sets an `arc-demo` cookie. Loaders read the
cookie to decide whether to send the `X-Arc-Demo: 1` header to the API.
The `ARC_DEMO=1` env var still works as a default when no cookie is set.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 07:30:23 -05:00
Bryan Helmkamp
cbc1444489 Add GitHub App IAT integration tests and improve is_repo_public error handling
Add three end-to-end tests for the GitHub App Installation Access Token clone
flow (private repo clone, public repo optimization, not-installed error). Also
return an error from is_repo_public on non-404 HTTP failures instead of
attempting to parse the response as JSON.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-06 06:46:52 -05:00
Bryan Helmkamp
72b6e86f3d Clean up GitHub App credentials: share reqwest client, accept raw PEM, avoid clone
- Share a single reqwest::Client across GitHub API calls in resolve_clone_credentials
  to reuse the TLS connection pool
- Accept raw PEM (not just base64-encoded) in build_github_app_credentials, matching
  the existing decode_pem_env/decode_pem_value convention
- Move github_app into DaytonaSandbox::new() instead of cloning

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:45:19 -05:00
Bryan Helmkamp
cf50625824 Switch Daytona git cloning from gh CLI to GitHub App Installation Access Tokens
Replace `gh auth token` with GitHub App IATs scoped to `contents: read` for
Daytona sandbox git cloning. Public repos are auto-detected and cloned without
credentials. Private repos get short-lived, repo-scoped tokens. Clear error
messages for each failure mode (app not installed, suspended, no repo access,
auth failure). Falls back gracefully when no GitHub App is configured.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:31:40 -05:00
Bryan Helmkamp
41f72116f2 Update changelog with GPT-5.4, per-node loop limits, and $$ escaping
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:20:58 -05:00
Bryan Helmkamp
21f9841623 Fill in tutorials, examples, and reference docs with content and SVGs
- Add SVG workflow diagrams for all tutorials and examples
- Fill in NLSpec Convergence and Semantic Port example content
- Add Solitaire example workflow
- Add error handling sections to tools and subagents docs
- Add context compaction and artifact offloading to context docs
- Add credential redaction note to observability docs
- Add workflow diagram Frame references to tutorials

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:14:02 -05:00
Bryan Helmkamp
013101a6f0 Add Clone Substack example workflow adapted from Kilroy
Port Kilroy's substack-spec-v01.dot as a full Arc example with:
- Debate planning (Opus + Gemini Flash independent plans)
- Six-stage verify chain (fmt, build, test, browser, artifacts, fidelity)
- Ensemble review with consensus (two providers)
- Postmortem repair loop with replan/toolchain routing
- Full Kilroy prompts adapted for Arc conventions
- Overview SVG with light/dark mode support

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:13:25 -05:00
Bryan Helmkamp
9d1bd1d091 Add GPT-5.4 and GPT-5.4 Pro to model catalog
Add both models with aliases (gpt54, gpt54-pro). Neither replaces
gpt-5.2 as the OpenAI default. Update fallback chain test since
GPT-5.4 ($2.50) is now closer to Opus ($15) than GPT-5.2 ($1.75).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:12:21 -05:00
Bryan Helmkamp
1b2a63f6af Implement per-node max_visits override for loop detection
Per-node `max_visits` now overrides the graph-level `max_node_visits`
(and the dry-run default of 10) for individual nodes, giving tighter
control over specific loops like fix-and-verify cycles.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-05 22:05:11 -05:00
Bryan Helmkamp
69a203c2a8 Add $$ escape mechanism for variable expansion
Allows literal $ signs in prompts and DOT files by writing $$. Also
refactors VariableExpansionTransform to use expand_vars instead of
string replace, fixing a substring-matching bug with $goal.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 21:44:50 -05:00
Bryan Helmkamp
4605f821e8 Add custom TextMate grammar for DOT syntax highlighting in docs
Revert the graphviz language identifier back to dot (Shiki doesn't
bundle either) and register a custom TextMate grammar via Mintlify's
styling.codeblocks.languages.custom config. The grammar (extracted from
apps/arc-web/app/data/dot-grammar.ts) highlights keywords, shape names,
attributes, strings, comments, and operators.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 21:41:54 -05:00
Bryan Helmkamp
6a98dcc246 Use graphviz language identifier for DOT code blocks, add titles to workflow examples
Changes ```dot to ```graphviz across all docs for better syntax highlighting
in Mintlify (Shiki). Full digraph blocks get a title derived from the workflow
name (e.g. title="hello.dot").

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 21:26:45 -05:00
Bryan Helmkamp
598b5b7d19 Update docs: fill in administration, agents, execution, and reference pages; remove placeholder pages
Remove stub pages (bring-your-own-key, costs, monitoring, usage, artifacts,
ai-tools, extensions, hooks, llms) and flesh out remaining pages with real
content covering advanced setup, security, permissions, MCP, observability,
interviews, environments, CLI reference, architecture, and workflow stages.
Add permission-flow diagram and tutorials section.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 20:25:23 -05:00
Bryan Helmkamp
5bdb67c51e Document agent backends (API vs CLI)
Add Backends section to agents page explaining the two execution
strategies, expand backend attribute descriptions in dot-language
and stylesheet references, and add API-only notes to tools and
sub-agents pages.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 20:00:21 -05:00
Bryan Helmkamp
3500d1436b Simplify Skills page, link to Agent Skills spec instead of duplicating
Remove the "Skill file format" and "Creating skills" sections which
duplicated content from the Agent Skills specification. Link to
agentskills.io for the format spec and introduction instead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 19:19:29 -05:00
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
ba1f37d57d Add parity tests for follow_up and mid-task steering, expand to all providers
- Add follow_up, steering_before_input, and steering_mid_task parity tests
- Add steering_queue_handle() to Session for test access
- Expand provider_tests! macro to cover all 7 providers (Kimi, Zai, Minimax, Inception)
- Update model names to match current catalog (gpt-5-mini, gemini-3-flash-preview, etc.)
- Fix OpenAI-compatible tool result serialization: emit one ChatMessage per ToolResult
  instead of bundling all results into a single message with only the first tool_call_id.
  This was causing Kimi to reject requests during parallel tool calls.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:44:30 -05:00
Bryan Helmkamp
1d4af91aab Remove root README (arc-llm content already lives in crates/arc-llm/)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:43:52 -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
dc348d553e Extract parse_ast() and use Write sink in parse_command
- Extract shared strip+parse+trailing-check into parser::parse_ast()
  so both parser::parse() and parse_command reuse it
- Accept impl Write in parse_command so tests verify actual JSON output
  instead of re-parsing independently

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:19:34 -05:00
Bryan Helmkamp
57dd00a1a5 Add arc parse FILE.dot subcommand to print raw AST as JSON
Parses a DOT file and outputs its AST as pretty-printed JSON, useful for
debugging and tooling. Adds Serialize/Deserialize to all AST types.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 16:16:04 -05:00
Bryan Helmkamp
872107e4d6 Fix Docker demo build and verifications API response parsing
- Switch mintlify install from bun to npm with katex version patch
- Add arm64 platform and pull_policy: never to docker-compose.demo.yaml
- Unwrap data envelope in verifications loader response
- Add name-gen script

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 12:03:42 -05:00
Bryan Helmkamp
75a6e2f297 Widen MODEL column from 24 to 30 chars in CLI tables
Accommodates longer model names like gemini-3.1-flash-lite-preview
in both `models list` and `models test` output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 10:43:29 -05:00
Bryan Helmkamp
f8d96cb7ae Fix server-side error message leaking to browser in production
error.message was displayed to users in all environments, while
stack traces were correctly gated behind import.meta.env.DEV.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 10:25:07 -05:00
Bryan Helmkamp
41ed815a19 Fix apiStages.map crash by using PaginatedRunStageList type
Three routes (run-overview, run-configuration, run-graph) were typing
the stages API response as RunStage[] but the endpoint returns a
paginated wrapper { data, meta }. Destructure .data to get the array.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 10:24:23 -05:00
Bryan Helmkamp
65e3a0bcee Fix pre-existing clippy warnings in arc-workflows
- Replace useless format!() with .to_string() in parse_decision
- Derive Default for HookDecision instead of manual impl
- Use contains_key() instead of get().is_none() in semantic parser

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-05 10:11:44 -05:00