diff --git a/crates/arc-api/src/demo/mod.rs b/crates/arc-api/src/demo/mod.rs index 49f57c36f..7661b58ce 100644 --- a/crates/arc-api/src/demo/mod.rs +++ b/crates/arc-api/src/demo/mod.rs @@ -42,7 +42,7 @@ pub async fn start_run_stub( ) -> Response { ( StatusCode::CREATED, - Json(serde_json::json!({"id": "demo-run-new"})), + Json(serde_json::json!({"id": "demo-run-new", "status": "queued", "created_at": "2026-03-06T14:30:00Z"})), ) .into_response() } @@ -113,7 +113,7 @@ pub async fn steer_run_stub( State(_state): State>, Path(_id): Path, ) -> Response { - (StatusCode::OK, Json(serde_json::json!({"accepted": true}))).into_response() + (StatusCode::ACCEPTED, Json(serde_json::json!({"accepted": true}))).into_response() } pub async fn generate_preview_url_stub( @@ -134,13 +134,14 @@ pub async fn get_run_status( Path(id): Path, ) -> Response { match runs::list_items().into_iter().find(|r| r.id == id) { - Some(_) => ( + Some(item) => ( StatusCode::OK, Json(arc_types::RunStatusResponse { id: id.clone(), status: arc_types::RunStatus::Running, error: None, queue_position: None, + created_at: item.created_at, }), ) .into_response(), @@ -452,7 +453,7 @@ pub async fn trigger_workflow_run_stub( ) -> Response { ( StatusCode::CREATED, - Json(serde_json::json!({"id": "demo-workflow-run"})), + Json(serde_json::json!({"id": "demo-workflow-run", "status": "queued", "created_at": "2026-03-06T14:30:00Z"})), ) .into_response() } @@ -597,7 +598,7 @@ pub async fn save_query_stub( ) -> Response { ( StatusCode::CREATED, - Json(serde_json::json!({"id": "new-q", "name": "New Query", "sql": "SELECT 1"})), + Json(serde_json::json!({"id": "new-q", "name": "New Query", "sql": "SELECT 1", "created_at": "2026-03-06T16:00:00Z"})), ) .into_response() } @@ -609,7 +610,7 @@ pub async fn update_query_stub( ) -> Response { ( StatusCode::OK, - Json(serde_json::json!({"id": "1", "name": "Updated", "sql": "SELECT 1"})), + Json(serde_json::json!({"id": "1", "name": "Updated", "sql": "SELECT 1", "created_at": "2026-03-01T10:00:00Z", "updated_at": "2026-03-06T16:00:00Z"})), ) .into_response() } @@ -687,6 +688,11 @@ pub async fn get_aggregate_usage( mod runs { use arc_types::*; + use chrono::{DateTime, Utc}; + + fn ts(s: &str) -> DateTime { + s.parse().unwrap() + } pub fn list_items() -> Vec { vec![ @@ -706,6 +712,7 @@ mod runs { comments: Some(0), question: None, sandbox_id: Some("sb-a1b2c3d4".into()), + created_at: ts("2026-03-06T14:30:00Z"), }, RunListItem { id: "run-2".into(), @@ -723,6 +730,7 @@ mod runs { comments: Some(0), question: None, sandbox_id: Some("sb-e5f6g7h8".into()), + created_at: ts("2026-03-06T12:00:00Z"), }, RunListItem { id: "run-3".into(), @@ -740,6 +748,7 @@ mod runs { comments: Some(0), question: None, sandbox_id: Some("sb-i9j0k1l2".into()), + created_at: ts("2026-03-05T09:20:00Z"), }, RunListItem { id: "run-4".into(), @@ -757,6 +766,7 @@ mod runs { comments: Some(0), question: Some("Accept or push for another round?".into()), sandbox_id: Some("sb-q7r8s9t0".into()), + created_at: ts("2026-03-04T15:00:00Z"), }, RunListItem { id: "run-5".into(), @@ -774,6 +784,7 @@ mod runs { comments: Some(0), question: Some("Proceed from investigation to fix?".into()), sandbox_id: Some("sb-u1v2w3x4".into()), + created_at: ts("2026-03-04T10:00:00Z"), }, RunListItem { id: "run-6".into(), @@ -827,6 +838,7 @@ mod runs { comments: Some(4), question: None, sandbox_id: Some("sb-m3n4o5p6".into()), + created_at: ts("2026-03-03T16:45:00Z"), }, RunListItem { id: "run-7".into(), @@ -870,6 +882,7 @@ mod runs { comments: Some(1), question: None, sandbox_id: Some("sb-y5z6a7b8".into()), + created_at: ts("2026-03-03T11:00:00Z"), }, RunListItem { id: "run-8".into(), @@ -948,6 +961,7 @@ mod runs { comments: Some(7), question: None, sandbox_id: Some("sb-c9d0e1f2".into()), + created_at: ts("2026-02-28T14:00:00Z"), }, RunListItem { id: "run-9".into(), @@ -996,6 +1010,7 @@ mod runs { comments: Some(2), question: None, sandbox_id: Some("sb-g3h4i5j6".into()), + created_at: ts("2026-02-27T09:00:00Z"), }, RunListItem { id: "run-10".into(), @@ -1034,6 +1049,7 @@ mod runs { comments: Some(0), question: None, sandbox_id: Some("sb-k7l8m9n0".into()), + created_at: ts("2026-02-26T08:00:00Z"), }, ] } @@ -1073,16 +1089,16 @@ mod runs { pub fn turns() -> Vec { vec![ - StageTurn { kind: StageTurnKind::System, content: Some("You are a drift detection agent. Compare the production and staging environments and identify any configuration or code drift.".into()), tools: vec![] }, - StageTurn { kind: StageTurnKind::Assistant, content: Some("I'll start by loading the environment configurations for both production and staging to compare them.".into()), tools: vec![] }, - StageTurn { - kind: StageTurnKind::Tool, content: None, + StageTurn::SystemStageTurn(SystemStageTurn { kind: SystemStageTurnKind::System, content: "You are a drift detection agent. Compare the production and staging environments and identify any configuration or code drift.".into(), tools: vec![] }), + StageTurn::AssistantStageTurn(AssistantStageTurn { kind: AssistantStageTurnKind::Assistant, content: "I'll start by loading the environment configurations for both production and staging to compare them.".into(), tools: vec![] }), + StageTurn::ToolStageTurn(ToolStageTurn { + kind: ToolStageTurnKind::Tool, content: None, tools: vec![ ToolUse { id: "toolu_01".into(), tool_name: "read_file".into(), input: r#"{ "path": "environments/production/config.toml" }"#.into(), result: "[redis]\nhost = \"redis-prod.internal\"\nport = 6379".into(), is_error: false, duration_ms: Some(45) }, ToolUse { id: "toolu_02".into(), tool_name: "read_file".into(), input: r#"{ "path": "environments/staging/config.toml" }"#.into(), result: "[redis]\nhost = \"redis-staging.internal\"\nport = 6379".into(), is_error: false, duration_ms: Some(38) }, ], - }, - StageTurn { kind: StageTurnKind::Assistant, content: Some("I've detected drift in 3 resources between production and staging:\n\n1. **redis.max_connections** — production has 200, staging has 100\n2. **redis.tls** — enabled in production, disabled in staging\n3. **iam.session_duration** — production uses 3600s, staging uses 1800s".into()), tools: vec![] }, + }), + StageTurn::AssistantStageTurn(AssistantStageTurn { kind: AssistantStageTurnKind::Assistant, content: "I've detected drift in 3 resources between production and staging:\n\n1. **redis.max_connections** — production has 200, staging has 100\n2. **redis.tls** — enabled in production, disabled in staging\n3. **iam.session_duration** — production uses 3600s, staging uses 1800s".into(), tools: vec![] }), ] } @@ -2295,6 +2311,11 @@ mod verifications { mod retros { use arc_types::*; + use chrono::{DateTime, Utc}; + + fn ts(s: &str) -> DateTime { + s.parse().unwrap() + } pub fn list_items() -> Vec { vec![ @@ -2302,7 +2323,7 @@ mod retros { run_id: "run-1".into(), workflow_name: "implement".into(), goal: "Add rate limiting to auth endpoints".into(), - timestamp: "2026-02-28T14:32:00Z".into(), + timestamp: ts("2026-02-28T14:32:00Z"), smoothness: Some(SmoothnessRating::Smooth), stats: RetroStats { total_duration_ms: 389000, @@ -2323,7 +2344,7 @@ mod retros { run_id: "run-2".into(), workflow_name: "implement".into(), goal: "Migrate to React Router v7".into(), - timestamp: "2026-02-28T10:15:00Z".into(), + timestamp: ts("2026-02-28T10:15:00Z"), smoothness: Some(SmoothnessRating::Bumpy), stats: RetroStats { total_duration_ms: 975000, @@ -2347,7 +2368,7 @@ mod retros { run_id: "run-6".into(), workflow_name: "implement".into(), goal: "Add dark mode toggle".into(), - timestamp: "2026-02-27T16:45:00Z".into(), + timestamp: ts("2026-02-27T16:45:00Z"), smoothness: Some(SmoothnessRating::Effortless), stats: RetroStats { total_duration_ms: 216000, @@ -2367,7 +2388,7 @@ mod retros { run_id: "run-3".into(), workflow_name: "fix_build".into(), goal: "Fix config parsing for nested values".into(), - timestamp: "2026-02-27T09:20:00Z".into(), + timestamp: ts("2026-02-27T09:20:00Z"), smoothness: Some(SmoothnessRating::Struggled), stats: RetroStats { total_duration_ms: 830000, @@ -2388,7 +2409,7 @@ mod retros { run_id: "run-8".into(), workflow_name: "implement".into(), goal: "Implement webhook retry logic".into(), - timestamp: "2026-02-26T11:00:00Z".into(), + timestamp: ts("2026-02-26T11:00:00Z"), smoothness: Some(SmoothnessRating::Smooth), stats: RetroStats { total_duration_ms: 440000, @@ -2557,12 +2578,17 @@ mod sessions { mod insights { use arc_types::*; + use chrono::{DateTime, Utc}; + + fn ts(s: &str) -> DateTime { + s.parse().unwrap() + } pub fn saved_queries() -> Vec { vec![ - SavedQuery { id: "1".into(), name: "Run duration by workflow".into(), sql: "SELECT workflow_name, AVG(duration_seconds) as avg_duration,\n COUNT(*) as run_count\nFROM runs\nGROUP BY workflow_name\nORDER BY avg_duration DESC\nLIMIT 20".into() }, - SavedQuery { id: "2".into(), name: "Daily failure rate".into(), sql: "SELECT date_trunc('day', created_at) as day,\n COUNT(*) FILTER (WHERE status = 'failed') as failures,\n COUNT(*) as total\nFROM runs\nGROUP BY 1\nORDER BY 1 DESC\nLIMIT 30".into() }, - SavedQuery { id: "3".into(), name: "Top repos by activity".into(), sql: "SELECT repo, COUNT(*) as runs\nFROM runs\nGROUP BY repo\nORDER BY runs DESC".into() }, + SavedQuery { id: "1".into(), name: "Run duration by workflow".into(), sql: "SELECT workflow_name, AVG(duration_seconds) as avg_duration,\n COUNT(*) as run_count\nFROM runs\nGROUP BY workflow_name\nORDER BY avg_duration DESC\nLIMIT 20".into(), created_at: ts("2026-03-01T10:00:00Z"), updated_at: Some(ts("2026-03-05T14:30:00Z")) }, + SavedQuery { id: "2".into(), name: "Daily failure rate".into(), sql: "SELECT date_trunc('day', created_at) as day,\n COUNT(*) FILTER (WHERE status = 'failed') as failures,\n COUNT(*) as total\nFROM runs\nGROUP BY 1\nORDER BY 1 DESC\nLIMIT 30".into(), created_at: ts("2026-03-02T09:00:00Z"), updated_at: None }, + SavedQuery { id: "3".into(), name: "Top repos by activity".into(), sql: "SELECT repo, COUNT(*) as runs\nFROM runs\nGROUP BY repo\nORDER BY runs DESC".into(), created_at: ts("2026-03-03T11:00:00Z"), updated_at: None }, ] } diff --git a/crates/arc-api/src/server.rs b/crates/arc-api/src/server.rs index c5596a9da..bfd4aa066 100644 --- a/crates/arc-api/src/server.rs +++ b/crates/arc-api/src/server.rs @@ -67,7 +67,7 @@ struct ManagedRun { graph: arc_workflows::graph::Graph, status: RunStatus, error: Option, - created_at: std::time::Instant, + created_at: chrono::DateTime, // Populated when running: interviewer: Option>, event_tx: Option>, @@ -379,6 +379,7 @@ async fn list_runs( status: managed_run.status, error: managed_run.error.clone(), queue_position: queue_positions.get(id).copied(), + created_at: managed_run.created_at, }) .collect(); let page: Vec<_> = all_items.into_iter().skip(offset).take(limit + 1).collect(); @@ -432,7 +433,7 @@ async fn start_run( graph, status: RunStatus::Queued, error: None, - created_at: std::time::Instant::now(), + created_at: chrono::Utc::now(), interviewer: None, event_tx: None, context: None, @@ -446,7 +447,15 @@ async fn start_run( state.scheduler_notify.notify_one(); - (StatusCode::CREATED, Json(StartRunResponse { id: run_id })).into_response() + ( + StatusCode::CREATED, + Json(StartRunResponse { + id: run_id, + status: RunStatus::Queued, + created_at: chrono::Utc::now(), + }), + ) + .into_response() } /// Execute a single run: transitions queued → starting → running → completed/failed/cancelled. @@ -678,6 +687,7 @@ async fn get_run_status( id: id.clone(), status: managed_run.status, error: managed_run.error.clone(), + created_at: managed_run.created_at, queue_position, }), ) diff --git a/docs/api-reference/arc-api.yaml b/docs/api-reference/arc-api.yaml index cca110f35..dc0fc699e 100644 --- a/docs/api-reference/arc-api.yaml +++ b/docs/api-reference/arc-api.yaml @@ -59,6 +59,7 @@ paths: operationId: getHealth tags: [Discovery] summary: Health Check + description: Returns service health status. Used by load balancers and monitoring. security: [] responses: "200": @@ -110,6 +111,7 @@ paths: operationId: listRuns tags: [Runs] summary: List Runs + description: Returns a paginated list of runs for the board view, ordered by recency. parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -124,6 +126,7 @@ paths: operationId: startRun tags: [Runs] summary: Start Run + description: Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler. requestBody: required: true content: @@ -149,6 +152,7 @@ paths: operationId: retrieveRun tags: [Runs] summary: Retrieve Run + description: Returns the current status of a run, including error details and queue position if applicable. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -170,6 +174,7 @@ paths: operationId: cancelRun tags: [Runs] summary: Cancel Run + description: Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -178,12 +183,7 @@ paths: content: application/json: schema: - type: object - properties: - cancelled: - type: boolean - required: - - cancelled + $ref: "#/components/schemas/CancelRunResponse" "404": description: Run not found content: @@ -202,6 +202,7 @@ paths: operationId: retrieveRunSvg tags: [Runs] summary: Render SVG + description: Renders the workflow graph as an SVG image using Graphviz. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -229,6 +230,7 @@ paths: operationId: retrieveRunCheckpoint tags: [Run Internals] summary: Retrieve Run Checkpoint + description: Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -249,6 +251,7 @@ paths: operationId: retrieveRunContext tags: [Run Internals] summary: Retrieve Run Context + description: Returns the key-value context map accumulated during the run. Empty if the run has not started. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -270,6 +273,7 @@ paths: operationId: streamRunEvents tags: [Runs] summary: Stream Run Events + description: Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -297,6 +301,7 @@ paths: operationId: listRunQuestions tags: [Human-in-the-Loop] summary: List Run Questions + description: Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -318,13 +323,10 @@ paths: operationId: submitRunAnswer tags: [Human-in-the-Loop] summary: Submit Run Answer + description: Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type. parameters: - $ref: "#/components/parameters/RunId" - - name: qid - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/QuestionId" requestBody: required: true content: @@ -356,6 +358,7 @@ paths: operationId: retrieveRetro tags: [Retros] summary: Retrieve Retro + description: Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -376,6 +379,7 @@ paths: operationId: listRunStages tags: [Run Internals] summary: List Run Stages + description: Returns the ordered list of stages in a run's workflow graph with their current status and timing. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -397,13 +401,10 @@ paths: operationId: listStageTurns tags: [Run Internals] summary: List Stage Turns + description: Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations. parameters: - $ref: "#/components/parameters/RunId" - - name: stageId - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/StageId" - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" responses: @@ -425,13 +426,10 @@ paths: operationId: listRunCompare tags: [Run Outputs] summary: List Run Compare + description: Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint. parameters: - $ref: "#/components/parameters/RunId" - - name: checkpoint - in: query - schema: - type: string - default: "all" + - $ref: "#/components/parameters/CheckpointFilter" responses: "200": description: File changes with checkpoint metadata @@ -451,6 +449,7 @@ paths: operationId: retrieveRunUsage tags: [Run Outputs] summary: Retrieve Run Usage + description: Returns token and cost usage broken down by stage and model for a specific run. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -472,6 +471,7 @@ paths: operationId: listRunVerifications tags: [Run Outputs] summary: List Run Verifications + description: Returns verification results for a run, organized by category with individual control statuses. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -493,6 +493,7 @@ paths: operationId: retrieveRunConfiguration tags: [Run Internals] summary: Retrieve Run Configuration + description: Returns the TOML configuration file content used to launch this run. parameters: - $ref: "#/components/parameters/RunId" responses: @@ -514,6 +515,7 @@ paths: operationId: steerRun tags: [Human-in-the-Loop] summary: Steer Run + description: Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously. parameters: - $ref: "#/components/parameters/RunId" requestBody: @@ -523,17 +525,12 @@ paths: schema: $ref: "#/components/schemas/SteerRequest" responses: - "200": - description: Steering accepted + "202": + description: Steering accepted for processing content: application/json: schema: - type: object - properties: - accepted: - type: boolean - required: - - accepted + $ref: "#/components/schemas/SteerRunResponse" "404": description: Run not found content: @@ -546,6 +543,7 @@ paths: operationId: generatePreviewUrl tags: [Human-in-the-Loop] summary: Preview URL + description: Generates a time-limited preview URL for a port exposed by the run's sandbox environment. parameters: - $ref: "#/components/parameters/RunId" requestBody: @@ -575,6 +573,7 @@ paths: operationId: listWorkflows tags: [Workflows] summary: List Workflows + description: Returns a paginated list of workflow definitions available for execution. parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -591,12 +590,9 @@ paths: operationId: retrieveWorkflow tags: [Workflows] summary: Retrieve Workflow + description: Returns the full detail of a workflow including its DOT graph, TOML config, and description. parameters: - - name: name - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/WorkflowName" responses: "200": description: Workflow detail @@ -616,12 +612,9 @@ paths: operationId: listWorkflowRuns tags: [Workflows] summary: List Workflow Runs + description: Returns a paginated list of runs filtered to a specific workflow. parameters: - - name: name - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/WorkflowName" - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" responses: @@ -641,12 +634,9 @@ paths: operationId: startWorkflowRun tags: [Workflows] summary: Start Workflow Run + description: Queues a new run of the specified workflow using its stored DOT graph. parameters: - - name: name - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/WorkflowName" responses: "201": description: Run created @@ -668,6 +658,7 @@ paths: operationId: listVerifications tags: [Verifications] summary: List Verifications + description: Returns all verification categories with their controls and performance metrics. responses: "200": description: Array of verification categories @@ -681,12 +672,9 @@ paths: operationId: retrieveVerification tags: [Verifications] summary: Retrieve Verification + description: Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category. parameters: - - name: slug - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/VerificationSlug" responses: "200": description: Verification control detail @@ -708,6 +696,7 @@ paths: operationId: listRetros tags: [Retros] summary: List Retros + description: Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics. parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -858,6 +847,7 @@ paths: operationId: listSavedQueries tags: [Insights] summary: List Saved Queries + description: Returns a paginated list of saved SQL queries for the insights editor. parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -872,6 +862,7 @@ paths: operationId: createSavedQuery tags: [Insights] summary: Create Saved Query + description: Saves a new named SQL query for later reuse. requestBody: required: true content: @@ -891,12 +882,9 @@ paths: operationId: updateSavedQuery tags: [Insights] summary: Update Saved Query + description: Replaces the name and SQL of an existing saved query. parameters: - - name: id - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/InsightQueryId" requestBody: required: true content: @@ -920,12 +908,9 @@ paths: operationId: deleteSavedQuery tags: [Insights] summary: Delete Saved Query + description: Permanently removes a saved query. parameters: - - name: id - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/InsightQueryId" responses: "204": description: Query deleted @@ -941,6 +926,7 @@ paths: operationId: executeQuery tags: [Insights] summary: Execute Query + description: Executes an ad-hoc SQL query against the analytics database and returns columnar results. requestBody: required: true content: @@ -960,6 +946,7 @@ paths: operationId: listQueryHistory tags: [Insights] summary: List Query History + description: Returns a paginated history of recently executed queries with timing and row counts. parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -994,6 +981,7 @@ paths: operationId: retrieveServerSettings tags: [Settings] summary: Retrieve Server Settings + description: Returns all server settings organized into groups. Each group contains fields with their current values and input types. responses: "200": description: Array of setting groups @@ -1011,6 +999,7 @@ paths: operationId: listProjects tags: [Projects] summary: List Projects + description: Returns a paginated list of registered projects (repositories). parameters: - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" @@ -1027,12 +1016,9 @@ paths: operationId: listBranches tags: [Projects] summary: List Branches + description: Returns a paginated list of branches for a specific project. parameters: - - name: id - in: path - required: true - schema: - type: string + - $ref: "#/components/parameters/ProjectId" - $ref: "#/components/parameters/PageLimit" - $ref: "#/components/parameters/PageOffset" responses: @@ -1075,8 +1061,10 @@ components: name: id in: path required: true + description: Unique run identifier (ULID). schema: type: string + example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z SessionId: name: id @@ -1088,35 +1076,109 @@ components: format: uuid example: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + StageId: + name: stageId + in: path + required: true + description: Identifier of a stage within a run's workflow graph. + schema: + type: string + example: propose-changes + + QuestionId: + name: qid + in: path + required: true + description: Unique identifier of a pending question. + schema: + type: string + example: q-001 + + WorkflowName: + name: name + in: path + required: true + description: URL-safe slug identifying a workflow definition. + schema: + type: string + example: fix_build + + VerificationSlug: + name: slug + in: path + required: true + description: URL-safe slug identifying a verification control. + schema: + type: string + example: motivation + + InsightQueryId: + name: id + in: path + required: true + description: Unique identifier of a saved query. + schema: + type: string + example: "1" + + ProjectId: + name: id + in: path + required: true + description: Unique identifier of a project (repository). + schema: + type: string + example: arc-web + + CheckpointFilter: + name: checkpoint + in: query + required: false + description: Filter file diffs to a specific checkpoint. Defaults to all changes. + schema: + type: string + default: "all" + example: cp-3 + PageLimit: name: page[limit] in: query required: false + description: Maximum number of items to return per page. schema: type: integer minimum: 1 maximum: 100 default: 20 + example: 20 PageOffset: name: page[offset] in: query required: false + description: Number of items to skip before returning results. schema: type: integer minimum: 0 default: 0 + example: 0 schemas: + # ── Pagination ─────────────────────────────────────────────────────── + PaginationMeta: + description: Pagination metadata included in every paginated response. type: object required: - has_more properties: has_more: type: boolean + description: Whether additional pages of results are available. + example: true PaginatedRunList: + description: Paginated list of runs. type: object required: - data @@ -1130,6 +1192,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedWorkflowList: + description: Paginated list of workflows. type: object required: - data @@ -1143,6 +1206,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedRetroList: + description: Paginated list of run retrospectives. type: object required: - data @@ -1156,6 +1220,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedSessionList: + description: Paginated list of sessions. type: object required: - data @@ -1169,6 +1234,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedProjectList: + description: Paginated list of projects. type: object required: - data @@ -1182,6 +1248,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedBranchList: + description: Paginated list of branches. type: object required: - data @@ -1195,6 +1262,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedSavedQueryList: + description: Paginated list of saved queries. type: object required: - data @@ -1208,6 +1276,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedHistoryEntryList: + description: Paginated list of query history entries. type: object required: - data @@ -1221,6 +1290,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedStageTurnList: + description: Paginated list of stage turns. type: object required: - data @@ -1234,6 +1304,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedApiQuestionList: + description: Paginated list of pending questions. type: object required: - data @@ -1247,6 +1318,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedRunStageList: + description: Paginated list of run stages. type: object required: - data @@ -1260,6 +1332,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedRunVerificationList: + description: Paginated list of run verification categories. type: object required: - data @@ -1273,6 +1346,7 @@ components: $ref: "#/components/schemas/PaginationMeta" PaginatedVerificationCategoryList: + description: Paginated list of verification categories. type: object required: - data @@ -1285,9 +1359,10 @@ components: meta: $ref: "#/components/schemas/PaginationMeta" - # ── Existing Run Schemas ──────────────────────────────────────────── + # ── Run Schemas ────────────────────────────────────────────────────── RunStatus: + description: Lifecycle status of a run. type: string enum: - queued @@ -1298,37 +1373,88 @@ components: - cancelled StartRunRequest: + description: Request body for starting a new run from a DOT graph source. type: object required: - dot_source properties: dot_source: type: string + description: DOT language source defining the workflow graph. + example: 'digraph { start [shape=Mdiamond]; exit [shape=Msquare]; start -> exit }' StartRunResponse: - type: object - required: - - id - properties: - id: - type: string - - RunStatusResponse: + description: Response returned after successfully queuing a new run. type: object required: - id - status + - created_at properties: id: type: string + description: Unique run identifier (ULID). + example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z + status: + $ref: "#/components/schemas/RunStatus" + created_at: + type: string + format: date-time + description: Timestamp when the run was created. + example: "2026-03-06T14:30:00Z" + + RunStatusResponse: + description: Current status of a run with optional error and queue position. + type: object + required: + - id + - status + - created_at + properties: + id: + type: string + description: Unique run identifier (ULID). + example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z status: $ref: "#/components/schemas/RunStatus" error: type: string + description: Error message if the run failed. + example: "Stage 'apply-changes' exceeded maximum retries." queue_position: type: integer + description: Position in the queue (1-based). Only present when status is `queued`. + example: 3 + created_at: + type: string + format: date-time + description: Timestamp when the run was created. + example: "2026-03-06T14:30:00Z" + + CancelRunResponse: + description: Response returned after cancelling a run. + type: object + required: + - cancelled + properties: + cancelled: + type: boolean + description: Whether the cancellation was successful. + example: true + + SteerRunResponse: + description: Acknowledgement that the steering guidance was accepted for delivery. + type: object + required: + - accepted + properties: + accepted: + type: boolean + description: Whether the steering guidance was accepted. + example: true ApiQuestionOption: + description: A selectable option for a multiple-choice or multi-select question. type: object required: - key @@ -1336,10 +1462,15 @@ components: properties: key: type: string + description: Machine-readable option key used when submitting an answer. + example: option_a label: type: string + description: Human-readable label displayed to the user. + example: Accept changes ApiQuestion: + description: A pending human-in-the-loop question generated by a workflow stage. type: object required: - id @@ -1350,18 +1481,26 @@ components: properties: id: type: string + description: Unique question identifier. + example: q-001 text: type: string + description: The question text displayed to the user. + example: Should we proceed with the proposed changes? question_type: $ref: "#/components/schemas/QuestionType" options: type: array + description: Available options for selection-based questions. Empty for freeform questions. items: $ref: "#/components/schemas/ApiQuestionOption" allow_freeform: type: boolean + description: Whether the user may provide freeform text in addition to selecting options. + example: true QuestionType: + description: The interaction type of a human-in-the-loop question. type: string enum: - yes_no @@ -1371,24 +1510,33 @@ components: - confirmation SubmitAnswerRequest: + description: Request body for submitting an answer to a pending question. type: object required: - value properties: value: type: string + description: Freeform answer text. + example: "Yes, proceed with the changes." selected_option_key: type: string + description: Key of the selected option (for multiple-choice questions). + example: option_a SubmitAnswerResponse: + description: Response indicating whether the submitted answer was accepted. type: object required: - accepted properties: accepted: type: boolean + description: Whether the answer was accepted. Returns false if the question no longer exists. + example: true ErrorResponseEntry: + description: A single error entry in an error response. type: object required: - status @@ -1397,24 +1545,33 @@ components: properties: status: type: string + description: HTTP status code as a string. + example: "404" title: type: string + description: Short error classification. + example: Not Found detail: type: string + description: Human-readable error description. + example: Run not found. ErrorResponse: + description: Standard error response containing one or more error entries. type: object required: - errors properties: errors: type: array + description: List of error entries. items: $ref: "#/components/schemas/ErrorResponseEntry" - # ── New Run Schemas ───────────────────────────────────────────────── + # ── Run Board Schemas ──────────────────────────────────────────────── RunListItemStatus: + description: Board column status for a run in the list view. type: string enum: - working @@ -1423,6 +1580,7 @@ components: - merge CheckRunStatus: + description: Status of a CI check run. type: string enum: - success @@ -1432,6 +1590,7 @@ components: - queued CheckRun: + description: A CI check run result associated with a run's pull request. type: object required: - name @@ -1439,12 +1598,17 @@ components: properties: name: type: string + description: Name of the CI check. + example: unit-tests status: $ref: "#/components/schemas/CheckRunStatus" duration_secs: type: number + description: Duration of the check run in seconds. + example: 154.0 RunListItem: + description: Summary of a run shown in the board view. type: object required: - id @@ -1452,41 +1616,77 @@ components: - title - workflow - status + - created_at properties: id: type: string + description: Unique run identifier (ULID). + example: 01JNQVR7M0EJ5GKAT2SC4ERS1Z repo: type: string + description: Repository name. + example: api-server title: type: string + description: Human-readable title describing the run's goal. + example: Add rate limiting to auth endpoints workflow: type: string + description: Slug of the workflow that produced this run. + example: implement status: $ref: "#/components/schemas/RunListItemStatus" number: type: integer + description: Pull request number, if the run has opened a PR. + example: 889 additions: type: integer + description: Lines added in the run's diff. + example: 234 deletions: type: integer + description: Lines deleted in the run's diff. + example: 67 checks: type: array + description: CI check run results for the run's PR. items: $ref: "#/components/schemas/CheckRun" elapsed_secs: type: number + description: Wall-clock time elapsed since the run started, in seconds. + example: 420.0 elapsed_warning: type: boolean + description: Whether the elapsed time exceeds the expected threshold. + example: false resources: type: string + description: Compute resources allocated to the run. + example: 4 CPU / 8 GB comments: type: integer + description: Number of review comments on the run's PR. + example: 4 question: type: string + description: Text of a pending human-in-the-loop question, if any. + example: Accept or push for another round? sandbox_id: type: string + description: Identifier of the sandbox environment running this run. + example: sb-a1b2c3d4 + created_at: + type: string + format: date-time + description: Timestamp when the run was created. + example: "2026-03-06T14:30:00Z" + + # ── Stage / Turn Schemas ───────────────────────────────────────────── StageStatus: + description: Execution status of a workflow stage. type: string enum: - completed @@ -1495,6 +1695,7 @@ components: - failed RunStage: + description: A single stage in a run's workflow graph. type: object required: - id @@ -1503,14 +1704,22 @@ components: properties: id: type: string + description: Unique stage identifier within the run. + example: propose-changes name: type: string + description: Human-readable stage name. + example: Propose Changes status: $ref: "#/components/schemas/StageStatus" duration_secs: type: number + description: Time spent in this stage, in seconds. + example: 154.0 dot_id: type: string + description: Node identifier in the DOT graph source. + example: propose ToolUse: description: A single tool invocation with its input, result, and execution metadata. @@ -1548,24 +1757,81 @@ components: example: 142 StageTurn: + description: A single turn in a stage conversation — a system prompt, assistant response, or tool invocation block. + discriminator: + propertyName: kind + mapping: + system: "#/components/schemas/SystemStageTurn" + assistant: "#/components/schemas/AssistantStageTurn" + tool: "#/components/schemas/ToolStageTurn" + oneOf: + - $ref: "#/components/schemas/SystemStageTurn" + - $ref: "#/components/schemas/AssistantStageTurn" + - $ref: "#/components/schemas/ToolStageTurn" + + SystemStageTurn: + description: A system prompt turn that sets the stage's instructions. type: object required: - kind + - content properties: kind: type: string - enum: - - system - - assistant - - tool + enum: [system] content: type: string + description: System prompt text. + example: You are a drift detection agent. Compare the production and staging environments. tools: type: array + description: Tool invocations (always empty for system turns). items: $ref: "#/components/schemas/ToolUse" + AssistantStageTurn: + description: An assistant response turn within a stage. + type: object + required: + - kind + - content + properties: + kind: + type: string + enum: [assistant] + content: + type: string + description: Assistant response text. + example: I'll start by loading the environment configurations for both production and staging. + tools: + type: array + description: Tool invocations (always empty for assistant turns). + items: + $ref: "#/components/schemas/ToolUse" + + ToolStageTurn: + description: A tool invocation turn containing one or more tool calls. + type: object + required: + - kind + - tools + properties: + kind: + type: string + enum: [tool] + content: + type: string + description: Optional text content (usually null for tool turns). + tools: + type: array + description: Tool invocations executed in this turn. + items: + $ref: "#/components/schemas/ToolUse" + + # ── Compare / Diff Schemas ─────────────────────────────────────────── + FileCheckpoint: + description: A named checkpoint within a run, used to filter file diffs. type: object required: - id @@ -1573,10 +1839,15 @@ components: properties: id: type: string + description: Checkpoint identifier. + example: cp-3 label: type: string + description: Human-readable label for the checkpoint. + example: "Checkpoint 3 — Review Changes" DiffFile: + description: A file's contents at one side of a diff. type: object required: - name @@ -1584,10 +1855,15 @@ components: properties: name: type: string + description: File path relative to the repository root. + example: src/commands/run.ts contents: type: string + description: Full file contents. Empty string for newly created or deleted files. + example: 'import { parseArgs } from "node:util";' FileDiff: + description: A before/after pair showing changes to a single file. type: object required: - old_file @@ -1599,6 +1875,7 @@ components: $ref: "#/components/schemas/DiffFile" DiffStats: + description: Aggregate line-change statistics for a diff. type: object required: - additions @@ -1606,10 +1883,15 @@ components: properties: additions: type: integer + description: Total lines added. + example: 567 deletions: type: integer + description: Total lines deleted. + example: 234 RunCompare: + description: File-level diff output for a run, with checkpoint filtering support. type: object required: - checkpoints @@ -1618,16 +1900,21 @@ components: properties: checkpoints: type: array + description: Available checkpoints for filtering. items: $ref: "#/components/schemas/FileCheckpoint" files: type: array + description: File diffs, optionally filtered by checkpoint. items: $ref: "#/components/schemas/FileDiff" stats: $ref: "#/components/schemas/DiffStats" + # ── Usage Schemas ──────────────────────────────────────────────────── + UsageStage: + description: Token and cost usage for a single stage within a run. type: object required: - stage @@ -1639,18 +1926,31 @@ components: properties: stage: type: string + description: Human-readable stage name. + example: Propose Changes model: type: string + description: Model slug used for this stage. + example: claude-opus-4-6 input_tokens: type: integer + description: Number of input tokens consumed. + example: 28640 output_tokens: type: integer + description: Number of output tokens generated. + example: 8750 runtime_secs: type: number + description: Wall-clock runtime in seconds. + example: 154.0 cost: type: number + description: Cost in USD for this stage. + example: 0.72 UsageTotals: + description: Aggregate usage totals across all stages of a run. type: object required: - runtime_secs @@ -1660,14 +1960,23 @@ components: properties: runtime_secs: type: number + description: Total wall-clock runtime in seconds. + example: 389.0 input_tokens: type: integer + description: Total input tokens consumed. + example: 71540 output_tokens: type: integer + description: Total output tokens generated. + example: 21080 cost: type: number + description: Total cost in USD. + example: 2.26 UsageByModel: + description: Usage statistics grouped by model. type: object required: - model @@ -1678,16 +1987,27 @@ components: properties: model: type: string + description: Model slug. + example: claude-opus-4-6 stages: type: integer + description: Number of stages that used this model. + example: 2 input_tokens: type: integer + description: Total input tokens for this model. + example: 33780 output_tokens: type: integer + description: Total output tokens for this model. + example: 9690 cost: type: number + description: Total cost in USD for this model. + example: 1.35 RunUsage: + description: Complete usage breakdown for a single run. type: object required: - stages @@ -1696,16 +2016,19 @@ components: properties: stages: type: array + description: Per-stage usage breakdown. items: $ref: "#/components/schemas/UsageStage" totals: $ref: "#/components/schemas/UsageTotals" by_model: type: array + description: Usage grouped by model. items: $ref: "#/components/schemas/UsageByModel" AggregateUsage: + description: Aggregate token and cost usage across all runs since server start. type: object required: - total_runs @@ -1717,20 +2040,34 @@ components: properties: total_runs: type: integer + description: Total number of completed runs. + example: 9 total_input_tokens: type: integer + description: Total input tokens across all runs. + example: 643860 total_output_tokens: type: integer + description: Total output tokens across all runs. + example: 189720 total_cost: type: number + description: Total cost in USD across all runs. + example: 20.34 total_runtime_secs: type: number + description: Total wall-clock runtime in seconds. + example: 3501.0 by_model: type: array + description: Usage grouped by model. items: $ref: "#/components/schemas/UsageByModel" + # ── Verification Schemas ───────────────────────────────────────────── + VerificationStatus: + description: Result status of a verification control evaluation. type: string enum: - pass @@ -1738,6 +2075,7 @@ components: - na VerificationType: + description: The evaluation method used by a verification control. type: string enum: - ai @@ -1746,6 +2084,7 @@ components: - ai-analysis RunVerificationControl: + description: A verification control result within a run. type: object required: - name @@ -1754,14 +2093,19 @@ components: properties: name: type: string + description: Human-readable control name. + example: Motivation description: type: string + description: Short description of what the control verifies. + example: Origin of proposal identified type: $ref: "#/components/schemas/VerificationType" status: $ref: "#/components/schemas/VerificationStatus" RunVerification: + description: Verification results for a category within a run. type: object required: - name @@ -1771,16 +2115,22 @@ components: properties: name: type: string + description: Category name. + example: Traceability question: type: string + description: The guiding question for this verification category. + example: Do we understand what this change is and why we're making it? status: $ref: "#/components/schemas/VerificationStatus" controls: type: array + description: Individual control results within this category. items: $ref: "#/components/schemas/RunVerificationControl" SteerRequest: + description: Request body for sending inline steering guidance to a running agent. type: object required: - file @@ -1789,12 +2139,19 @@ components: properties: file: type: string + description: File path to target with the guidance. + example: src/middleware/rate-limit.ts line: type: integer + description: Line number in the file to annotate. + example: 42 guidance: type: string + description: Guidance text for the agent. + example: Use a sliding window algorithm instead of fixed window. PreviewUrlRequest: + description: Request body for generating a preview URL from a sandbox port. type: object required: - port @@ -1802,20 +2159,28 @@ components: properties: port: type: integer + description: Port number exposed by the sandbox. + example: 3000 expires_in_secs: type: integer + description: Time-to-live for the preview URL in seconds. + example: 3600 PreviewUrlResponse: + description: Response containing the generated preview URL. type: object required: - url properties: url: type: string + description: Time-limited preview URL. + example: "https://preview.example.com/sb-a1b2c3d4/3000" # ── Workflow Schemas ───────────────────────────────────────────────── WorkflowListItem: + description: Summary of a workflow shown in list views. type: object required: - name @@ -1824,18 +2189,31 @@ components: properties: name: type: string + description: Human-readable workflow name. + example: Fix Build slug: type: string + description: URL-safe slug used in API paths. + example: fix_build filename: type: string + description: DOT graph filename. + example: fix_build.dot last_run: type: string + description: Human-readable relative timestamp of the last run. + example: 2 hours ago schedule: type: string + description: Cron-like schedule expression, if the workflow runs on a schedule. + example: "0 */6 * * *" next_run: type: string + description: Human-readable relative timestamp of the next scheduled run. + example: in 4 hours WorkflowDetail: + description: Full detail of a workflow definition including graph and configuration. type: object required: - title @@ -1847,20 +2225,33 @@ components: properties: title: type: string + description: Human-readable workflow title. + example: Fix Build slug: type: string + description: URL-safe slug used in API paths. + example: fix_build filename: type: string + description: DOT graph filename. + example: fix_build.dot description: type: string + description: Prose description of what the workflow does. + example: Automatically diagnoses and fixes CI build failures. config: type: string + description: TOML configuration content for the workflow. + example: "version = 1\ngoal = \"Fix CI build failures\"" graph: type: string + description: DOT language source defining the workflow graph. + example: "digraph fix_build { rankdir=LR; start -> diagnose -> fix -> validate }" - # ── Verification Schemas ──────────────────────────────────────────── + # ── Verification Detail Schemas ────────────────────────────────────── EvaluationResult: + description: Outcome of a single verification evaluation. type: string enum: - pass @@ -1868,6 +2259,7 @@ components: - skip VerificationMode: + description: Operational mode of a verification control. type: string enum: - active @@ -1875,6 +2267,7 @@ components: - disabled VerificationControl: + description: A verification control within a category, with performance metrics. type: object required: - name @@ -1883,24 +2276,36 @@ components: properties: name: type: string + description: Human-readable control name. + example: Motivation slug: type: string + description: URL-safe slug for API lookups. + example: motivation description: type: string + description: Short description of what the control verifies. + example: Origin of proposal identified type: $ref: "#/components/schemas/VerificationType" mode: $ref: "#/components/schemas/VerificationMode" f1: type: number + description: F1 score of the control's AI evaluator. + example: 0.87 pass_at_1: type: number + description: Pass@1 rate — probability of passing on the first evaluation. + example: 0.82 evaluations: type: array + description: Recent evaluation results (newest first). items: $ref: "#/components/schemas/EvaluationResult" VerificationCategory: + description: A group of related verification controls. type: object required: - name @@ -1909,14 +2314,20 @@ components: properties: name: type: string + description: Category name. + example: Traceability question: type: string + description: Guiding question for the category. + example: Do we understand what this change is and why we're making it? controls: type: array + description: Verification controls in this category. items: $ref: "#/components/schemas/VerificationControl" ControlInfo: + description: Core metadata about a verification control. type: object required: - name @@ -1926,16 +2337,25 @@ components: properties: name: type: string + description: Human-readable control name. + example: Motivation slug: type: string + description: URL-safe slug. + example: motivation description: type: string + description: Short description of what the control verifies. + example: Origin of proposal identified type: $ref: "#/components/schemas/VerificationType" category: type: string + description: Name of the category this control belongs to. + example: Traceability ControlPerformance: + description: Performance metrics for a verification control. type: object required: - mode @@ -1945,14 +2365,20 @@ components: $ref: "#/components/schemas/VerificationMode" f1: type: number + description: F1 score of the control's AI evaluator. + example: 0.87 pass_at_1: type: number + description: Pass@1 rate. + example: 0.82 evaluations: type: array + description: Recent evaluation results (newest first). items: $ref: "#/components/schemas/EvaluationResult" ControlDetail: + description: Detailed information about a verification control including checks and examples. type: object required: - description @@ -1962,16 +2388,25 @@ components: properties: description: type: string + description: Detailed prose description of the control's purpose and rationale. + example: Verifies that every change traces back to a clear origin. checks: type: array + description: Specific checks performed by this control. items: type: string + example: ["PR body explains why the change is needed", "Commit messages reference a ticket"] pass_example: type: string + description: Example scenario where the control passes. + example: PR links to JIRA-1234 and explains the user-facing pain point. fail_example: type: string + description: Example scenario where the control fails. + example: PR description is empty or says only 'fix stuff'. RecentControlResult: + description: Result of a recent verification control evaluation for a specific run. type: object required: - run_id @@ -1982,16 +2417,25 @@ components: properties: run_id: type: string + description: Identifier of the run that was evaluated. + example: run-047 run_title: type: string + description: Title of the evaluated run. + example: "PR #312 — Add OAuth2 PKCE flow" workflow: type: string + description: Workflow that produced the run. + example: code_review result: $ref: "#/components/schemas/VerificationStatus" timestamp: type: string + description: Human-readable relative timestamp of the evaluation. + example: 2h ago SiblingControl: + description: Summary of a sibling verification control in the same category. type: object required: - name @@ -1999,14 +2443,19 @@ components: properties: name: type: string + description: Human-readable control name. + example: Specifications slug: type: string + description: URL-safe slug. + example: specifications type: $ref: "#/components/schemas/VerificationType" mode: $ref: "#/components/schemas/VerificationMode" VerificationDetailResponse: + description: Complete detail view of a verification control with performance, examples, and recent results. type: object required: - control @@ -2023,16 +2472,19 @@ components: $ref: "#/components/schemas/ControlDetail" recent_results: type: array + description: Recent evaluation results across runs. items: $ref: "#/components/schemas/RecentControlResult" siblings: type: array + description: Other controls in the same category. items: $ref: "#/components/schemas/SiblingControl" - # ── Retro Schemas ─────────────────────────────────────────────────── + # ── Retro Schemas ──────────────────────────────────────────────────── SmoothnessRating: + description: Qualitative assessment of how smoothly a run executed. type: string enum: - effortless @@ -2042,6 +2494,7 @@ components: - failed RetroStats: + description: Summary statistics for a run retrospective. type: object required: - total_duration_ms @@ -2052,20 +2505,33 @@ components: properties: total_duration_ms: type: integer + description: Total run duration in milliseconds. + example: 389000 total_cost: type: number + description: Total cost in USD. + example: 2.78 total_retries: type: integer + description: Total number of retries across all stages. + example: 0 files_touched: type: array + description: List of files modified during the run. items: type: string + example: ["src/middleware/rate-limit.ts", "src/routes/auth.ts"] stages_completed: type: integer + description: Number of stages that completed successfully. + example: 4 stages_failed: type: integer + description: Number of stages that failed. + example: 0 RetroListItem: + description: Summary of a run retrospective shown in list views. type: object required: - run_id @@ -2077,20 +2543,31 @@ components: properties: run_id: type: string + description: Identifier of the run this retro belongs to. + example: run-1 workflow_name: type: string + description: Name of the workflow that produced the run. + example: implement goal: type: string + description: The run's goal. + example: Add rate limiting to auth endpoints timestamp: type: string + format: date-time + description: Timestamp when the retro was generated. + example: "2026-02-28T14:32:00Z" smoothness: $ref: "#/components/schemas/SmoothnessRating" stats: $ref: "#/components/schemas/RetroStats" friction_point_count: type: integer + description: Number of friction points identified in the retro. + example: 0 - # ── Session Schemas ───────────────────────────────────────────────── + # ── Session Schemas ────────────────────────────────────────────────── SessionListItem: description: Summary of a session shown in list views. @@ -2320,23 +2797,42 @@ components: description: Whether the message was accepted for processing. example: true - # ── Insights Schemas ──────────────────────────────────────────────── + # ── Insights Schemas ───────────────────────────────────────────────── SavedQuery: + description: A saved SQL query for the insights editor. type: object required: - id - name - sql + - created_at properties: id: type: string + description: Unique query identifier. + example: "1" name: type: string + description: Human-readable query name. + example: Run duration by workflow sql: type: string + description: SQL query text. + example: "SELECT workflow_name, AVG(duration_seconds) FROM runs GROUP BY 1" + created_at: + type: string + format: date-time + description: Timestamp when the query was saved. + example: "2026-03-01T10:00:00Z" + updated_at: + type: string + format: date-time + description: Timestamp when the query was last modified. + example: "2026-03-05T14:30:00Z" SaveQueryRequest: + description: Request body for creating or updating a saved query. type: object required: - name @@ -2344,18 +2840,26 @@ components: properties: name: type: string + description: Human-readable query name. + example: Run duration by workflow sql: type: string + description: SQL query text. + example: "SELECT workflow_name, AVG(duration_seconds) FROM runs GROUP BY 1" ExecuteQueryRequest: + description: Request body for executing an ad-hoc SQL query. type: object required: - sql properties: sql: type: string + description: SQL query to execute. + example: "SELECT workflow_name, COUNT(*) FROM runs GROUP BY 1" ExecuteQueryResponse: + description: Columnar result set from an executed query. type: object required: - columns @@ -2365,19 +2869,27 @@ components: properties: columns: type: array + description: Column names in the result set. items: type: string + example: ["workflow_name", "count"] rows: type: array + description: Result rows, each an array of values matching the column order. items: type: array items: {} elapsed: type: number + description: Query execution time in seconds. + example: 0.342 row_count: type: integer + description: Number of rows returned. + example: 3 HistoryEntry: + description: A previously executed query in the history log. type: object required: - id @@ -2388,18 +2900,29 @@ components: properties: id: type: string + description: Unique history entry identifier. + example: h1 sql: type: string + description: SQL query that was executed. + example: "SELECT workflow_name, COUNT(*) FROM runs GROUP BY 1" timestamp: type: string + description: Human-readable relative timestamp of execution. + example: 2 min ago elapsed: type: number + description: Query execution time in seconds. + example: 0.342 row_count: type: integer + description: Number of rows returned. + example: 6 - # ── Settings Schemas ──────────────────────────────────────────────── + # ── Settings Schemas ───────────────────────────────────────────────── SettingFieldType: + description: Input type for a setting field. type: string enum: - text @@ -2407,6 +2930,7 @@ components: - toggle SettingField: + description: A single configurable setting within a group. type: object required: - key @@ -2416,20 +2940,31 @@ components: properties: key: type: string + description: Machine-readable setting key. + example: org_name label: type: string + description: Human-readable label displayed in the UI. + example: Organization name value: type: string + description: Current value of the setting. + example: Acme Corp type: $ref: "#/components/schemas/SettingFieldType" options: type: array + description: Available options for select-type fields. items: type: string + example: ["America/New_York", "UTC", "Europe/London"] description: type: string + description: Additional help text for the setting. + example: Comma-separated CIDRs. Leave empty to allow all. SettingGroup: + description: A logical group of related settings. type: object required: - id @@ -2439,18 +2974,26 @@ components: properties: id: type: string + description: Machine-readable group identifier. + example: general name: type: string + description: Human-readable group name. + example: General description: type: string + description: Prose description of the settings group. + example: Core platform settings and defaults. fields: type: array + description: Settings within this group. items: $ref: "#/components/schemas/SettingField" - # ── Project Schemas ───────────────────────────────────────────────── + # ── Project Schemas ────────────────────────────────────────────────── Project: + description: A registered project (repository). type: object required: - id @@ -2458,10 +3001,15 @@ components: properties: id: type: string + description: Unique project identifier. + example: arc-web name: type: string + description: Human-readable project name. + example: arc-web Branch: + description: A branch within a project. type: object required: - id @@ -2469,12 +3017,17 @@ components: properties: id: type: string + description: Branch identifier. + example: main name: type: string + description: Branch name. + example: main - # ── Discovery Schemas ────────────────────────────────────────────── + # ── Discovery Schemas ──────────────────────────────────────────────── RootResponseUrls: + description: Collection of API discovery URLs. type: object required: - openapi_url @@ -2483,12 +3036,19 @@ components: properties: openapi_url: type: string + description: URL of the OpenAPI JSON specification. + example: /openapi.json current_user_url: type: string + description: URL of the current user endpoint. + example: /user health_url: type: string + description: URL of the health check endpoint. + example: /health RootResponse: + description: API discovery response with navigation URLs. type: object required: - urls @@ -2497,17 +3057,23 @@ components: $ref: "#/components/schemas/RootResponseUrls" HealthResponse: + description: Service health check response. type: object required: - status properties: status: type: string + description: Health status indicator. + example: ok UserResponse: + description: Information about the authenticated user. type: object required: - login properties: login: type: string + description: User's login identifier (e.g. GitHub username). + example: octocat diff --git a/docs/execution/observability.mdx b/docs/execution/observability.mdx index b9172a4ae..ecb16aaaf 100644 --- a/docs/execution/observability.mdx +++ b/docs/execution/observability.mdx @@ -153,17 +153,7 @@ ARC_LOG=debug arc run start workflow.dot ### API: Server-Sent Events -When running workflows through the API server, subscribe to a live event stream: - -``` -GET /runs/{id}/events -``` - -This returns a Server-Sent Events (SSE) stream. Each event is a JSON-serialized `WorkflowRunEvent`. The stream stays open until the run completes, at which point the connection closes. If the run has already finished, the endpoint returns `410 Gone`. - -```bash -curl -N http://localhost:3000/runs/01JKXYZ.../events -``` +When running workflows through the API server, subscribe to a live event stream via the [run events endpoint](/api-reference/runs#get-events). Each event is a JSON-serialized `WorkflowRunEvent`. The stream stays open until the run completes. ### Web UI @@ -204,34 +194,13 @@ Each run's logs directory contains a standard set of files: ### Inspecting stages and turns -The API provides endpoints for drilling into individual stages and the agent turns within them: - -``` -GET /runs/{id}/stages -``` - -Returns per-stage metadata: node ID, status, duration, cost, files touched. - -``` -GET /runs/{id}/stages/{stageId}/turns -``` - -Returns the conversation turns within an agent stage — each user prompt, assistant response, and tool call with its result. +The API provides endpoints for drilling into individual stages and the agent turns within them. See the [stages](/api-reference/run-internals#get-stages) and [turns](/api-reference/run-internals#get-stage-turns) API reference for details. ## Insights (SQL analytics) The Insights feature lets you run SQL queries across your run data using DuckDB. This is useful for aggregate analysis — finding slow workflows, tracking failure rates, comparing model costs, and spotting trends. -### API endpoints - -| Endpoint | Description | -|---|---| -| `GET /insights/queries` | List saved queries | -| `POST /insights/queries` | Save a new query | -| `PUT /insights/queries/{id}` | Update a saved query | -| `DELETE /insights/queries/{id}` | Delete a saved query | -| `POST /insights/execute` | Execute a SQL query | -| `GET /insights/history` | View recent query executions | +Insights is managed through the [Insights API endpoints](/api-reference/insights). You can save, update, and execute queries programmatically. ### Example queries @@ -269,13 +238,7 @@ ORDER BY runs DESC ## Aggregate usage -The API server tracks aggregate usage counters across all runs. These are available at: - -``` -GET /usage -``` - -This returns total run count, total runtime, and per-model breakdowns of token usage and cost. Counters reset on server restart. +The API server tracks aggregate usage counters across all runs — total run count, total runtime, and per-model breakdowns of token usage and cost. See the [usage endpoint](/api-reference/run-outputs#get-usage) in the API reference. Counters reset on server restart. ## Credential redaction diff --git a/docs/execution/retros.mdx b/docs/execution/retros.mdx index b37680c95..7d810f9ab 100644 --- a/docs/execution/retros.mdx +++ b/docs/execution/retros.mdx @@ -116,71 +116,8 @@ arc run start workflow.dot --no-retro ### API -Retrieve the retro for a specific run: - -``` -GET /runs/{id}/retro -``` - -Returns the full retro JSON, or `null` if no retro is available yet. - -List retros across all runs (paginated): - -``` -GET /retros -``` - -Returns a summary for each retro including `run_id`, `workflow_name`, `goal`, `timestamp`, `smoothness`, aggregate stats, and a count of friction points. +Retros are also available via the REST API. See the [Retros API reference](/api-reference/retros) for endpoints to retrieve a single run's retro or list retros across all runs. ## Storage Retros are stored as `retro.json` in the run's logs directory alongside `checkpoint.json` and `progress.jsonl`. They are plain JSON files — easy to parse, query, or pipe into other tools. - -```json -{ - "run_id": "01JKXYZ...", - "workflow_name": "PlanImplement", - "goal": "Fix the authentication bug", - "timestamp": "2026-03-05T14:30:00Z", - "smoothness": "smooth", - "stages": [ - { - "stage_id": "plan", - "stage_label": "Plan", - "status": "success", - "duration_ms": 5000, - "retries": 0, - "cost": 0.05, - "files_touched": ["plan.md"] - }, - { - "stage_id": "implement", - "stage_label": "Implement", - "status": "success", - "duration_ms": 15000, - "retries": 1, - "cost": 0.10, - "files_touched": ["src/auth.rs", "src/auth_test.rs"] - } - ], - "stats": { - "total_duration_ms": 20000, - "total_cost": 0.15, - "total_retries": 1, - "files_touched": ["plan.md", "src/auth.rs", "src/auth_test.rs"], - "stages_completed": 2, - "stages_failed": 0 - }, - "intent": "Fix the authentication bug causing login failures", - "outcome": "Successfully fixed the token refresh logic", - "learnings": [ - { "category": "code", "text": "Token refresh was in the wrong module" } - ], - "friction_points": [ - { "kind": "retry", "description": "First implementation attempt had an incorrect import", "stage_id": "implement" } - ], - "open_items": [ - { "kind": "test_gap", "description": "No integration test for token refresh flow" } - ] -} -``` diff --git a/docs/reference/architecture.mdx b/docs/reference/architecture.mdx index a51204716..fe43045c3 100644 --- a/docs/reference/architecture.mdx +++ b/docs/reference/architecture.mdx @@ -53,22 +53,11 @@ Key server config options: ### Event streaming -The API streams run events via [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events): - -``` -GET /runs/{id}/events -``` - -Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. +The API streams run events via [Server-Sent Events (SSE)](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events). Every significant action — stage starts, LLM calls, tool invocations, edge selections — is emitted as a structured JSON event. The web UI uses this endpoint for real-time run monitoring. Any HTTP client that supports SSE can subscribe. See the [run events endpoint](/api-reference/runs#get-events) in the API reference. ### Human-in-the-loop -In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts: - -- `GET /runs/{id}/questions` — Poll for pending questions -- `POST /runs/{id}/questions/{qid}/answer` — Submit an answer - -The engine blocks the current stage until the answer is received, then continues execution. +In API mode, human-in-the-loop questions are served over HTTP instead of terminal prompts. The engine blocks the current stage until an answer is received, then continues execution. See the [Human-in-the-Loop API reference](/api-reference/human-in-the-loop) for the polling and answer submission endpoints. ### Authentication diff --git a/packages/arc-api-client/src/.openapi-generator/FILES b/packages/arc-api-client/src/.openapi-generator/FILES index bbd7cd112..a2512531a 100644 --- a/packages/arc-api-client/src/.openapi-generator/FILES +++ b/packages/arc-api-client/src/.openapi-generator/FILES @@ -19,9 +19,10 @@ index.ts models/aggregate-usage.ts models/api-question-option.ts models/api-question.ts +models/assistant-stage-turn.ts models/assistant-turn.ts models/branch.ts -models/cancel-run200-response.ts +models/cancel-run-response.ts models/check-run-status.ts models/check-run.ts models/control-detail.ts @@ -90,9 +91,11 @@ models/stage-turn.ts models/start-run-request.ts models/start-run-response.ts models/steer-request.ts -models/steer-run200-response.ts +models/steer-run-response.ts models/submit-answer-request.ts models/submit-answer-response.ts +models/system-stage-turn.ts +models/tool-stage-turn.ts models/tool-turn.ts models/tool-use.ts models/usage-by-model.ts diff --git a/packages/arc-api-client/src/api/discovery-api.ts b/packages/arc-api-client/src/api/discovery-api.ts index 94f6b8b06..b66adbfb8 100644 --- a/packages/arc-api-client/src/api/discovery-api.ts +++ b/packages/arc-api-client/src/api/discovery-api.ts @@ -35,7 +35,7 @@ import type { UserResponse } from '../models'; export const DiscoveryApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns service health status. Used by load balancers and monitoring. * @summary Health Check * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -171,7 +171,7 @@ export const DiscoveryApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = DiscoveryApiAxiosParamCreator(configuration) return { /** - * + * Returns service health status. Used by load balancers and monitoring. * @summary Health Check * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -228,7 +228,7 @@ export const DiscoveryApiFactory = function (configuration?: Configuration, base const localVarFp = DiscoveryApiFp(configuration) return { /** - * + * Returns service health status. Used by load balancers and monitoring. * @summary Health Check * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -271,7 +271,7 @@ export const DiscoveryApiFactory = function (configuration?: Configuration, base */ export class DiscoveryApi extends BaseAPI { /** - * + * Returns service health status. Used by load balancers and monitoring. * @summary Health Check * @param {*} [options] Override http request option. * @throws {RequiredError} diff --git a/packages/arc-api-client/src/api/human-in-the-loop-api.ts b/packages/arc-api-client/src/api/human-in-the-loop-api.ts index 55e4b24c9..d55e4e475 100644 --- a/packages/arc-api-client/src/api/human-in-the-loop-api.ts +++ b/packages/arc-api-client/src/api/human-in-the-loop-api.ts @@ -32,7 +32,7 @@ import type { PreviewUrlResponse } from '../models'; // @ts-ignore import type { SteerRequest } from '../models'; // @ts-ignore -import type { SteerRun200Response } from '../models'; +import type { SteerRunResponse } from '../models'; // @ts-ignore import type { SubmitAnswerRequest } from '../models'; // @ts-ignore @@ -43,9 +43,9 @@ import type { SubmitAnswerResponse } from '../models'; export const HumanInTheLoopApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Generates a time-limited preview URL for a port exposed by the run\'s sandbox environment. * @summary Preview URL - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {PreviewUrlRequest} previewUrlRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -89,9 +89,9 @@ export const HumanInTheLoopApiAxiosParamCreator = function (configuration?: Conf }; }, /** - * + * Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed. * @summary List Run Questions - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -130,9 +130,9 @@ export const HumanInTheLoopApiAxiosParamCreator = function (configuration?: Conf }; }, /** - * + * Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously. * @summary Steer Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {SteerRequest} steerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -176,10 +176,10 @@ export const HumanInTheLoopApiAxiosParamCreator = function (configuration?: Conf }; }, /** - * + * Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type. * @summary Submit Run Answer - * @param {string} id - * @param {string} qid + * @param {string} id Unique run identifier (ULID). + * @param {string} qid Unique identifier of a pending question. * @param {SubmitAnswerRequest} submitAnswerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -235,9 +235,9 @@ export const HumanInTheLoopApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = HumanInTheLoopApiAxiosParamCreator(configuration) return { /** - * + * Generates a time-limited preview URL for a port exposed by the run\'s sandbox environment. * @summary Preview URL - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {PreviewUrlRequest} previewUrlRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -249,9 +249,9 @@ export const HumanInTheLoopApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed. * @summary List Run Questions - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -262,24 +262,24 @@ export const HumanInTheLoopApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously. * @summary Steer Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {SteerRequest} steerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} */ - async steerRun(id: string, steerRequest: SteerRequest, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise> { + async steerRun(id: string, steerRequest: SteerRequest, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise> { const localVarAxiosArgs = await localVarAxiosParamCreator.steerRun(id, steerRequest, options); const localVarOperationServerIndex = configuration?.serverIndex ?? 0; const localVarOperationServerBasePath = operationServerMap['HumanInTheLoopApi.steerRun']?.[localVarOperationServerIndex]?.url; return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type. * @summary Submit Run Answer - * @param {string} id - * @param {string} qid + * @param {string} id Unique run identifier (ULID). + * @param {string} qid Unique identifier of a pending question. * @param {SubmitAnswerRequest} submitAnswerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -300,9 +300,9 @@ export const HumanInTheLoopApiFactory = function (configuration?: Configuration, const localVarFp = HumanInTheLoopApiFp(configuration) return { /** - * + * Generates a time-limited preview URL for a port exposed by the run\'s sandbox environment. * @summary Preview URL - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {PreviewUrlRequest} previewUrlRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -311,9 +311,9 @@ export const HumanInTheLoopApiFactory = function (configuration?: Configuration, return localVarFp.generatePreviewUrl(id, previewUrlRequest, options).then((request) => request(axios, basePath)); }, /** - * + * Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed. * @summary List Run Questions - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -321,21 +321,21 @@ export const HumanInTheLoopApiFactory = function (configuration?: Configuration, return localVarFp.listRunQuestions(id, options).then((request) => request(axios, basePath)); }, /** - * + * Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously. * @summary Steer Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {SteerRequest} steerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} */ - steerRun(id: string, steerRequest: SteerRequest, options?: RawAxiosRequestConfig): AxiosPromise { + steerRun(id: string, steerRequest: SteerRequest, options?: RawAxiosRequestConfig): AxiosPromise { return localVarFp.steerRun(id, steerRequest, options).then((request) => request(axios, basePath)); }, /** - * + * Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type. * @summary Submit Run Answer - * @param {string} id - * @param {string} qid + * @param {string} id Unique run identifier (ULID). + * @param {string} qid Unique identifier of a pending question. * @param {SubmitAnswerRequest} submitAnswerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -351,9 +351,9 @@ export const HumanInTheLoopApiFactory = function (configuration?: Configuration, */ export class HumanInTheLoopApi extends BaseAPI { /** - * + * Generates a time-limited preview URL for a port exposed by the run\'s sandbox environment. * @summary Preview URL - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {PreviewUrlRequest} previewUrlRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -363,9 +363,9 @@ export class HumanInTheLoopApi extends BaseAPI { } /** - * + * Returns pending human-in-the-loop questions for a run. Questions are generated when the workflow needs user input to proceed. * @summary List Run Questions - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -374,9 +374,9 @@ export class HumanInTheLoopApi extends BaseAPI { } /** - * + * Sends inline guidance to a running agent, targeting a specific file and line. The guidance is delivered asynchronously. * @summary Steer Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {SteerRequest} steerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -386,10 +386,10 @@ export class HumanInTheLoopApi extends BaseAPI { } /** - * + * Submits an answer to a pending question. The answer can be freeform text or a selected option key, depending on the question type. * @summary Submit Run Answer - * @param {string} id - * @param {string} qid + * @param {string} id Unique run identifier (ULID). + * @param {string} qid Unique identifier of a pending question. * @param {SubmitAnswerRequest} submitAnswerRequest * @param {*} [options] Override http request option. * @throws {RequiredError} diff --git a/packages/arc-api-client/src/api/insights-api.ts b/packages/arc-api-client/src/api/insights-api.ts index 7f08eebfb..d2c89580d 100644 --- a/packages/arc-api-client/src/api/insights-api.ts +++ b/packages/arc-api-client/src/api/insights-api.ts @@ -41,7 +41,7 @@ import type { SavedQuery } from '../models'; export const InsightsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Saves a new named SQL query for later reuse. * @summary Create Saved Query * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. @@ -83,9 +83,9 @@ export const InsightsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Permanently removes a saved query. * @summary Delete Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -124,7 +124,7 @@ export const InsightsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Executes an ad-hoc SQL query against the analytics database and returns columnar results. * @summary Execute Query * @param {ExecuteQueryRequest} executeQueryRequest * @param {*} [options] Override http request option. @@ -166,10 +166,10 @@ export const InsightsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Returns a paginated history of recently executed queries with timing and row counts. * @summary List Query History - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -213,10 +213,10 @@ export const InsightsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Returns a paginated list of saved SQL queries for the insights editor. * @summary List Saved Queries - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -260,9 +260,9 @@ export const InsightsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Replaces the name and SQL of an existing saved query. * @summary Update Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -315,7 +315,7 @@ export const InsightsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = InsightsApiAxiosParamCreator(configuration) return { /** - * + * Saves a new named SQL query for later reuse. * @summary Create Saved Query * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. @@ -328,9 +328,9 @@ export const InsightsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Permanently removes a saved query. * @summary Delete Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -341,7 +341,7 @@ export const InsightsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Executes an ad-hoc SQL query against the analytics database and returns columnar results. * @summary Execute Query * @param {ExecuteQueryRequest} executeQueryRequest * @param {*} [options] Override http request option. @@ -354,10 +354,10 @@ export const InsightsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated history of recently executed queries with timing and row counts. * @summary List Query History - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -368,10 +368,10 @@ export const InsightsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated list of saved SQL queries for the insights editor. * @summary List Saved Queries - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -382,9 +382,9 @@ export const InsightsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Replaces the name and SQL of an existing saved query. * @summary Update Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -405,7 +405,7 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP const localVarFp = InsightsApiFp(configuration) return { /** - * + * Saves a new named SQL query for later reuse. * @summary Create Saved Query * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. @@ -415,9 +415,9 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP return localVarFp.createSavedQuery(saveQueryRequest, options).then((request) => request(axios, basePath)); }, /** - * + * Permanently removes a saved query. * @summary Delete Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -425,7 +425,7 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP return localVarFp.deleteSavedQuery(id, options).then((request) => request(axios, basePath)); }, /** - * + * Executes an ad-hoc SQL query against the analytics database and returns columnar results. * @summary Execute Query * @param {ExecuteQueryRequest} executeQueryRequest * @param {*} [options] Override http request option. @@ -435,10 +435,10 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP return localVarFp.executeQuery(executeQueryRequest, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated history of recently executed queries with timing and row counts. * @summary List Query History - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -446,10 +446,10 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP return localVarFp.listQueryHistory(pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated list of saved SQL queries for the insights editor. * @summary List Saved Queries - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -457,9 +457,9 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP return localVarFp.listSavedQueries(pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Replaces the name and SQL of an existing saved query. * @summary Update Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -475,7 +475,7 @@ export const InsightsApiFactory = function (configuration?: Configuration, baseP */ export class InsightsApi extends BaseAPI { /** - * + * Saves a new named SQL query for later reuse. * @summary Create Saved Query * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. @@ -486,9 +486,9 @@ export class InsightsApi extends BaseAPI { } /** - * + * Permanently removes a saved query. * @summary Delete Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -497,7 +497,7 @@ export class InsightsApi extends BaseAPI { } /** - * + * Executes an ad-hoc SQL query against the analytics database and returns columnar results. * @summary Execute Query * @param {ExecuteQueryRequest} executeQueryRequest * @param {*} [options] Override http request option. @@ -508,10 +508,10 @@ export class InsightsApi extends BaseAPI { } /** - * + * Returns a paginated history of recently executed queries with timing and row counts. * @summary List Query History - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -520,10 +520,10 @@ export class InsightsApi extends BaseAPI { } /** - * + * Returns a paginated list of saved SQL queries for the insights editor. * @summary List Saved Queries - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -532,9 +532,9 @@ export class InsightsApi extends BaseAPI { } /** - * + * Replaces the name and SQL of an existing saved query. * @summary Update Saved Query - * @param {string} id + * @param {string} id Unique identifier of a saved query. * @param {SaveQueryRequest} saveQueryRequest * @param {*} [options] Override http request option. * @throws {RequiredError} diff --git a/packages/arc-api-client/src/api/projects-api.ts b/packages/arc-api-client/src/api/projects-api.ts index 9ff015fb2..593e1e1ac 100644 --- a/packages/arc-api-client/src/api/projects-api.ts +++ b/packages/arc-api-client/src/api/projects-api.ts @@ -33,11 +33,11 @@ import type { PaginatedProjectList } from '../models'; export const ProjectsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns a paginated list of branches for a specific project. * @summary List Branches - * @param {string} id - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique identifier of a project (repository). + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -84,10 +84,10 @@ export const ProjectsApiAxiosParamCreator = function (configuration?: Configurat }; }, /** - * + * Returns a paginated list of registered projects (repositories). * @summary List Projects - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -140,11 +140,11 @@ export const ProjectsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = ProjectsApiAxiosParamCreator(configuration) return { /** - * + * Returns a paginated list of branches for a specific project. * @summary List Branches - * @param {string} id - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique identifier of a project (repository). + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -155,10 +155,10 @@ export const ProjectsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated list of registered projects (repositories). * @summary List Projects - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -178,11 +178,11 @@ export const ProjectsApiFactory = function (configuration?: Configuration, baseP const localVarFp = ProjectsApiFp(configuration) return { /** - * + * Returns a paginated list of branches for a specific project. * @summary List Branches - * @param {string} id - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique identifier of a project (repository). + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -190,10 +190,10 @@ export const ProjectsApiFactory = function (configuration?: Configuration, baseP return localVarFp.listBranches(id, pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated list of registered projects (repositories). * @summary List Projects - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -208,11 +208,11 @@ export const ProjectsApiFactory = function (configuration?: Configuration, baseP */ export class ProjectsApi extends BaseAPI { /** - * + * Returns a paginated list of branches for a specific project. * @summary List Branches - * @param {string} id - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique identifier of a project (repository). + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -221,10 +221,10 @@ export class ProjectsApi extends BaseAPI { } /** - * + * Returns a paginated list of registered projects (repositories). * @summary List Projects - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/retros-api.ts b/packages/arc-api-client/src/api/retros-api.ts index 8a5632aa7..b46b90bed 100644 --- a/packages/arc-api-client/src/api/retros-api.ts +++ b/packages/arc-api-client/src/api/retros-api.ts @@ -31,10 +31,10 @@ import type { PaginatedRetroList } from '../models'; export const RetrosApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics. * @summary List Retros - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -78,9 +78,9 @@ export const RetrosApiAxiosParamCreator = function (configuration?: Configuratio }; }, /** - * + * Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet. * @summary Retrieve Retro - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -128,10 +128,10 @@ export const RetrosApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = RetrosApiAxiosParamCreator(configuration) return { /** - * + * Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics. * @summary List Retros - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -142,9 +142,9 @@ export const RetrosApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet. * @summary Retrieve Retro - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -164,10 +164,10 @@ export const RetrosApiFactory = function (configuration?: Configuration, basePat const localVarFp = RetrosApiFp(configuration) return { /** - * + * Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics. * @summary List Retros - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -175,9 +175,9 @@ export const RetrosApiFactory = function (configuration?: Configuration, basePat return localVarFp.listRetros(pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet. * @summary Retrieve Retro - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -192,10 +192,10 @@ export const RetrosApiFactory = function (configuration?: Configuration, basePat */ export class RetrosApi extends BaseAPI { /** - * + * Returns a paginated list of run retrospectives ordered by recency, with smoothness ratings and summary statistics. * @summary List Retros - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -204,9 +204,9 @@ export class RetrosApi extends BaseAPI { } /** - * + * Returns the retrospective analysis for a completed run, or null if the retro has not been generated yet. * @summary Retrieve Retro - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/run-internals-api.ts b/packages/arc-api-client/src/api/run-internals-api.ts index b83abff85..897ccde3d 100644 --- a/packages/arc-api-client/src/api/run-internals-api.ts +++ b/packages/arc-api-client/src/api/run-internals-api.ts @@ -33,9 +33,9 @@ import type { PaginatedStageTurnList } from '../models'; export const RunInternalsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns the ordered list of stages in a run\'s workflow graph with their current status and timing. * @summary List Run Stages - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -74,12 +74,12 @@ export const RunInternalsApiAxiosParamCreator = function (configuration?: Config }; }, /** - * + * Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations. * @summary List Stage Turns - * @param {string} id - * @param {string} stageId - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique run identifier (ULID). + * @param {string} stageId Identifier of a stage within a run\'s workflow graph. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -129,9 +129,9 @@ export const RunInternalsApiAxiosParamCreator = function (configuration?: Config }; }, /** - * + * Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet. * @summary Retrieve Run Checkpoint - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -170,9 +170,9 @@ export const RunInternalsApiAxiosParamCreator = function (configuration?: Config }; }, /** - * + * Returns the TOML configuration file content used to launch this run. * @summary Retrieve Run Configuration - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -211,9 +211,9 @@ export const RunInternalsApiAxiosParamCreator = function (configuration?: Config }; }, /** - * + * Returns the key-value context map accumulated during the run. Empty if the run has not started. * @summary Retrieve Run Context - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -261,9 +261,9 @@ export const RunInternalsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = RunInternalsApiAxiosParamCreator(configuration) return { /** - * + * Returns the ordered list of stages in a run\'s workflow graph with their current status and timing. * @summary List Run Stages - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -274,12 +274,12 @@ export const RunInternalsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations. * @summary List Stage Turns - * @param {string} id - * @param {string} stageId - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique run identifier (ULID). + * @param {string} stageId Identifier of a stage within a run\'s workflow graph. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -290,9 +290,9 @@ export const RunInternalsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet. * @summary Retrieve Run Checkpoint - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -303,9 +303,9 @@ export const RunInternalsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the TOML configuration file content used to launch this run. * @summary Retrieve Run Configuration - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -316,9 +316,9 @@ export const RunInternalsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the key-value context map accumulated during the run. Empty if the run has not started. * @summary Retrieve Run Context - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -338,9 +338,9 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b const localVarFp = RunInternalsApiFp(configuration) return { /** - * + * Returns the ordered list of stages in a run\'s workflow graph with their current status and timing. * @summary List Run Stages - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -348,12 +348,12 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b return localVarFp.listRunStages(id, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations. * @summary List Stage Turns - * @param {string} id - * @param {string} stageId - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique run identifier (ULID). + * @param {string} stageId Identifier of a stage within a run\'s workflow graph. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -361,9 +361,9 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b return localVarFp.listStageTurns(id, stageId, pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet. * @summary Retrieve Run Checkpoint - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -371,9 +371,9 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b return localVarFp.retrieveRunCheckpoint(id, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the TOML configuration file content used to launch this run. * @summary Retrieve Run Configuration - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -381,9 +381,9 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b return localVarFp.retrieveRunConfiguration(id, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the key-value context map accumulated during the run. Empty if the run has not started. * @summary Retrieve Run Context - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -398,9 +398,9 @@ export const RunInternalsApiFactory = function (configuration?: Configuration, b */ export class RunInternalsApi extends BaseAPI { /** - * + * Returns the ordered list of stages in a run\'s workflow graph with their current status and timing. * @summary List Run Stages - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -409,12 +409,12 @@ export class RunInternalsApi extends BaseAPI { } /** - * + * Returns a paginated list of conversation turns within a specific stage, including system prompts, assistant responses, and tool invocations. * @summary List Stage Turns - * @param {string} id - * @param {string} stageId - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} id Unique run identifier (ULID). + * @param {string} stageId Identifier of a stage within a run\'s workflow graph. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -423,9 +423,9 @@ export class RunInternalsApi extends BaseAPI { } /** - * + * Returns the latest checkpoint data for a run, or null if no checkpoint has been recorded yet. * @summary Retrieve Run Checkpoint - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -434,9 +434,9 @@ export class RunInternalsApi extends BaseAPI { } /** - * + * Returns the TOML configuration file content used to launch this run. * @summary Retrieve Run Configuration - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -445,9 +445,9 @@ export class RunInternalsApi extends BaseAPI { } /** - * + * Returns the key-value context map accumulated during the run. Empty if the run has not started. * @summary Retrieve Run Context - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/run-outputs-api.ts b/packages/arc-api-client/src/api/run-outputs-api.ts index bd13b534e..c82a5b9c4 100644 --- a/packages/arc-api-client/src/api/run-outputs-api.ts +++ b/packages/arc-api-client/src/api/run-outputs-api.ts @@ -35,10 +35,10 @@ import type { RunUsage } from '../models'; export const RunOutputsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint. * @summary List Run Compare - * @param {string} id - * @param {string} [checkpoint] + * @param {string} id Unique run identifier (ULID). + * @param {string} [checkpoint] Filter file diffs to a specific checkpoint. Defaults to all changes. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -81,9 +81,9 @@ export const RunOutputsApiAxiosParamCreator = function (configuration?: Configur }; }, /** - * + * Returns verification results for a run, organized by category with individual control statuses. * @summary List Run Verifications - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -122,9 +122,9 @@ export const RunOutputsApiAxiosParamCreator = function (configuration?: Configur }; }, /** - * + * Returns token and cost usage broken down by stage and model for a specific run. * @summary Retrieve Run Usage - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -172,10 +172,10 @@ export const RunOutputsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = RunOutputsApiAxiosParamCreator(configuration) return { /** - * + * Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint. * @summary List Run Compare - * @param {string} id - * @param {string} [checkpoint] + * @param {string} id Unique run identifier (ULID). + * @param {string} [checkpoint] Filter file diffs to a specific checkpoint. Defaults to all changes. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -186,9 +186,9 @@ export const RunOutputsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns verification results for a run, organized by category with individual control statuses. * @summary List Run Verifications - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -199,9 +199,9 @@ export const RunOutputsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns token and cost usage broken down by stage and model for a specific run. * @summary Retrieve Run Usage - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -221,10 +221,10 @@ export const RunOutputsApiFactory = function (configuration?: Configuration, bas const localVarFp = RunOutputsApiFp(configuration) return { /** - * + * Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint. * @summary List Run Compare - * @param {string} id - * @param {string} [checkpoint] + * @param {string} id Unique run identifier (ULID). + * @param {string} [checkpoint] Filter file diffs to a specific checkpoint. Defaults to all changes. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -232,9 +232,9 @@ export const RunOutputsApiFactory = function (configuration?: Configuration, bas return localVarFp.listRunCompare(id, checkpoint, options).then((request) => request(axios, basePath)); }, /** - * + * Returns verification results for a run, organized by category with individual control statuses. * @summary List Run Verifications - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -242,9 +242,9 @@ export const RunOutputsApiFactory = function (configuration?: Configuration, bas return localVarFp.listRunVerifications(id, options).then((request) => request(axios, basePath)); }, /** - * + * Returns token and cost usage broken down by stage and model for a specific run. * @summary Retrieve Run Usage - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -259,10 +259,10 @@ export const RunOutputsApiFactory = function (configuration?: Configuration, bas */ export class RunOutputsApi extends BaseAPI { /** - * + * Returns file-level diffs produced by the run, optionally filtered to a specific checkpoint. * @summary List Run Compare - * @param {string} id - * @param {string} [checkpoint] + * @param {string} id Unique run identifier (ULID). + * @param {string} [checkpoint] Filter file diffs to a specific checkpoint. Defaults to all changes. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -271,9 +271,9 @@ export class RunOutputsApi extends BaseAPI { } /** - * + * Returns verification results for a run, organized by category with individual control statuses. * @summary List Run Verifications - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -282,9 +282,9 @@ export class RunOutputsApi extends BaseAPI { } /** - * + * Returns token and cost usage broken down by stage and model for a specific run. * @summary Retrieve Run Usage - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/runs-api.ts b/packages/arc-api-client/src/api/runs-api.ts index bddcf0365..becbf0987 100644 --- a/packages/arc-api-client/src/api/runs-api.ts +++ b/packages/arc-api-client/src/api/runs-api.ts @@ -22,7 +22,7 @@ import { DUMMY_BASE_URL, assertParamExists, setApiKeyToObject, setBasicAuthToObj // @ts-ignore import { BASE_PATH, COLLECTION_FORMATS, type RequestArgs, BaseAPI, RequiredError, operationServerMap } from '../base'; // @ts-ignore -import type { CancelRun200Response } from '../models'; +import type { CancelRunResponse } from '../models'; // @ts-ignore import type { ErrorResponse } from '../models'; // @ts-ignore @@ -39,9 +39,9 @@ import type { StartRunResponse } from '../models'; export const RunsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled. * @summary Cancel Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -80,10 +80,10 @@ export const RunsApiAxiosParamCreator = function (configuration?: Configuration) }; }, /** - * + * Returns a paginated list of runs for the board view, ordered by recency. * @summary List Runs - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -127,9 +127,9 @@ export const RunsApiAxiosParamCreator = function (configuration?: Configuration) }; }, /** - * + * Returns the current status of a run, including error details and queue position if applicable. * @summary Retrieve Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -168,9 +168,9 @@ export const RunsApiAxiosParamCreator = function (configuration?: Configuration) }; }, /** - * + * Renders the workflow graph as an SVG image using Graphviz. * @summary Render SVG - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -209,7 +209,7 @@ export const RunsApiAxiosParamCreator = function (configuration?: Configuration) }; }, /** - * + * Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler. * @summary Start Run * @param {StartRunRequest} startRunRequest * @param {*} [options] Override http request option. @@ -251,9 +251,9 @@ export const RunsApiAxiosParamCreator = function (configuration?: Configuration) }; }, /** - * + * Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed. * @summary Stream Run Events - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -301,23 +301,23 @@ export const RunsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = RunsApiAxiosParamCreator(configuration) return { /** - * + * Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled. * @summary Cancel Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ - async cancelRun(id: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise> { + async cancelRun(id: string, options?: RawAxiosRequestConfig): Promise<(axios?: AxiosInstance, basePath?: string) => AxiosPromise> { const localVarAxiosArgs = await localVarAxiosParamCreator.cancelRun(id, options); const localVarOperationServerIndex = configuration?.serverIndex ?? 0; const localVarOperationServerBasePath = operationServerMap['RunsApi.cancelRun']?.[localVarOperationServerIndex]?.url; return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated list of runs for the board view, ordered by recency. * @summary List Runs - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -328,9 +328,9 @@ export const RunsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the current status of a run, including error details and queue position if applicable. * @summary Retrieve Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -341,9 +341,9 @@ export const RunsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Renders the workflow graph as an SVG image using Graphviz. * @summary Render SVG - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -354,7 +354,7 @@ export const RunsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler. * @summary Start Run * @param {StartRunRequest} startRunRequest * @param {*} [options] Override http request option. @@ -367,9 +367,9 @@ export const RunsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed. * @summary Stream Run Events - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -389,20 +389,20 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? const localVarFp = RunsApiFp(configuration) return { /** - * + * Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled. * @summary Cancel Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ - cancelRun(id: string, options?: RawAxiosRequestConfig): AxiosPromise { + cancelRun(id: string, options?: RawAxiosRequestConfig): AxiosPromise { return localVarFp.cancelRun(id, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated list of runs for the board view, ordered by recency. * @summary List Runs - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -410,9 +410,9 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? return localVarFp.listRuns(pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the current status of a run, including error details and queue position if applicable. * @summary Retrieve Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -420,9 +420,9 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? return localVarFp.retrieveRun(id, options).then((request) => request(axios, basePath)); }, /** - * + * Renders the workflow graph as an SVG image using Graphviz. * @summary Render SVG - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -430,7 +430,7 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? return localVarFp.retrieveRunSvg(id, options).then((request) => request(axios, basePath)); }, /** - * + * Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler. * @summary Start Run * @param {StartRunRequest} startRunRequest * @param {*} [options] Override http request option. @@ -440,9 +440,9 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? return localVarFp.startRun(startRunRequest, options).then((request) => request(axios, basePath)); }, /** - * + * Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed. * @summary Stream Run Events - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -457,9 +457,9 @@ export const RunsApiFactory = function (configuration?: Configuration, basePath? */ export class RunsApi extends BaseAPI { /** - * + * Cancels a running or queued run. Returns 409 if the run has already completed or been cancelled. * @summary Cancel Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -468,10 +468,10 @@ export class RunsApi extends BaseAPI { } /** - * + * Returns a paginated list of runs for the board view, ordered by recency. * @summary List Runs - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -480,9 +480,9 @@ export class RunsApi extends BaseAPI { } /** - * + * Returns the current status of a run, including error details and queue position if applicable. * @summary Retrieve Run - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -491,9 +491,9 @@ export class RunsApi extends BaseAPI { } /** - * + * Renders the workflow graph as an SVG image using Graphviz. * @summary Render SVG - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -502,7 +502,7 @@ export class RunsApi extends BaseAPI { } /** - * + * Queues a new workflow run from a DOT graph source. The run is created in `queued` status and will be picked up by the scheduler. * @summary Start Run * @param {StartRunRequest} startRunRequest * @param {*} [options] Override http request option. @@ -513,9 +513,9 @@ export class RunsApi extends BaseAPI { } /** - * + * Opens a server-sent event (SSE) stream for real-time run updates. Returns 410 if the stream has been closed. * @summary Stream Run Events - * @param {string} id + * @param {string} id Unique run identifier (ULID). * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/sessions-api.ts b/packages/arc-api-client/src/api/sessions-api.ts index 19ad9589a..df4c34198 100644 --- a/packages/arc-api-client/src/api/sessions-api.ts +++ b/packages/arc-api-client/src/api/sessions-api.ts @@ -85,8 +85,8 @@ export const SessionsApiAxiosParamCreator = function (configuration?: Configurat /** * Returns sessions ordered by recency (newest first). * @summary List Sessions - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -286,8 +286,8 @@ export const SessionsApiFp = function(configuration?: Configuration) { /** * Returns sessions ordered by recency (newest first). * @summary List Sessions - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -360,8 +360,8 @@ export const SessionsApiFactory = function (configuration?: Configuration, baseP /** * Returns sessions ordered by recency (newest first). * @summary List Sessions - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -421,8 +421,8 @@ export class SessionsApi extends BaseAPI { /** * Returns sessions ordered by recency (newest first). * @summary List Sessions - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/settings-api.ts b/packages/arc-api-client/src/api/settings-api.ts index 8dc132255..211d108ec 100644 --- a/packages/arc-api-client/src/api/settings-api.ts +++ b/packages/arc-api-client/src/api/settings-api.ts @@ -29,7 +29,7 @@ import type { SettingGroup } from '../models'; export const SettingsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns all server settings organized into groups. Each group contains fields with their current values and input types. * @summary Retrieve Server Settings * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -75,7 +75,7 @@ export const SettingsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = SettingsApiAxiosParamCreator(configuration) return { /** - * + * Returns all server settings organized into groups. Each group contains fields with their current values and input types. * @summary Retrieve Server Settings * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -96,7 +96,7 @@ export const SettingsApiFactory = function (configuration?: Configuration, baseP const localVarFp = SettingsApiFp(configuration) return { /** - * + * Returns all server settings organized into groups. Each group contains fields with their current values and input types. * @summary Retrieve Server Settings * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -112,7 +112,7 @@ export const SettingsApiFactory = function (configuration?: Configuration, baseP */ export class SettingsApi extends BaseAPI { /** - * + * Returns all server settings organized into groups. Each group contains fields with their current values and input types. * @summary Retrieve Server Settings * @param {*} [options] Override http request option. * @throws {RequiredError} diff --git a/packages/arc-api-client/src/api/verifications-api.ts b/packages/arc-api-client/src/api/verifications-api.ts index 343e65fff..4aefdd33a 100644 --- a/packages/arc-api-client/src/api/verifications-api.ts +++ b/packages/arc-api-client/src/api/verifications-api.ts @@ -33,7 +33,7 @@ import type { VerificationDetailResponse } from '../models'; export const VerificationsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns all verification categories with their controls and performance metrics. * @summary List Verifications * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -70,9 +70,9 @@ export const VerificationsApiAxiosParamCreator = function (configuration?: Confi }; }, /** - * + * Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category. * @summary Retrieve Verification - * @param {string} slug + * @param {string} slug URL-safe slug identifying a verification control. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -120,7 +120,7 @@ export const VerificationsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = VerificationsApiAxiosParamCreator(configuration) return { /** - * + * Returns all verification categories with their controls and performance metrics. * @summary List Verifications * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -132,9 +132,9 @@ export const VerificationsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category. * @summary Retrieve Verification - * @param {string} slug + * @param {string} slug URL-safe slug identifying a verification control. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -154,7 +154,7 @@ export const VerificationsApiFactory = function (configuration?: Configuration, const localVarFp = VerificationsApiFp(configuration) return { /** - * + * Returns all verification categories with their controls and performance metrics. * @summary List Verifications * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -163,9 +163,9 @@ export const VerificationsApiFactory = function (configuration?: Configuration, return localVarFp.listVerifications(options).then((request) => request(axios, basePath)); }, /** - * + * Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category. * @summary Retrieve Verification - * @param {string} slug + * @param {string} slug URL-safe slug identifying a verification control. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -180,7 +180,7 @@ export const VerificationsApiFactory = function (configuration?: Configuration, */ export class VerificationsApi extends BaseAPI { /** - * + * Returns all verification categories with their controls and performance metrics. * @summary List Verifications * @param {*} [options] Override http request option. * @throws {RequiredError} @@ -190,9 +190,9 @@ export class VerificationsApi extends BaseAPI { } /** - * + * Returns detailed information about a specific verification control, including performance data, recent results, and sibling controls in the same category. * @summary Retrieve Verification - * @param {string} slug + * @param {string} slug URL-safe slug identifying a verification control. * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/api/workflows-api.ts b/packages/arc-api-client/src/api/workflows-api.ts index 54825d26d..a094c556e 100644 --- a/packages/arc-api-client/src/api/workflows-api.ts +++ b/packages/arc-api-client/src/api/workflows-api.ts @@ -37,11 +37,11 @@ import type { WorkflowDetail } from '../models'; export const WorkflowsApiAxiosParamCreator = function (configuration?: Configuration) { return { /** - * + * Returns a paginated list of runs filtered to a specific workflow. * @summary List Workflow Runs - * @param {string} name - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} name URL-safe slug identifying a workflow definition. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -88,10 +88,10 @@ export const WorkflowsApiAxiosParamCreator = function (configuration?: Configura }; }, /** - * + * Returns a paginated list of workflow definitions available for execution. * @summary List Workflows - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -135,9 +135,9 @@ export const WorkflowsApiAxiosParamCreator = function (configuration?: Configura }; }, /** - * + * Returns the full detail of a workflow including its DOT graph, TOML config, and description. * @summary Retrieve Workflow - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -176,9 +176,9 @@ export const WorkflowsApiAxiosParamCreator = function (configuration?: Configura }; }, /** - * + * Queues a new run of the specified workflow using its stored DOT graph. * @summary Start Workflow Run - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -226,11 +226,11 @@ export const WorkflowsApiFp = function(configuration?: Configuration) { const localVarAxiosParamCreator = WorkflowsApiAxiosParamCreator(configuration) return { /** - * + * Returns a paginated list of runs filtered to a specific workflow. * @summary List Workflow Runs - * @param {string} name - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} name URL-safe slug identifying a workflow definition. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -241,10 +241,10 @@ export const WorkflowsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns a paginated list of workflow definitions available for execution. * @summary List Workflows - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -255,9 +255,9 @@ export const WorkflowsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Returns the full detail of a workflow including its DOT graph, TOML config, and description. * @summary Retrieve Workflow - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -268,9 +268,9 @@ export const WorkflowsApiFp = function(configuration?: Configuration) { return (axios, basePath) => createRequestFunction(localVarAxiosArgs, globalAxios, BASE_PATH, configuration)(axios, localVarOperationServerBasePath || basePath); }, /** - * + * Queues a new run of the specified workflow using its stored DOT graph. * @summary Start Workflow Run - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -290,11 +290,11 @@ export const WorkflowsApiFactory = function (configuration?: Configuration, base const localVarFp = WorkflowsApiFp(configuration) return { /** - * + * Returns a paginated list of runs filtered to a specific workflow. * @summary List Workflow Runs - * @param {string} name - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} name URL-safe slug identifying a workflow definition. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -302,10 +302,10 @@ export const WorkflowsApiFactory = function (configuration?: Configuration, base return localVarFp.listWorkflowRuns(name, pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns a paginated list of workflow definitions available for execution. * @summary List Workflows - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -313,9 +313,9 @@ export const WorkflowsApiFactory = function (configuration?: Configuration, base return localVarFp.listWorkflows(pageLimit, pageOffset, options).then((request) => request(axios, basePath)); }, /** - * + * Returns the full detail of a workflow including its DOT graph, TOML config, and description. * @summary Retrieve Workflow - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -323,9 +323,9 @@ export const WorkflowsApiFactory = function (configuration?: Configuration, base return localVarFp.retrieveWorkflow(name, options).then((request) => request(axios, basePath)); }, /** - * + * Queues a new run of the specified workflow using its stored DOT graph. * @summary Start Workflow Run - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -340,11 +340,11 @@ export const WorkflowsApiFactory = function (configuration?: Configuration, base */ export class WorkflowsApi extends BaseAPI { /** - * + * Returns a paginated list of runs filtered to a specific workflow. * @summary List Workflow Runs - * @param {string} name - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {string} name URL-safe slug identifying a workflow definition. + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -353,10 +353,10 @@ export class WorkflowsApi extends BaseAPI { } /** - * + * Returns a paginated list of workflow definitions available for execution. * @summary List Workflows - * @param {number} [pageLimit] - * @param {number} [pageOffset] + * @param {number} [pageLimit] Maximum number of items to return per page. + * @param {number} [pageOffset] Number of items to skip before returning results. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -365,9 +365,9 @@ export class WorkflowsApi extends BaseAPI { } /** - * + * Returns the full detail of a workflow including its DOT graph, TOML config, and description. * @summary Retrieve Workflow - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ @@ -376,9 +376,9 @@ export class WorkflowsApi extends BaseAPI { } /** - * + * Queues a new run of the specified workflow using its stored DOT graph. * @summary Start Workflow Run - * @param {string} name + * @param {string} name URL-safe slug identifying a workflow definition. * @param {*} [options] Override http request option. * @throws {RequiredError} */ diff --git a/packages/arc-api-client/src/models/aggregate-usage.ts b/packages/arc-api-client/src/models/aggregate-usage.ts index e3d0f840e..75a2c18eb 100644 --- a/packages/arc-api-client/src/models/aggregate-usage.ts +++ b/packages/arc-api-client/src/models/aggregate-usage.ts @@ -17,12 +17,33 @@ // @ts-ignore import type { UsageByModel } from './usage-by-model'; +/** + * Aggregate token and cost usage across all runs since server start. + */ export interface AggregateUsage { + /** + * Total number of completed runs. + */ 'total_runs': number; + /** + * Total input tokens across all runs. + */ 'total_input_tokens': number; + /** + * Total output tokens across all runs. + */ 'total_output_tokens': number; + /** + * Total cost in USD across all runs. + */ 'total_cost': number; + /** + * Total wall-clock runtime in seconds. + */ 'total_runtime_secs': number; + /** + * Usage grouped by model. + */ 'by_model': Array; } diff --git a/packages/arc-api-client/src/models/api-question-option.ts b/packages/arc-api-client/src/models/api-question-option.ts index 77fbb7827..2d79eef3b 100644 --- a/packages/arc-api-client/src/models/api-question-option.ts +++ b/packages/arc-api-client/src/models/api-question-option.ts @@ -14,8 +14,17 @@ +/** + * A selectable option for a multiple-choice or multi-select question. + */ export interface ApiQuestionOption { + /** + * Machine-readable option key used when submitting an answer. + */ 'key': string; + /** + * Human-readable label displayed to the user. + */ 'label': string; } diff --git a/packages/arc-api-client/src/models/api-question.ts b/packages/arc-api-client/src/models/api-question.ts index 40a558184..2bfd92a2c 100644 --- a/packages/arc-api-client/src/models/api-question.ts +++ b/packages/arc-api-client/src/models/api-question.ts @@ -20,11 +20,26 @@ import type { ApiQuestionOption } from './api-question-option'; // @ts-ignore import type { QuestionType } from './question-type'; +/** + * A pending human-in-the-loop question generated by a workflow stage. + */ export interface ApiQuestion { + /** + * Unique question identifier. + */ 'id': string; + /** + * The question text displayed to the user. + */ 'text': string; 'question_type': QuestionType; + /** + * Available options for selection-based questions. Empty for freeform questions. + */ 'options': Array; + /** + * Whether the user may provide freeform text in addition to selecting options. + */ 'allow_freeform': boolean; } diff --git a/packages/arc-api-client/src/models/assistant-stage-turn.ts b/packages/arc-api-client/src/models/assistant-stage-turn.ts new file mode 100644 index 000000000..be2bd1da5 --- /dev/null +++ b/packages/arc-api-client/src/models/assistant-stage-turn.ts @@ -0,0 +1,41 @@ +/* tslint:disable */ +/* eslint-disable */ +/** + * Arc Run API + * HTTP API for managing Arc workflow run executions. + * + * The version of the OpenAPI document: 0.1.0 + * + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + + +// May contain unused imports in some cases +// @ts-ignore +import type { ToolUse } from './tool-use'; + +/** + * An assistant response turn within a stage. + */ +export interface AssistantStageTurn { + 'kind': AssistantStageTurnKindEnum; + /** + * Assistant response text. + */ + 'content': string; + /** + * Tool invocations (always empty for assistant turns). + */ + 'tools'?: Array; +} + +export const AssistantStageTurnKindEnum = { + ASSISTANT: 'assistant' +} as const; + +export type AssistantStageTurnKindEnum = typeof AssistantStageTurnKindEnum[keyof typeof AssistantStageTurnKindEnum]; + + diff --git a/packages/arc-api-client/src/models/branch.ts b/packages/arc-api-client/src/models/branch.ts index f34d98fea..fa629ad6e 100644 --- a/packages/arc-api-client/src/models/branch.ts +++ b/packages/arc-api-client/src/models/branch.ts @@ -14,8 +14,17 @@ +/** + * A branch within a project. + */ export interface Branch { + /** + * Branch identifier. + */ 'id': string; + /** + * Branch name. + */ 'name': string; } diff --git a/packages/arc-api-client/src/models/cancel-run-response.ts b/packages/arc-api-client/src/models/cancel-run-response.ts new file mode 100644 index 000000000..1310b0e62 --- /dev/null +++ b/packages/arc-api-client/src/models/cancel-run-response.ts @@ -0,0 +1,26 @@ +/* tslint:disable */ +/* eslint-disable */ +/** + * Arc Run API + * HTTP API for managing Arc workflow run executions. + * + * The version of the OpenAPI document: 0.1.0 + * + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + + + +/** + * Response returned after cancelling a run. + */ +export interface CancelRunResponse { + /** + * Whether the cancellation was successful. + */ + 'cancelled': boolean; +} + diff --git a/packages/arc-api-client/src/models/check-run-status.ts b/packages/arc-api-client/src/models/check-run-status.ts index da8e6e2cb..b7acc42b1 100644 --- a/packages/arc-api-client/src/models/check-run-status.ts +++ b/packages/arc-api-client/src/models/check-run-status.ts @@ -14,6 +14,9 @@ +/** + * Status of a CI check run. + */ export const CheckRunStatus = { SUCCESS: 'success', diff --git a/packages/arc-api-client/src/models/check-run.ts b/packages/arc-api-client/src/models/check-run.ts index 04d3a3b0c..8a2d1b242 100644 --- a/packages/arc-api-client/src/models/check-run.ts +++ b/packages/arc-api-client/src/models/check-run.ts @@ -17,9 +17,18 @@ // @ts-ignore import type { CheckRunStatus } from './check-run-status'; +/** + * A CI check run result associated with a run\'s pull request. + */ export interface CheckRun { + /** + * Name of the CI check. + */ 'name': string; 'status': CheckRunStatus; + /** + * Duration of the check run in seconds. + */ 'duration_secs'?: number; } diff --git a/packages/arc-api-client/src/models/control-detail.ts b/packages/arc-api-client/src/models/control-detail.ts index f581bc589..81d6e1ebb 100644 --- a/packages/arc-api-client/src/models/control-detail.ts +++ b/packages/arc-api-client/src/models/control-detail.ts @@ -14,10 +14,25 @@ +/** + * Detailed information about a verification control including checks and examples. + */ export interface ControlDetail { + /** + * Detailed prose description of the control\'s purpose and rationale. + */ 'description': string; + /** + * Specific checks performed by this control. + */ 'checks': Array; + /** + * Example scenario where the control passes. + */ 'pass_example': string; + /** + * Example scenario where the control fails. + */ 'fail_example': string; } diff --git a/packages/arc-api-client/src/models/control-info.ts b/packages/arc-api-client/src/models/control-info.ts index 3416af863..bc11c30d5 100644 --- a/packages/arc-api-client/src/models/control-info.ts +++ b/packages/arc-api-client/src/models/control-info.ts @@ -17,11 +17,26 @@ // @ts-ignore import type { VerificationType } from './verification-type'; +/** + * Core metadata about a verification control. + */ export interface ControlInfo { + /** + * Human-readable control name. + */ 'name': string; + /** + * URL-safe slug. + */ 'slug': string; + /** + * Short description of what the control verifies. + */ 'description': string; 'type'?: VerificationType; + /** + * Name of the category this control belongs to. + */ 'category': string; } diff --git a/packages/arc-api-client/src/models/control-performance.ts b/packages/arc-api-client/src/models/control-performance.ts index a32ed589b..6f16563bf 100644 --- a/packages/arc-api-client/src/models/control-performance.ts +++ b/packages/arc-api-client/src/models/control-performance.ts @@ -20,10 +20,22 @@ import type { EvaluationResult } from './evaluation-result'; // @ts-ignore import type { VerificationMode } from './verification-mode'; +/** + * Performance metrics for a verification control. + */ export interface ControlPerformance { 'mode': VerificationMode; + /** + * F1 score of the control\'s AI evaluator. + */ 'f1'?: number; + /** + * Pass@1 rate. + */ 'pass_at_1'?: number; + /** + * Recent evaluation results (newest first). + */ 'evaluations': Array; } diff --git a/packages/arc-api-client/src/models/diff-file.ts b/packages/arc-api-client/src/models/diff-file.ts index d8a43b72c..40a4893e7 100644 --- a/packages/arc-api-client/src/models/diff-file.ts +++ b/packages/arc-api-client/src/models/diff-file.ts @@ -14,8 +14,17 @@ +/** + * A file\'s contents at one side of a diff. + */ export interface DiffFile { + /** + * File path relative to the repository root. + */ 'name': string; + /** + * Full file contents. Empty string for newly created or deleted files. + */ 'contents': string; } diff --git a/packages/arc-api-client/src/models/diff-stats.ts b/packages/arc-api-client/src/models/diff-stats.ts index 9e5951f5d..519b370cf 100644 --- a/packages/arc-api-client/src/models/diff-stats.ts +++ b/packages/arc-api-client/src/models/diff-stats.ts @@ -14,8 +14,17 @@ +/** + * Aggregate line-change statistics for a diff. + */ export interface DiffStats { + /** + * Total lines added. + */ 'additions': number; + /** + * Total lines deleted. + */ 'deletions': number; } diff --git a/packages/arc-api-client/src/models/error-response-entry.ts b/packages/arc-api-client/src/models/error-response-entry.ts index dd9aa0c96..4907e84da 100644 --- a/packages/arc-api-client/src/models/error-response-entry.ts +++ b/packages/arc-api-client/src/models/error-response-entry.ts @@ -14,9 +14,21 @@ +/** + * A single error entry in an error response. + */ export interface ErrorResponseEntry { + /** + * HTTP status code as a string. + */ 'status': string; + /** + * Short error classification. + */ 'title': string; + /** + * Human-readable error description. + */ 'detail': string; } diff --git a/packages/arc-api-client/src/models/error-response.ts b/packages/arc-api-client/src/models/error-response.ts index 998d38b1d..7ff766707 100644 --- a/packages/arc-api-client/src/models/error-response.ts +++ b/packages/arc-api-client/src/models/error-response.ts @@ -17,7 +17,13 @@ // @ts-ignore import type { ErrorResponseEntry } from './error-response-entry'; +/** + * Standard error response containing one or more error entries. + */ export interface ErrorResponse { + /** + * List of error entries. + */ 'errors': Array; } diff --git a/packages/arc-api-client/src/models/evaluation-result.ts b/packages/arc-api-client/src/models/evaluation-result.ts index 3e91d0656..495361638 100644 --- a/packages/arc-api-client/src/models/evaluation-result.ts +++ b/packages/arc-api-client/src/models/evaluation-result.ts @@ -14,6 +14,9 @@ +/** + * Outcome of a single verification evaluation. + */ export const EvaluationResult = { PASS: 'pass', diff --git a/packages/arc-api-client/src/models/execute-query-request.ts b/packages/arc-api-client/src/models/execute-query-request.ts index 2c09b4b71..335558d11 100644 --- a/packages/arc-api-client/src/models/execute-query-request.ts +++ b/packages/arc-api-client/src/models/execute-query-request.ts @@ -14,7 +14,13 @@ +/** + * Request body for executing an ad-hoc SQL query. + */ export interface ExecuteQueryRequest { + /** + * SQL query to execute. + */ 'sql': string; } diff --git a/packages/arc-api-client/src/models/execute-query-response.ts b/packages/arc-api-client/src/models/execute-query-response.ts index 915c2d314..ca09f2eae 100644 --- a/packages/arc-api-client/src/models/execute-query-response.ts +++ b/packages/arc-api-client/src/models/execute-query-response.ts @@ -14,10 +14,25 @@ +/** + * Columnar result set from an executed query. + */ export interface ExecuteQueryResponse { + /** + * Column names in the result set. + */ 'columns': Array; + /** + * Result rows, each an array of values matching the column order. + */ 'rows': Array>; + /** + * Query execution time in seconds. + */ 'elapsed': number; + /** + * Number of rows returned. + */ 'row_count': number; } diff --git a/packages/arc-api-client/src/models/file-checkpoint.ts b/packages/arc-api-client/src/models/file-checkpoint.ts index 9629f9d5b..67de73c9e 100644 --- a/packages/arc-api-client/src/models/file-checkpoint.ts +++ b/packages/arc-api-client/src/models/file-checkpoint.ts @@ -14,8 +14,17 @@ +/** + * A named checkpoint within a run, used to filter file diffs. + */ export interface FileCheckpoint { + /** + * Checkpoint identifier. + */ 'id': string; + /** + * Human-readable label for the checkpoint. + */ 'label': string; } diff --git a/packages/arc-api-client/src/models/file-diff.ts b/packages/arc-api-client/src/models/file-diff.ts index fa4f9b31b..0f81e83c0 100644 --- a/packages/arc-api-client/src/models/file-diff.ts +++ b/packages/arc-api-client/src/models/file-diff.ts @@ -17,6 +17,9 @@ // @ts-ignore import type { DiffFile } from './diff-file'; +/** + * A before/after pair showing changes to a single file. + */ export interface FileDiff { 'old_file': DiffFile; 'new_file': DiffFile; diff --git a/packages/arc-api-client/src/models/health-response.ts b/packages/arc-api-client/src/models/health-response.ts index d77fda2bc..f53b15cf7 100644 --- a/packages/arc-api-client/src/models/health-response.ts +++ b/packages/arc-api-client/src/models/health-response.ts @@ -14,7 +14,13 @@ +/** + * Service health check response. + */ export interface HealthResponse { + /** + * Health status indicator. + */ 'status': string; } diff --git a/packages/arc-api-client/src/models/history-entry.ts b/packages/arc-api-client/src/models/history-entry.ts index f0d44b290..a002be31f 100644 --- a/packages/arc-api-client/src/models/history-entry.ts +++ b/packages/arc-api-client/src/models/history-entry.ts @@ -14,11 +14,29 @@ +/** + * A previously executed query in the history log. + */ export interface HistoryEntry { + /** + * Unique history entry identifier. + */ 'id': string; + /** + * SQL query that was executed. + */ 'sql': string; + /** + * Human-readable relative timestamp of execution. + */ 'timestamp': string; + /** + * Query execution time in seconds. + */ 'elapsed': number; + /** + * Number of rows returned. + */ 'row_count': number; } diff --git a/packages/arc-api-client/src/models/index.ts b/packages/arc-api-client/src/models/index.ts index aac00499e..47af2d7c3 100644 --- a/packages/arc-api-client/src/models/index.ts +++ b/packages/arc-api-client/src/models/index.ts @@ -1,9 +1,10 @@ export * from './aggregate-usage'; export * from './api-question'; export * from './api-question-option'; +export * from './assistant-stage-turn'; export * from './assistant-turn'; export * from './branch'; -export * from './cancel-run200-response'; +export * from './cancel-run-response'; export * from './check-run'; export * from './check-run-status'; export * from './control-detail'; @@ -71,9 +72,11 @@ export * from './stage-turn'; export * from './start-run-request'; export * from './start-run-response'; export * from './steer-request'; -export * from './steer-run200-response'; +export * from './steer-run-response'; export * from './submit-answer-request'; export * from './submit-answer-response'; +export * from './system-stage-turn'; +export * from './tool-stage-turn'; export * from './tool-turn'; export * from './tool-use'; export * from './usage-by-model'; diff --git a/packages/arc-api-client/src/models/paginated-api-question-list.ts b/packages/arc-api-client/src/models/paginated-api-question-list.ts index da44cca39..1baf14aa9 100644 --- a/packages/arc-api-client/src/models/paginated-api-question-list.ts +++ b/packages/arc-api-client/src/models/paginated-api-question-list.ts @@ -20,6 +20,9 @@ import type { ApiQuestion } from './api-question'; // @ts-ignore import type { PaginationMeta } from './pagination-meta'; +/** + * Paginated list of pending questions. + */ export interface PaginatedApiQuestionList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-branch-list.ts b/packages/arc-api-client/src/models/paginated-branch-list.ts index 3fb65d366..938c955b5 100644 --- a/packages/arc-api-client/src/models/paginated-branch-list.ts +++ b/packages/arc-api-client/src/models/paginated-branch-list.ts @@ -20,6 +20,9 @@ import type { Branch } from './branch'; // @ts-ignore import type { PaginationMeta } from './pagination-meta'; +/** + * Paginated list of branches. + */ export interface PaginatedBranchList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-history-entry-list.ts b/packages/arc-api-client/src/models/paginated-history-entry-list.ts index 25cee334c..d2a644215 100644 --- a/packages/arc-api-client/src/models/paginated-history-entry-list.ts +++ b/packages/arc-api-client/src/models/paginated-history-entry-list.ts @@ -20,6 +20,9 @@ import type { HistoryEntry } from './history-entry'; // @ts-ignore import type { PaginationMeta } from './pagination-meta'; +/** + * Paginated list of query history entries. + */ export interface PaginatedHistoryEntryList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-project-list.ts b/packages/arc-api-client/src/models/paginated-project-list.ts index 56eca6e3b..d68c26db1 100644 --- a/packages/arc-api-client/src/models/paginated-project-list.ts +++ b/packages/arc-api-client/src/models/paginated-project-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { Project } from './project'; +/** + * Paginated list of projects. + */ export interface PaginatedProjectList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-retro-list.ts b/packages/arc-api-client/src/models/paginated-retro-list.ts index 908cf449d..56f8c228a 100644 --- a/packages/arc-api-client/src/models/paginated-retro-list.ts +++ b/packages/arc-api-client/src/models/paginated-retro-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { RetroListItem } from './retro-list-item'; +/** + * Paginated list of run retrospectives. + */ export interface PaginatedRetroList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-run-list.ts b/packages/arc-api-client/src/models/paginated-run-list.ts index 537afeac7..085ff2ba4 100644 --- a/packages/arc-api-client/src/models/paginated-run-list.ts +++ b/packages/arc-api-client/src/models/paginated-run-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { RunListItem } from './run-list-item'; +/** + * Paginated list of runs. + */ export interface PaginatedRunList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-run-stage-list.ts b/packages/arc-api-client/src/models/paginated-run-stage-list.ts index 42ebf1c84..f7c6a0f6b 100644 --- a/packages/arc-api-client/src/models/paginated-run-stage-list.ts +++ b/packages/arc-api-client/src/models/paginated-run-stage-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { RunStage } from './run-stage'; +/** + * Paginated list of run stages. + */ export interface PaginatedRunStageList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-run-verification-list.ts b/packages/arc-api-client/src/models/paginated-run-verification-list.ts index 2f1a84e37..c548b6f05 100644 --- a/packages/arc-api-client/src/models/paginated-run-verification-list.ts +++ b/packages/arc-api-client/src/models/paginated-run-verification-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { RunVerification } from './run-verification'; +/** + * Paginated list of run verification categories. + */ export interface PaginatedRunVerificationList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-saved-query-list.ts b/packages/arc-api-client/src/models/paginated-saved-query-list.ts index 16448b4c7..51e9b3882 100644 --- a/packages/arc-api-client/src/models/paginated-saved-query-list.ts +++ b/packages/arc-api-client/src/models/paginated-saved-query-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { SavedQuery } from './saved-query'; +/** + * Paginated list of saved queries. + */ export interface PaginatedSavedQueryList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-session-list.ts b/packages/arc-api-client/src/models/paginated-session-list.ts index 1997ccb14..af3857391 100644 --- a/packages/arc-api-client/src/models/paginated-session-list.ts +++ b/packages/arc-api-client/src/models/paginated-session-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { SessionListItem } from './session-list-item'; +/** + * Paginated list of sessions. + */ export interface PaginatedSessionList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-stage-turn-list.ts b/packages/arc-api-client/src/models/paginated-stage-turn-list.ts index 00eee7dbc..ca0ea7d6a 100644 --- a/packages/arc-api-client/src/models/paginated-stage-turn-list.ts +++ b/packages/arc-api-client/src/models/paginated-stage-turn-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { StageTurn } from './stage-turn'; +/** + * Paginated list of stage turns. + */ export interface PaginatedStageTurnList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-verification-category-list.ts b/packages/arc-api-client/src/models/paginated-verification-category-list.ts index b6c31ad11..6ec2c65d4 100644 --- a/packages/arc-api-client/src/models/paginated-verification-category-list.ts +++ b/packages/arc-api-client/src/models/paginated-verification-category-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { VerificationCategory } from './verification-category'; +/** + * Paginated list of verification categories. + */ export interface PaginatedVerificationCategoryList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/paginated-workflow-list.ts b/packages/arc-api-client/src/models/paginated-workflow-list.ts index c97ce0270..194430498 100644 --- a/packages/arc-api-client/src/models/paginated-workflow-list.ts +++ b/packages/arc-api-client/src/models/paginated-workflow-list.ts @@ -20,6 +20,9 @@ import type { PaginationMeta } from './pagination-meta'; // @ts-ignore import type { WorkflowListItem } from './workflow-list-item'; +/** + * Paginated list of workflows. + */ export interface PaginatedWorkflowList { 'data': Array; 'meta': PaginationMeta; diff --git a/packages/arc-api-client/src/models/pagination-meta.ts b/packages/arc-api-client/src/models/pagination-meta.ts index f574a634b..f2ab3af90 100644 --- a/packages/arc-api-client/src/models/pagination-meta.ts +++ b/packages/arc-api-client/src/models/pagination-meta.ts @@ -14,7 +14,13 @@ +/** + * Pagination metadata included in every paginated response. + */ export interface PaginationMeta { + /** + * Whether additional pages of results are available. + */ 'has_more': boolean; } diff --git a/packages/arc-api-client/src/models/preview-url-request.ts b/packages/arc-api-client/src/models/preview-url-request.ts index 729526da3..5461e5c60 100644 --- a/packages/arc-api-client/src/models/preview-url-request.ts +++ b/packages/arc-api-client/src/models/preview-url-request.ts @@ -14,8 +14,17 @@ +/** + * Request body for generating a preview URL from a sandbox port. + */ export interface PreviewUrlRequest { + /** + * Port number exposed by the sandbox. + */ 'port': number; + /** + * Time-to-live for the preview URL in seconds. + */ 'expires_in_secs': number; } diff --git a/packages/arc-api-client/src/models/preview-url-response.ts b/packages/arc-api-client/src/models/preview-url-response.ts index 028aaae9f..ec8f93a7f 100644 --- a/packages/arc-api-client/src/models/preview-url-response.ts +++ b/packages/arc-api-client/src/models/preview-url-response.ts @@ -14,7 +14,13 @@ +/** + * Response containing the generated preview URL. + */ export interface PreviewUrlResponse { + /** + * Time-limited preview URL. + */ 'url': string; } diff --git a/packages/arc-api-client/src/models/project.ts b/packages/arc-api-client/src/models/project.ts index 20da0f3d8..210a5416e 100644 --- a/packages/arc-api-client/src/models/project.ts +++ b/packages/arc-api-client/src/models/project.ts @@ -14,8 +14,17 @@ +/** + * A registered project (repository). + */ export interface Project { + /** + * Unique project identifier. + */ 'id': string; + /** + * Human-readable project name. + */ 'name': string; } diff --git a/packages/arc-api-client/src/models/question-type.ts b/packages/arc-api-client/src/models/question-type.ts index ec488be5b..9f0c25676 100644 --- a/packages/arc-api-client/src/models/question-type.ts +++ b/packages/arc-api-client/src/models/question-type.ts @@ -14,6 +14,9 @@ +/** + * The interaction type of a human-in-the-loop question. + */ export const QuestionType = { YES_NO: 'yes_no', diff --git a/packages/arc-api-client/src/models/recent-control-result.ts b/packages/arc-api-client/src/models/recent-control-result.ts index e36ec5fb9..43020af48 100644 --- a/packages/arc-api-client/src/models/recent-control-result.ts +++ b/packages/arc-api-client/src/models/recent-control-result.ts @@ -17,11 +17,26 @@ // @ts-ignore import type { VerificationStatus } from './verification-status'; +/** + * Result of a recent verification control evaluation for a specific run. + */ export interface RecentControlResult { + /** + * Identifier of the run that was evaluated. + */ 'run_id': string; + /** + * Title of the evaluated run. + */ 'run_title': string; + /** + * Workflow that produced the run. + */ 'workflow': string; 'result': VerificationStatus; + /** + * Human-readable relative timestamp of the evaluation. + */ 'timestamp': string; } diff --git a/packages/arc-api-client/src/models/retro-list-item.ts b/packages/arc-api-client/src/models/retro-list-item.ts index a758e59c7..21baf1da8 100644 --- a/packages/arc-api-client/src/models/retro-list-item.ts +++ b/packages/arc-api-client/src/models/retro-list-item.ts @@ -20,13 +20,31 @@ import type { RetroStats } from './retro-stats'; // @ts-ignore import type { SmoothnessRating } from './smoothness-rating'; +/** + * Summary of a run retrospective shown in list views. + */ export interface RetroListItem { + /** + * Identifier of the run this retro belongs to. + */ 'run_id': string; + /** + * Name of the workflow that produced the run. + */ 'workflow_name': string; + /** + * The run\'s goal. + */ 'goal': string; + /** + * Timestamp when the retro was generated. + */ 'timestamp': string; 'smoothness'?: SmoothnessRating; 'stats': RetroStats; + /** + * Number of friction points identified in the retro. + */ 'friction_point_count': number; } diff --git a/packages/arc-api-client/src/models/retro-stats.ts b/packages/arc-api-client/src/models/retro-stats.ts index a94e4300f..3f6685b9b 100644 --- a/packages/arc-api-client/src/models/retro-stats.ts +++ b/packages/arc-api-client/src/models/retro-stats.ts @@ -14,12 +14,33 @@ +/** + * Summary statistics for a run retrospective. + */ export interface RetroStats { + /** + * Total run duration in milliseconds. + */ 'total_duration_ms': number; + /** + * Total cost in USD. + */ 'total_cost'?: number; + /** + * Total number of retries across all stages. + */ 'total_retries': number; + /** + * List of files modified during the run. + */ 'files_touched': Array; + /** + * Number of stages that completed successfully. + */ 'stages_completed': number; + /** + * Number of stages that failed. + */ 'stages_failed': number; } diff --git a/packages/arc-api-client/src/models/root-response-urls.ts b/packages/arc-api-client/src/models/root-response-urls.ts index 193168a0a..4d9a3dad4 100644 --- a/packages/arc-api-client/src/models/root-response-urls.ts +++ b/packages/arc-api-client/src/models/root-response-urls.ts @@ -14,9 +14,21 @@ +/** + * Collection of API discovery URLs. + */ export interface RootResponseUrls { + /** + * URL of the OpenAPI JSON specification. + */ 'openapi_url': string; + /** + * URL of the current user endpoint. + */ 'current_user_url': string; + /** + * URL of the health check endpoint. + */ 'health_url': string; } diff --git a/packages/arc-api-client/src/models/root-response.ts b/packages/arc-api-client/src/models/root-response.ts index fff376c6d..64da05961 100644 --- a/packages/arc-api-client/src/models/root-response.ts +++ b/packages/arc-api-client/src/models/root-response.ts @@ -17,6 +17,9 @@ // @ts-ignore import type { RootResponseUrls } from './root-response-urls'; +/** + * API discovery response with navigation URLs. + */ export interface RootResponse { 'urls': RootResponseUrls; } diff --git a/packages/arc-api-client/src/models/run-compare.ts b/packages/arc-api-client/src/models/run-compare.ts index c2a1a2a07..d00ab723e 100644 --- a/packages/arc-api-client/src/models/run-compare.ts +++ b/packages/arc-api-client/src/models/run-compare.ts @@ -23,8 +23,17 @@ import type { FileCheckpoint } from './file-checkpoint'; // @ts-ignore import type { FileDiff } from './file-diff'; +/** + * File-level diff output for a run, with checkpoint filtering support. + */ export interface RunCompare { + /** + * Available checkpoints for filtering. + */ 'checkpoints': Array; + /** + * File diffs, optionally filtered by checkpoint. + */ 'files': Array; 'stats': DiffStats; } diff --git a/packages/arc-api-client/src/models/run-list-item-status.ts b/packages/arc-api-client/src/models/run-list-item-status.ts index 8bfd23bc7..7619170f8 100644 --- a/packages/arc-api-client/src/models/run-list-item-status.ts +++ b/packages/arc-api-client/src/models/run-list-item-status.ts @@ -14,6 +14,9 @@ +/** + * Board column status for a run in the list view. + */ export const RunListItemStatus = { WORKING: 'working', diff --git a/packages/arc-api-client/src/models/run-list-item.ts b/packages/arc-api-client/src/models/run-list-item.ts index fc19898a4..65584944c 100644 --- a/packages/arc-api-client/src/models/run-list-item.ts +++ b/packages/arc-api-client/src/models/run-list-item.ts @@ -20,22 +20,71 @@ import type { CheckRun } from './check-run'; // @ts-ignore import type { RunListItemStatus } from './run-list-item-status'; +/** + * Summary of a run shown in the board view. + */ export interface RunListItem { + /** + * Unique run identifier (ULID). + */ 'id': string; + /** + * Repository name. + */ 'repo': string; + /** + * Human-readable title describing the run\'s goal. + */ 'title': string; + /** + * Slug of the workflow that produced this run. + */ 'workflow': string; 'status': RunListItemStatus; + /** + * Pull request number, if the run has opened a PR. + */ 'number'?: number; + /** + * Lines added in the run\'s diff. + */ 'additions'?: number; + /** + * Lines deleted in the run\'s diff. + */ 'deletions'?: number; + /** + * CI check run results for the run\'s PR. + */ 'checks'?: Array; + /** + * Wall-clock time elapsed since the run started, in seconds. + */ 'elapsed_secs'?: number; + /** + * Whether the elapsed time exceeds the expected threshold. + */ 'elapsed_warning'?: boolean; + /** + * Compute resources allocated to the run. + */ 'resources'?: string; + /** + * Number of review comments on the run\'s PR. + */ 'comments'?: number; + /** + * Text of a pending human-in-the-loop question, if any. + */ 'question'?: string; + /** + * Identifier of the sandbox environment running this run. + */ 'sandbox_id'?: string; + /** + * Timestamp when the run was created. + */ + 'created_at': string; } diff --git a/packages/arc-api-client/src/models/run-stage.ts b/packages/arc-api-client/src/models/run-stage.ts index a5e0159fe..07f7ddf73 100644 --- a/packages/arc-api-client/src/models/run-stage.ts +++ b/packages/arc-api-client/src/models/run-stage.ts @@ -17,11 +17,26 @@ // @ts-ignore import type { StageStatus } from './stage-status'; +/** + * A single stage in a run\'s workflow graph. + */ export interface RunStage { + /** + * Unique stage identifier within the run. + */ 'id': string; + /** + * Human-readable stage name. + */ 'name': string; 'status': StageStatus; + /** + * Time spent in this stage, in seconds. + */ 'duration_secs'?: number; + /** + * Node identifier in the DOT graph source. + */ 'dot_id'?: string; } diff --git a/packages/arc-api-client/src/models/run-status-response.ts b/packages/arc-api-client/src/models/run-status-response.ts index 6a5419ad7..a574e8f7f 100644 --- a/packages/arc-api-client/src/models/run-status-response.ts +++ b/packages/arc-api-client/src/models/run-status-response.ts @@ -17,11 +17,27 @@ // @ts-ignore import type { RunStatus } from './run-status'; +/** + * Current status of a run with optional error and queue position. + */ export interface RunStatusResponse { + /** + * Unique run identifier (ULID). + */ 'id': string; 'status': RunStatus; + /** + * Error message if the run failed. + */ 'error'?: string; + /** + * Position in the queue (1-based). Only present when status is `queued`. + */ 'queue_position'?: number; + /** + * Timestamp when the run was created. + */ + 'created_at': string; } diff --git a/packages/arc-api-client/src/models/run-status.ts b/packages/arc-api-client/src/models/run-status.ts index f960f0abb..834af400e 100644 --- a/packages/arc-api-client/src/models/run-status.ts +++ b/packages/arc-api-client/src/models/run-status.ts @@ -14,6 +14,9 @@ +/** + * Lifecycle status of a run. + */ export const RunStatus = { QUEUED: 'queued', diff --git a/packages/arc-api-client/src/models/run-usage.ts b/packages/arc-api-client/src/models/run-usage.ts index 9777cd4ee..ed2da007d 100644 --- a/packages/arc-api-client/src/models/run-usage.ts +++ b/packages/arc-api-client/src/models/run-usage.ts @@ -23,9 +23,18 @@ import type { UsageStage } from './usage-stage'; // @ts-ignore import type { UsageTotals } from './usage-totals'; +/** + * Complete usage breakdown for a single run. + */ export interface RunUsage { + /** + * Per-stage usage breakdown. + */ 'stages': Array; 'totals': UsageTotals; + /** + * Usage grouped by model. + */ 'by_model': Array; } diff --git a/packages/arc-api-client/src/models/run-verification-control.ts b/packages/arc-api-client/src/models/run-verification-control.ts index ac413ab99..6f78ca2e9 100644 --- a/packages/arc-api-client/src/models/run-verification-control.ts +++ b/packages/arc-api-client/src/models/run-verification-control.ts @@ -20,8 +20,17 @@ import type { VerificationStatus } from './verification-status'; // @ts-ignore import type { VerificationType } from './verification-type'; +/** + * A verification control result within a run. + */ export interface RunVerificationControl { + /** + * Human-readable control name. + */ 'name': string; + /** + * Short description of what the control verifies. + */ 'description': string; 'type'?: VerificationType; 'status': VerificationStatus; diff --git a/packages/arc-api-client/src/models/run-verification.ts b/packages/arc-api-client/src/models/run-verification.ts index fb775239b..0b86a6c35 100644 --- a/packages/arc-api-client/src/models/run-verification.ts +++ b/packages/arc-api-client/src/models/run-verification.ts @@ -20,10 +20,22 @@ import type { RunVerificationControl } from './run-verification-control'; // @ts-ignore import type { VerificationStatus } from './verification-status'; +/** + * Verification results for a category within a run. + */ export interface RunVerification { + /** + * Category name. + */ 'name': string; + /** + * The guiding question for this verification category. + */ 'question': string; 'status': VerificationStatus; + /** + * Individual control results within this category. + */ 'controls': Array; } diff --git a/packages/arc-api-client/src/models/save-query-request.ts b/packages/arc-api-client/src/models/save-query-request.ts index 115eb2d22..6be25cb8e 100644 --- a/packages/arc-api-client/src/models/save-query-request.ts +++ b/packages/arc-api-client/src/models/save-query-request.ts @@ -14,8 +14,17 @@ +/** + * Request body for creating or updating a saved query. + */ export interface SaveQueryRequest { + /** + * Human-readable query name. + */ 'name': string; + /** + * SQL query text. + */ 'sql': string; } diff --git a/packages/arc-api-client/src/models/saved-query.ts b/packages/arc-api-client/src/models/saved-query.ts index d4289b9fa..91ed2cfe7 100644 --- a/packages/arc-api-client/src/models/saved-query.ts +++ b/packages/arc-api-client/src/models/saved-query.ts @@ -14,9 +14,29 @@ +/** + * A saved SQL query for the insights editor. + */ export interface SavedQuery { + /** + * Unique query identifier. + */ 'id': string; + /** + * Human-readable query name. + */ 'name': string; + /** + * SQL query text. + */ 'sql': string; + /** + * Timestamp when the query was saved. + */ + 'created_at': string; + /** + * Timestamp when the query was last modified. + */ + 'updated_at'?: string; } diff --git a/packages/arc-api-client/src/models/setting-field-type.ts b/packages/arc-api-client/src/models/setting-field-type.ts index 7a04f3d02..d830df867 100644 --- a/packages/arc-api-client/src/models/setting-field-type.ts +++ b/packages/arc-api-client/src/models/setting-field-type.ts @@ -14,6 +14,9 @@ +/** + * Input type for a setting field. + */ export const SettingFieldType = { TEXT: 'text', diff --git a/packages/arc-api-client/src/models/setting-field.ts b/packages/arc-api-client/src/models/setting-field.ts index db8256458..3f33ffb67 100644 --- a/packages/arc-api-client/src/models/setting-field.ts +++ b/packages/arc-api-client/src/models/setting-field.ts @@ -17,12 +17,30 @@ // @ts-ignore import type { SettingFieldType } from './setting-field-type'; +/** + * A single configurable setting within a group. + */ export interface SettingField { + /** + * Machine-readable setting key. + */ 'key': string; + /** + * Human-readable label displayed in the UI. + */ 'label': string; + /** + * Current value of the setting. + */ 'value': string; 'type': SettingFieldType; + /** + * Available options for select-type fields. + */ 'options'?: Array; + /** + * Additional help text for the setting. + */ 'description'?: string; } diff --git a/packages/arc-api-client/src/models/setting-group.ts b/packages/arc-api-client/src/models/setting-group.ts index 27655d4c8..f4a3d254a 100644 --- a/packages/arc-api-client/src/models/setting-group.ts +++ b/packages/arc-api-client/src/models/setting-group.ts @@ -17,10 +17,25 @@ // @ts-ignore import type { SettingField } from './setting-field'; +/** + * A logical group of related settings. + */ export interface SettingGroup { + /** + * Machine-readable group identifier. + */ 'id': string; + /** + * Human-readable group name. + */ 'name': string; + /** + * Prose description of the settings group. + */ 'description': string; + /** + * Settings within this group. + */ 'fields': Array; } diff --git a/packages/arc-api-client/src/models/sibling-control.ts b/packages/arc-api-client/src/models/sibling-control.ts index 3b3d81c01..28bf29a17 100644 --- a/packages/arc-api-client/src/models/sibling-control.ts +++ b/packages/arc-api-client/src/models/sibling-control.ts @@ -20,8 +20,17 @@ import type { VerificationMode } from './verification-mode'; // @ts-ignore import type { VerificationType } from './verification-type'; +/** + * Summary of a sibling verification control in the same category. + */ export interface SiblingControl { + /** + * Human-readable control name. + */ 'name': string; + /** + * URL-safe slug. + */ 'slug': string; 'type'?: VerificationType; 'mode'?: VerificationMode; diff --git a/packages/arc-api-client/src/models/smoothness-rating.ts b/packages/arc-api-client/src/models/smoothness-rating.ts index 5b685039d..2b86c04ba 100644 --- a/packages/arc-api-client/src/models/smoothness-rating.ts +++ b/packages/arc-api-client/src/models/smoothness-rating.ts @@ -14,6 +14,9 @@ +/** + * Qualitative assessment of how smoothly a run executed. + */ export const SmoothnessRating = { EFFORTLESS: 'effortless', diff --git a/packages/arc-api-client/src/models/stage-status.ts b/packages/arc-api-client/src/models/stage-status.ts index bef6f5fbf..637df68f6 100644 --- a/packages/arc-api-client/src/models/stage-status.ts +++ b/packages/arc-api-client/src/models/stage-status.ts @@ -14,6 +14,9 @@ +/** + * Execution status of a workflow stage. + */ export const StageStatus = { COMPLETED: 'completed', diff --git a/packages/arc-api-client/src/models/stage-turn.ts b/packages/arc-api-client/src/models/stage-turn.ts index 10f4a9df6..7e8e9ca7a 100644 --- a/packages/arc-api-client/src/models/stage-turn.ts +++ b/packages/arc-api-client/src/models/stage-turn.ts @@ -13,22 +13,23 @@ */ +// May contain unused imports in some cases +// @ts-ignore +import type { AssistantStageTurn } from './assistant-stage-turn'; +// May contain unused imports in some cases +// @ts-ignore +import type { SystemStageTurn } from './system-stage-turn'; +// May contain unused imports in some cases +// @ts-ignore +import type { ToolStageTurn } from './tool-stage-turn'; // May contain unused imports in some cases // @ts-ignore import type { ToolUse } from './tool-use'; -export interface StageTurn { - 'kind': StageTurnKindEnum; - 'content'?: string; - 'tools'?: Array; -} - -export const StageTurnKindEnum = { - SYSTEM: 'system', - ASSISTANT: 'assistant', - TOOL: 'tool' -} as const; - -export type StageTurnKindEnum = typeof StageTurnKindEnum[keyof typeof StageTurnKindEnum]; +/** + * @type StageTurn + * A single turn in a stage conversation — a system prompt, assistant response, or tool invocation block. + */ +export type StageTurn = { kind: 'assistant' } & AssistantStageTurn | { kind: 'system' } & SystemStageTurn | { kind: 'tool' } & ToolStageTurn; diff --git a/packages/arc-api-client/src/models/start-run-request.ts b/packages/arc-api-client/src/models/start-run-request.ts index d1c1c9379..4f748c144 100644 --- a/packages/arc-api-client/src/models/start-run-request.ts +++ b/packages/arc-api-client/src/models/start-run-request.ts @@ -14,7 +14,13 @@ +/** + * Request body for starting a new run from a DOT graph source. + */ export interface StartRunRequest { + /** + * DOT language source defining the workflow graph. + */ 'dot_source': string; } diff --git a/packages/arc-api-client/src/models/start-run-response.ts b/packages/arc-api-client/src/models/start-run-response.ts index 0ac9d1c19..b80a7cd2e 100644 --- a/packages/arc-api-client/src/models/start-run-response.ts +++ b/packages/arc-api-client/src/models/start-run-response.ts @@ -13,8 +13,24 @@ */ +// May contain unused imports in some cases +// @ts-ignore +import type { RunStatus } from './run-status'; +/** + * Response returned after successfully queuing a new run. + */ export interface StartRunResponse { + /** + * Unique run identifier (ULID). + */ 'id': string; + 'status': RunStatus; + /** + * Timestamp when the run was created. + */ + 'created_at': string; } + + diff --git a/packages/arc-api-client/src/models/steer-request.ts b/packages/arc-api-client/src/models/steer-request.ts index 48a65b9ec..f46df5725 100644 --- a/packages/arc-api-client/src/models/steer-request.ts +++ b/packages/arc-api-client/src/models/steer-request.ts @@ -14,9 +14,21 @@ +/** + * Request body for sending inline steering guidance to a running agent. + */ export interface SteerRequest { + /** + * File path to target with the guidance. + */ 'file': string; + /** + * Line number in the file to annotate. + */ 'line': number; + /** + * Guidance text for the agent. + */ 'guidance': string; } diff --git a/packages/arc-api-client/src/models/steer-run-response.ts b/packages/arc-api-client/src/models/steer-run-response.ts new file mode 100644 index 000000000..069577eb6 --- /dev/null +++ b/packages/arc-api-client/src/models/steer-run-response.ts @@ -0,0 +1,26 @@ +/* tslint:disable */ +/* eslint-disable */ +/** + * Arc Run API + * HTTP API for managing Arc workflow run executions. + * + * The version of the OpenAPI document: 0.1.0 + * + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + + + +/** + * Acknowledgement that the steering guidance was accepted for delivery. + */ +export interface SteerRunResponse { + /** + * Whether the steering guidance was accepted. + */ + 'accepted': boolean; +} + diff --git a/packages/arc-api-client/src/models/submit-answer-request.ts b/packages/arc-api-client/src/models/submit-answer-request.ts index d921a4555..cefa55f4e 100644 --- a/packages/arc-api-client/src/models/submit-answer-request.ts +++ b/packages/arc-api-client/src/models/submit-answer-request.ts @@ -14,8 +14,17 @@ +/** + * Request body for submitting an answer to a pending question. + */ export interface SubmitAnswerRequest { + /** + * Freeform answer text. + */ 'value': string; + /** + * Key of the selected option (for multiple-choice questions). + */ 'selected_option_key'?: string; } diff --git a/packages/arc-api-client/src/models/submit-answer-response.ts b/packages/arc-api-client/src/models/submit-answer-response.ts index 31cfeb650..bf683b8f3 100644 --- a/packages/arc-api-client/src/models/submit-answer-response.ts +++ b/packages/arc-api-client/src/models/submit-answer-response.ts @@ -14,7 +14,13 @@ +/** + * Response indicating whether the submitted answer was accepted. + */ export interface SubmitAnswerResponse { + /** + * Whether the answer was accepted. Returns false if the question no longer exists. + */ 'accepted': boolean; } diff --git a/packages/arc-api-client/src/models/system-stage-turn.ts b/packages/arc-api-client/src/models/system-stage-turn.ts new file mode 100644 index 000000000..6d5007372 --- /dev/null +++ b/packages/arc-api-client/src/models/system-stage-turn.ts @@ -0,0 +1,41 @@ +/* tslint:disable */ +/* eslint-disable */ +/** + * Arc Run API + * HTTP API for managing Arc workflow run executions. + * + * The version of the OpenAPI document: 0.1.0 + * + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + + +// May contain unused imports in some cases +// @ts-ignore +import type { ToolUse } from './tool-use'; + +/** + * A system prompt turn that sets the stage\'s instructions. + */ +export interface SystemStageTurn { + 'kind': SystemStageTurnKindEnum; + /** + * System prompt text. + */ + 'content': string; + /** + * Tool invocations (always empty for system turns). + */ + 'tools'?: Array; +} + +export const SystemStageTurnKindEnum = { + SYSTEM: 'system' +} as const; + +export type SystemStageTurnKindEnum = typeof SystemStageTurnKindEnum[keyof typeof SystemStageTurnKindEnum]; + + diff --git a/packages/arc-api-client/src/models/tool-stage-turn.ts b/packages/arc-api-client/src/models/tool-stage-turn.ts new file mode 100644 index 000000000..45882d1c5 --- /dev/null +++ b/packages/arc-api-client/src/models/tool-stage-turn.ts @@ -0,0 +1,41 @@ +/* tslint:disable */ +/* eslint-disable */ +/** + * Arc Run API + * HTTP API for managing Arc workflow run executions. + * + * The version of the OpenAPI document: 0.1.0 + * + * + * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech). + * https://openapi-generator.tech + * Do not edit the class manually. + */ + + +// May contain unused imports in some cases +// @ts-ignore +import type { ToolUse } from './tool-use'; + +/** + * A tool invocation turn containing one or more tool calls. + */ +export interface ToolStageTurn { + 'kind': ToolStageTurnKindEnum; + /** + * Optional text content (usually null for tool turns). + */ + 'content'?: string; + /** + * Tool invocations executed in this turn. + */ + 'tools': Array; +} + +export const ToolStageTurnKindEnum = { + TOOL: 'tool' +} as const; + +export type ToolStageTurnKindEnum = typeof ToolStageTurnKindEnum[keyof typeof ToolStageTurnKindEnum]; + + diff --git a/packages/arc-api-client/src/models/usage-by-model.ts b/packages/arc-api-client/src/models/usage-by-model.ts index e679290b3..5d2d8c325 100644 --- a/packages/arc-api-client/src/models/usage-by-model.ts +++ b/packages/arc-api-client/src/models/usage-by-model.ts @@ -14,11 +14,29 @@ +/** + * Usage statistics grouped by model. + */ export interface UsageByModel { + /** + * Model slug. + */ 'model': string; + /** + * Number of stages that used this model. + */ 'stages': number; + /** + * Total input tokens for this model. + */ 'input_tokens': number; + /** + * Total output tokens for this model. + */ 'output_tokens': number; + /** + * Total cost in USD for this model. + */ 'cost': number; } diff --git a/packages/arc-api-client/src/models/usage-stage.ts b/packages/arc-api-client/src/models/usage-stage.ts index c4911ee70..a89f2814e 100644 --- a/packages/arc-api-client/src/models/usage-stage.ts +++ b/packages/arc-api-client/src/models/usage-stage.ts @@ -14,12 +14,33 @@ +/** + * Token and cost usage for a single stage within a run. + */ export interface UsageStage { + /** + * Human-readable stage name. + */ 'stage': string; + /** + * Model slug used for this stage. + */ 'model': string; + /** + * Number of input tokens consumed. + */ 'input_tokens': number; + /** + * Number of output tokens generated. + */ 'output_tokens': number; + /** + * Wall-clock runtime in seconds. + */ 'runtime_secs': number; + /** + * Cost in USD for this stage. + */ 'cost': number; } diff --git a/packages/arc-api-client/src/models/usage-totals.ts b/packages/arc-api-client/src/models/usage-totals.ts index 10aa97c88..5eb9678f2 100644 --- a/packages/arc-api-client/src/models/usage-totals.ts +++ b/packages/arc-api-client/src/models/usage-totals.ts @@ -14,10 +14,25 @@ +/** + * Aggregate usage totals across all stages of a run. + */ export interface UsageTotals { + /** + * Total wall-clock runtime in seconds. + */ 'runtime_secs': number; + /** + * Total input tokens consumed. + */ 'input_tokens': number; + /** + * Total output tokens generated. + */ 'output_tokens': number; + /** + * Total cost in USD. + */ 'cost': number; } diff --git a/packages/arc-api-client/src/models/user-response.ts b/packages/arc-api-client/src/models/user-response.ts index 39079d607..50e005f9f 100644 --- a/packages/arc-api-client/src/models/user-response.ts +++ b/packages/arc-api-client/src/models/user-response.ts @@ -14,7 +14,13 @@ +/** + * Information about the authenticated user. + */ export interface UserResponse { + /** + * User\'s login identifier (e.g. GitHub username). + */ 'login': string; } diff --git a/packages/arc-api-client/src/models/verification-category.ts b/packages/arc-api-client/src/models/verification-category.ts index 89fd99ecb..f9ce1804b 100644 --- a/packages/arc-api-client/src/models/verification-category.ts +++ b/packages/arc-api-client/src/models/verification-category.ts @@ -17,9 +17,21 @@ // @ts-ignore import type { VerificationControl } from './verification-control'; +/** + * A group of related verification controls. + */ export interface VerificationCategory { + /** + * Category name. + */ 'name': string; + /** + * Guiding question for the category. + */ 'question': string; + /** + * Verification controls in this category. + */ 'controls': Array; } diff --git a/packages/arc-api-client/src/models/verification-control.ts b/packages/arc-api-client/src/models/verification-control.ts index cb10de256..ccf584769 100644 --- a/packages/arc-api-client/src/models/verification-control.ts +++ b/packages/arc-api-client/src/models/verification-control.ts @@ -23,14 +23,35 @@ import type { VerificationMode } from './verification-mode'; // @ts-ignore import type { VerificationType } from './verification-type'; +/** + * A verification control within a category, with performance metrics. + */ export interface VerificationControl { + /** + * Human-readable control name. + */ 'name': string; + /** + * URL-safe slug for API lookups. + */ 'slug': string; + /** + * Short description of what the control verifies. + */ 'description': string; 'type'?: VerificationType; 'mode'?: VerificationMode; + /** + * F1 score of the control\'s AI evaluator. + */ 'f1'?: number; + /** + * Pass@1 rate — probability of passing on the first evaluation. + */ 'pass_at_1'?: number; + /** + * Recent evaluation results (newest first). + */ 'evaluations'?: Array; } diff --git a/packages/arc-api-client/src/models/verification-detail-response.ts b/packages/arc-api-client/src/models/verification-detail-response.ts index 40100225e..4e3358075 100644 --- a/packages/arc-api-client/src/models/verification-detail-response.ts +++ b/packages/arc-api-client/src/models/verification-detail-response.ts @@ -29,11 +29,20 @@ import type { RecentControlResult } from './recent-control-result'; // @ts-ignore import type { SiblingControl } from './sibling-control'; +/** + * Complete detail view of a verification control with performance, examples, and recent results. + */ export interface VerificationDetailResponse { 'control': ControlInfo; 'performance': ControlPerformance; 'control_detail': ControlDetail; + /** + * Recent evaluation results across runs. + */ 'recent_results': Array; + /** + * Other controls in the same category. + */ 'siblings': Array; } diff --git a/packages/arc-api-client/src/models/verification-mode.ts b/packages/arc-api-client/src/models/verification-mode.ts index e0929f233..7ee77d7c8 100644 --- a/packages/arc-api-client/src/models/verification-mode.ts +++ b/packages/arc-api-client/src/models/verification-mode.ts @@ -14,6 +14,9 @@ +/** + * Operational mode of a verification control. + */ export const VerificationMode = { ACTIVE: 'active', diff --git a/packages/arc-api-client/src/models/verification-status.ts b/packages/arc-api-client/src/models/verification-status.ts index b8ca0b67f..7debfc41d 100644 --- a/packages/arc-api-client/src/models/verification-status.ts +++ b/packages/arc-api-client/src/models/verification-status.ts @@ -14,6 +14,9 @@ +/** + * Result status of a verification control evaluation. + */ export const VerificationStatus = { PASS: 'pass', diff --git a/packages/arc-api-client/src/models/verification-type.ts b/packages/arc-api-client/src/models/verification-type.ts index 12129534f..ea1744fde 100644 --- a/packages/arc-api-client/src/models/verification-type.ts +++ b/packages/arc-api-client/src/models/verification-type.ts @@ -14,6 +14,9 @@ +/** + * The evaluation method used by a verification control. + */ export const VerificationType = { AI: 'ai', diff --git a/packages/arc-api-client/src/models/workflow-detail.ts b/packages/arc-api-client/src/models/workflow-detail.ts index 0f2d3fa7d..9c289ee46 100644 --- a/packages/arc-api-client/src/models/workflow-detail.ts +++ b/packages/arc-api-client/src/models/workflow-detail.ts @@ -14,12 +14,33 @@ +/** + * Full detail of a workflow definition including graph and configuration. + */ export interface WorkflowDetail { + /** + * Human-readable workflow title. + */ 'title': string; + /** + * URL-safe slug used in API paths. + */ 'slug': string; + /** + * DOT graph filename. + */ 'filename': string; + /** + * Prose description of what the workflow does. + */ 'description': string; + /** + * TOML configuration content for the workflow. + */ 'config': string; + /** + * DOT language source defining the workflow graph. + */ 'graph': string; } diff --git a/packages/arc-api-client/src/models/workflow-list-item.ts b/packages/arc-api-client/src/models/workflow-list-item.ts index e022f45d0..3c46acc3f 100644 --- a/packages/arc-api-client/src/models/workflow-list-item.ts +++ b/packages/arc-api-client/src/models/workflow-list-item.ts @@ -14,12 +14,33 @@ +/** + * Summary of a workflow shown in list views. + */ export interface WorkflowListItem { + /** + * Human-readable workflow name. + */ 'name': string; + /** + * URL-safe slug used in API paths. + */ 'slug': string; + /** + * DOT graph filename. + */ 'filename': string; + /** + * Human-readable relative timestamp of the last run. + */ 'last_run'?: string; + /** + * Cron-like schedule expression, if the workflow runs on a schedule. + */ 'schedule'?: string; + /** + * Human-readable relative timestamp of the next scheduled run. + */ 'next_run'?: string; }