@contraagent/api 0.6.2 → 0.7.1

package/src/schema.ts

@@ -162,6 +162,26 @@ export type paths = {
         patch?: never;
         trace?: never;
     };
+    "/api/runs/{run}/forecast": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Api Forecast
+         * @description The tasks the run is expected to create and has not yet, from the run of the same flow that finished last before it started; a display only.
+         */
+        get: operations["api_forecast_api_runs__run__forecast_get"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/runs/{run}/definitions": {
         parameters: {
             query?: never;
@@ -609,14 +629,17 @@ export type components = {
             executor?: "agent" | "python";
             /**
              * Params
-             * @description the task's params that are strings, numbers or booleans; an earlier task's output is one of `inputs`
+             * @description the task's params that are strings, numbers or booleans
              */
             params?: {
                 [key: string]: string | number | boolean;
             };
             /** Outputs */
             outputs?: components["schemas"]["ContractSpec"][];
-            /** Inputs */
+            /**
+             * Inputs
+             * @description its input contracts (`InputContract`, from a `TaskAdapter` of the engine), checked before it starts
+             */
             inputs?: components["schemas"]["ContractSpec"][];
         } & {
             [key: string]: unknown;
@@ -791,8 +814,8 @@ export type components = {
          * DeferralCause
          * @description Why a task was deferred, as data (`Deferral.cause`). `cause`: `deadline`,
          *     `grace_window` (past the deadline's grace window), `cannot_finish` (`need_s`, `left_s`),
-         *     `dependency_not_queued`, `dependency_deferred` (a task whose output it reads was
-         *     deferred: `dependency`), `rest` (the credential of every hop it could take rests:
+         *     `dependency_not_queued`, `dependency_deferred` (written by releases before 0.7: a task
+         *     whose output it read was deferred, `dependency`), `rest` (the credential of every hop it could take rests:
          *     `rests`), or a runner's own name. A field a cause does not have is left unset, and
          *     `deferred.jsonl` records only the fields set.
          */
@@ -822,7 +845,7 @@ export type components = {
             rests?: components["schemas"]["SkippedHop"][];
             /**
              * Dependency
-             * @description `dependency_deferred`: the key of the deferred task whose output it reads
+             * @description `dependency_deferred` (releases before 0.7): the key of the deferred task whose output it read
              */
             dependency?: string | null;
         };
@@ -840,7 +863,10 @@ export type components = {
         } & {
             [key: string]: unknown;
         };
-        /** DownstreamTask */
+        /**
+         * DownstreamTask
+         * @description A later task: one given from this task, waiting for it, or created from it.
+         */
         DownstreamTask: {
             /** Key */
             key: string;
@@ -853,6 +879,11 @@ export type components = {
              * @enum {string}
              */
             executor: "agent" | "python";
+            /**
+             * Lineage
+             * @description how it is joined to this task, in the order `given_from`, `after`, `created_from`
+             */
+            lineage?: ("given_from" | "after" | "created_from")[];
         };
         /**
          * DroppedRoute
@@ -1020,8 +1051,129 @@ export type components = {
              * @description `<type>: <message>` of what it raised (or what cancelling it raised); else null
              */
             error?: string | null;
+            /** @description for one that raised: where the exception left its own code (mostly the `await` that failed), its file as `flow` gives it; else null */
+            raised_at?: components["schemas"]["Frame"] | null;
+            /**
+             * Raised By
+             * @description for one that raised: the key of the failed task the exception is, the same in every flow call it passes through; null for an exception of flow code's own
+             */
+            raised_by?: string | null;
             /** @description its own deadline, for a flow call started through `time_box`; else null */
             time_box?: components["schemas"]["TimeBoxRecord"] | null;
+            /**
+             * Unawaited
+             * @description for a top flow call that ended: the keys of the tasks created in it or in the flow calls it started that nothing awaited, waited for with `after=` or returned; they ran all the same
+             */
+            unawaited?: string[];
+        };
+        /**
+         * Forecast
+         * @description The tasks the run is expected to create and has not yet, with their wall time and
+         *     cost, from the run of the same flow that finished last before it started (`run.json`
+         *     `flow`). A display only: the schedule never reads it, and a run that creates fewer or
+         *     more tasks than the earlier run is no error.
+         */
+        Forecast: {
+            /**
+             * Flow
+             * @description `module.qualname` of the run's top flow (`run.json` `flow`); empty for a run of an earlier release
+             */
+            flow: string;
+            /**
+             * Earlier Run
+             * @description the run it reads; empty when no run of the same flow finished before this one started
+             */
+            earlier_run: string;
+            /**
+             * Earlier Finished At
+             * @description when the earlier run finished, ISO 8601; empty when there is none
+             */
+            earlier_finished_at: string;
+            /**
+             * Entries
+             * @description by tail key, in the order the earlier run created the first task of each
+             */
+            entries: components["schemas"]["ForecastEntry"][];
+            /**
+             * Remaining
+             * @description the entries' `remaining`, summed
+             */
+            remaining: number;
+            /**
+             * Wall S
+             * @description the entries' `wall_s`, summed
+             */
+            wall_s: number;
+            /**
+             * Cost Usd
+             * @description the entries' `cost_usd`, summed; null when none has one
+             */
+            cost_usd: number | null;
+        };
+        /**
+         * ForecastEntry
+         * @description The tasks of one tail key in the earlier run the forecast reads, and how many of them
+         *     this run has created. A tail key is the flow path's function names, the kind, and the
+         *     passes of the loops around it, each capped at 3.
+         */
+        ForecastEntry: {
+            /**
+             * Kind
+             * @description the kind of the earlier run's first task of it
+             */
+            kind: string;
+            /**
+             * Group
+             * @description the group its kind is drawn in (`PlanGroup.id`)
+             */
+            group: string;
+            /**
+             * Flow
+             * @description the function names of its flow path, outermost first
+             */
+            flow: string[];
+            /**
+             * Passes
+             * @description the passes of the loops around it, outermost first, each capped at 3 (3: the third pass and later); null for a loop whose pass was not recorded
+             */
+            passes: (number | null)[];
+            /**
+             * Expected
+             * @description the tasks of it the earlier run created
+             */
+            expected: number;
+            /**
+             * Created
+             * @description the tasks of it this run has created
+             */
+            created: number;
+            /**
+             * Remaining
+             * @description `expected` less `created`, never below 0
+             */
+            remaining: number;
+            /**
+             * Wall S
+             * @description the wall time of the `remaining` tasks, at the earlier run's mean per task (every attempt counted)
+             */
+            wall_s: number;
+            /**
+             * Cost Usd
+             * @description the cost of the `remaining` tasks in USD, at the earlier run's mean per task; null when the earlier run reported none
+             */
+            cost_usd: number | null;
+        };
+        /**
+         * ForecastMessage
+         * @description The forecast, sent when it changed: a task the run creates takes one off it.
+         */
+        ForecastMessage: {
+            /**
+             * Event
+             * @constant
+             */
+            event: "forecast";
+            data: components["schemas"]["Forecast"];
         };
         /**
          * Frame
@@ -1372,7 +1524,7 @@ export type components = {
              * Stop
              * @enum {string}
              */
-            stop: "completed" | "timeout" | "max_turns" | "budget" | "context_budget" | "stalled" | "auth_failed" | "api_error" | "rate_limited" | "refused" | "aborted" | "denied" | "error" | "no_output" | "launch_failed" | "invalid_output" | "invalid_input" | "credential_mismatch" | "skipped" | "partial";
+            stop: "completed" | "timeout" | "max_turns" | "budget" | "context_budget" | "stalled" | "auth_failed" | "api_error" | "rate_limited" | "refused" | "aborted" | "denied" | "error" | "no_output" | "launch_failed" | "invalid_output" | "invalid_input" | "credential_mismatch" | "skipped" | "partial" | "cancelled";
             /** Ok */
             ok: boolean;
             /**
@@ -1410,6 +1562,12 @@ export type components = {
             unread_events?: {
                 [key: string]: number;
             };
+            /**
+             * Usage Unknown
+             * @default
+             * @enum {string}
+             */
+            usage_unknown?: "" | "calls" | "tokens";
             changes?: components["schemas"]["Changes"] | null;
             /** Context Budget */
             context_budget?: number | null;
@@ -1423,6 +1581,10 @@ export type components = {
              * @default
              */
             fingerprint?: string;
+            /** Fingerprint Parts */
+            fingerprint_parts?: {
+                [key: string]: string;
+            };
             /**
              * Outside
              * @default
@@ -1433,6 +1595,11 @@ export type components = {
              * @default
              */
             rerun?: string;
+            /**
+             * Output Of After
+             * @default
+             */
+            output_of_after?: string;
             /** Flow Call */
             flow_call?: string | null;
             /**
@@ -1897,6 +2064,11 @@ export type components = {
             skipped: number;
             /** Blocked */
             blocked: number;
+            /**
+             * Cancelled
+             * @default 0
+             */
+            cancelled?: number;
         };
         /** PlanMessage */
         PlanMessage: {
@@ -1947,7 +2119,7 @@ export type components = {
             priority?: number;
             /**
              * Credential
-             * @description the credential its task call names (`credential=`), which every route of its kind ran it as; empty when it names none, or a run-wide override outranks it
+             * @description the credential its call options name (`.options(credential=)`), which every route of its kind ran it as; empty when it names none, or a run-wide override outranks it
              * @default
              */
             credential?: string;
@@ -1964,7 +2136,7 @@ export type components = {
             flow?: components["schemas"]["Frame"][];
             /**
              * Created From
-             * @description keys whose results its flow call had received when it created it
+             * @description keys of the results that reached its flow call between that flow call's previous resume and the one in which it created the task
              */
             created_from?: string[];
             /**
@@ -1972,6 +2144,18 @@ export type components = {
              * @description the id of the flow call that created it; null for a task with no origin
              */
             flow_call?: string | null;
+            /**
+             * Given From
+             * @description keys of the tasks whose outputs it was given in its params: an output, or one item of an output that is a list, whose JSON is a value of its params; shown only, never part of its fingerprint
+             */
+            given_from?: string[];
+            /**
+             * Input Files
+             * @description the input files among its params, as its task call hashed them: `param` (its place in the params, `notes/0`), `path` and `sha256`; absent when it has none
+             */
+            input_files?: {
+                [key: string]: string;
+            }[];
             /**
              * Base Kind
              * @description an implementation kind's base kind (`agent_task(implementations=)`), its group unless `groups` lists it; else empty
@@ -1982,7 +2166,7 @@ export type components = {
              * State
              * @enum {string}
              */
-            state: "pending" | "running" | "done" | "partial" | "failed" | "skipped" | "blocked";
+            state: "pending" | "running" | "done" | "partial" | "failed" | "skipped" | "blocked" | "cancelled";
             /**
              * Level
              * @description depth in the dependency graph, 0 for a task that waits for nothing
@@ -2259,7 +2443,7 @@ export type components = {
          * RunEvent
          * @description One message of /events?run=
          */
-        RunEvent: components["schemas"]["JournalMessage"] | components["schemas"]["ProcsMessage"] | components["schemas"]["PlanMessage"] | components["schemas"]["OutputsMessage"] | components["schemas"]["CursorMessage"] | components["schemas"]["PanelMessage"] | components["schemas"]["ReadyMessage"];
+        RunEvent: components["schemas"]["JournalMessage"] | components["schemas"]["ProcsMessage"] | components["schemas"]["PlanMessage"] | components["schemas"]["OutputsMessage"] | components["schemas"]["ForecastMessage"] | components["schemas"]["CursorMessage"] | components["schemas"]["PanelMessage"] | components["schemas"]["ReadyMessage"];
         /**
          * RunSummary
          * @description One run directory, as the run picker lists it.
@@ -2690,7 +2874,8 @@ export type components = {
          * @description A run's tasks (not attempts) by how they ended. `not_started`: refused for
          *     an input, or waiting behind a task that failed; `running`: running now (in a
          *     live run); `waiting`: queued in a live run; `not_run`: deferred, or queued in a
-         *     run that is no longer live (it will not run).
+         *     run that is no longer live (it will not run); `cancelled`: cancelled once no flow
+         *     call waited for it (called with `.options(cancellable=True)`).
          */
         TaskCounts: {
             /** Total */
@@ -2721,6 +2906,11 @@ export type components = {
             not_run?: number;
             /** Skipped */
             skipped: number;
+            /**
+             * Cancelled
+             * @default 0
+             */
+            cancelled?: number;
         };
         /**
          * TaskDefinition
@@ -2860,8 +3050,16 @@ export type components = {
             params: {
                 [key: string]: unknown;
             };
-            /** Inputs */
+            /**
+             * Inputs
+             * @description its input contracts (`ContractRecord.inputs`)
+             */
             inputs: components["schemas"]["ContractSpec"][];
+            /**
+             * Input Files
+             * @description the input files among its params
+             */
+            input_files?: components["schemas"]["TaskInputFile"][];
             /** Outputs */
             outputs: components["schemas"]["ContractSpec"][];
             /**
@@ -2874,6 +3072,42 @@ export type components = {
             /** Downstream */
             downstream: components["schemas"]["DownstreamTask"][];
         };
+        /**
+         * TaskInputFile
+         * @description An input file among the task's params (`plan.jsonl` `input_files`): its place in the
+         *     params, its path and the SHA-256 of its content taken at the task call, the task whose
+         *     output file it is, and its check as the task was about to start.
+         */
+        TaskInputFile: {
+            /**
+             * Param
+             * @description its place in the params: the param's name, then a list's index or a field's name (`notes/0`)
+             */
+            param: string;
+            /**
+             * Path
+             * @description as the params hold it: relative to the run's working directory, or absolute for an output file outside it
+             */
+            path: string;
+            /** Sha256 */
+            sha256: string;
+            /**
+             * Writer
+             * @description the key of the task it was given from whose output file it is; null for another file
+             */
+            writer?: string | null;
+            /**
+             * Check
+             * @enum {string}
+             */
+            check: "passed" | "refused" | "not_checked";
+            /**
+             * Reason
+             * @description for one `refused`: why, as the refusal names it; else empty
+             * @default
+             */
+            reason?: string;
+        };
         /**
          * TaskLaunch
          * @description A live launch of the task (a child process, or an in-process marker with empty plugin/model/role/cmd).
@@ -3606,7 +3840,10 @@ export type components = {
             /** Inflight */
             inflight: string[];
         };
-        /** UpstreamTask */
+        /**
+         * UpstreamTask
+         * @description An earlier task: one this task was given from, waits for, or was created from.
+         */
         UpstreamTask: {
             /** Key */
             key: string;
@@ -3621,6 +3858,11 @@ export type components = {
             executor: "agent" | "python";
             /** Outputs */
             outputs: components["schemas"]["ContractSpec"][];
+            /**
+             * Lineage
+             * @description how this task is joined to it, in the order `given_from`, `after`, `created_from`
+             */
+            lineage?: ("given_from" | "after" | "created_from")[];
         };
         /** ValidationError */
         ValidationError: {
@@ -3898,6 +4140,37 @@ export interface operations {
             };
         };
     };
+    api_forecast_api_runs__run__forecast_get: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                run: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Successful Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["Forecast"];
+                };
+            };
+            /** @description Validation Error */
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HTTPValidationError"];
+                };
+            };
+        };
+    };
     api_definitions_api_runs__run__definitions_get: {
         parameters: {
             query?: never;

package/src/types.ts

@@ -62,6 +62,9 @@ export type Loop = S['Loop'];
 export type FlowCallNode = S['FlowCallNode'];
 export type FlowState = FlowCallNode['state'];
 export type TimeBoxRecord = S['TimeBoxRecord'];
+/** The tasks a run is expected to create and has not yet, from an earlier run of its flow; a display only. */
+export type Forecast = S['Forecast'];
+export type ForecastEntry = S['ForecastEntry'];
 
 export type Outputs = S['Outputs'];
 export type OutputTally = S['OutputTally'];
@@ -87,6 +90,11 @@ export type TaskLaunch = S['TaskLaunch'];
 export type TaskIO = S['TaskIO'];
 export type UpstreamTask = S['UpstreamTask'];
 export type DownstreamTask = S['DownstreamTask'];
+/** How a task is joined to an earlier one: given its output (`given_from`), waiting for it only (`after`), created after its result (`created_from`). */
+export type Lineage = NonNullable<UpstreamTask['lineage']>[number];
+/** An input file among a task's params, with the task whose output it is and its check at the start. */
+export type TaskInputFile = S['TaskInputFile'];
+export type InputFileCheck = TaskInputFile['check'];
 
 // --- transcripts -----------------------------------------------------------