@skastr0/prism-linux-x64 0.5.1 → 0.8.0

package/types/workflows.d.ts

@@ -1,8 +1,10 @@
-import { Effect, Schema } from "effect";
-import type { Either } from "effect/Either";
-import type { ParseError } from "effect/ParseResult";
+import { Effect, Result, Schema, type SchemaAST } from "effect";
+import { type WorkflowEffortCapabilityFor, type WorkflowEffortWorkerHarnessId, type WorkflowWorkerHarnessId } from "./lowerer-capabilities.js";
 import { type WorkflowRuntimeError } from "./workflow-errors.js";
+import { type WorkflowSchedule } from "./workflow-scheduler/schedule.js";
+import { type JevEntry, type JevQuestions, type JevRequest, type JevResult, type JevResultCodec } from "./jev.js";
 export type { WorkflowRuntimeError } from "./workflow-errors.js";
+export { WORKFLOW_SCHEDULE_MISSED_RUN_POLICIES, WORKFLOW_SCHEDULE_OVERLAP_POLICIES, isWorkflowSchedule, parseWorkflowSchedule, type WorkflowSchedule, type WorkflowScheduleMissedRuns, type WorkflowScheduleOverlap, } from "./workflow-scheduler/schedule.js";
 export interface WorkflowModelRef {
     readonly modelspace?: string;
     readonly profile?: string;
@@ -42,9 +44,21 @@ export interface WorkflowValidationSummary {
     readonly tasks: ReadonlyArray<WorkflowTaskSummary>;
     readonly dynamic: boolean;
 }
-export type WorkflowOutputSchema = Schema.Schema.AnyNoContext;
+/**
+ * Constraint for a workflow task's output schema.
+ *
+ * The load-bearing part is `never, never`: a task output schema must decode and
+ * encode without services. `Type` stays `unknown` so the generic bound cannot
+ * silently turn decoded values into `any`.
+ *
+ * `WorkflowFinishOptions` consumes `Output` in contravariant callback positions,
+ * which makes a task invariant in its output type. A heterogeneous task tuple is
+ * therefore accepted only where the output type is erased, which happens at
+ * `AnyWorkflowTask` rather than here.
+ */
+export type WorkflowOutputSchema = Schema.Codec<unknown, unknown, never, never>;
 export type WorkflowFinishCriterionError = Error;
-export type WorkflowWorkerId = "amp-code" | "antigravity-cli" | "claude-code" | "codex-cli" | "cursor" | "devin" | "grok" | "hermes" | "kimi-code" | "opencode" | "opencode2" | "omp";
+export type WorkflowWorkerId = WorkflowWorkerHarnessId;
 /**
  * Per-harness model identifier map. Empty in core so `worker.model` stays
  * `string` until `prism workflow refresh-harness-types` augments keys with
@@ -60,14 +74,56 @@ export interface WorkflowHarnessModelMap {
 export interface WorkflowHarnessCatalogModelMap {
 }
 /**
- * Amp reasoning-effort ladders from the catalog. Empty in core; refresh
- * augments `"amp-code"` for `worker.effort`.
+ * Model-specific reasoning-effort ladders from installed CLI catalogs.
+ * Fixed CLI values come from `LOWERER_CAPABILITIES` and are not discovered.
+ * Refresh augments only catalog-backed workers.
  */
 export interface WorkflowHarnessEffortMap {
 }
+/**
+ * Discovered Amp orb projects (`amp projects list --json`). Empty in core;
+ * refresh augments `"amp-orb"` so `worker.project` narrows to known projects.
+ */
+export interface WorkflowHarnessProjectMap {
+}
+export type WorkflowHarnessProject<W extends WorkflowWorkerId> = W extends keyof WorkflowHarnessProjectMap ? WorkflowHarnessProjectMap[W] : string;
+/**
+ * Discovered Amp runners (`list_runners`, captured by
+ * `refresh-harness-types --discover-amp-runners`). Empty in core; refresh
+ * augments one key per runner whose value is the union of the directories
+ * that runner serves.
+ */
+export interface WorkflowHarnessRunnerDirMap {
+}
+/**
+ * The `amp-runner` target: with a runner snapshot, a discriminated union over
+ * the live runner ids so `runnerDir` follows the chosen id (a directory
+ * another runner serves is a type error); without one, both stay plain
+ * strings. `validate` enforces the pair again at load time.
+ */
+export type AmpRunnerTargetOptions = keyof WorkflowHarnessRunnerDirMap extends never ? {
+    /** Runner id from `amp --no-tui --runner-id <id>` (`--executor runner:<id>`). */
+    readonly runnerId: string;
+    /** Absolute directory the runner serves (`--runner-dir`); defaults to the runner's start directory. */
+    readonly runnerDir?: string;
+} : {
+    [R in keyof WorkflowHarnessRunnerDirMap]: {
+        readonly runnerId: R;
+        readonly runnerDir?: WorkflowHarnessRunnerDirMap[R];
+    };
+}[keyof WorkflowHarnessRunnerDirMap];
 export type WorkflowHarnessModel<W extends WorkflowWorkerId> = (W extends keyof WorkflowHarnessModelMap ? WorkflowHarnessModelMap[W] : string) | WorkflowModelProfileRef;
 export type WorkflowHarnessCatalogModel<W extends WorkflowWorkerId> = W extends keyof WorkflowHarnessCatalogModelMap ? WorkflowHarnessCatalogModelMap[W] : string;
-export type WorkflowHarnessEffort<W extends WorkflowWorkerId> = W extends keyof WorkflowHarnessEffortMap ? WorkflowHarnessEffortMap[W] : string;
+type WorkflowHarnessEffortForCapability<W extends WorkflowWorkerId, Capability> = Capability extends {
+    readonly kind: "fixed";
+    readonly values: readonly (infer Value extends string)[];
+} ? Value : Capability extends {
+    readonly kind: "catalog";
+} ? W extends keyof WorkflowHarnessEffortMap ? WorkflowHarnessEffortMap[W] : never : never;
+type WorkflowHarnessEffortForOne<W extends WorkflowWorkerId> = WorkflowHarnessEffortForCapability<W, NonNullable<WorkflowEffortCapabilityFor<W>>>;
+/** Harness-bound effort values; catalog-backed values require a refreshed type map. */
+export type WorkflowHarnessEffort<W extends WorkflowWorkerId> = W extends WorkflowWorkerId ? WorkflowHarnessEffortForOne<W> : never;
+export declare const workflowWorkerSupportsEffort: (worker: unknown) => worker is WorkflowEffortWorkerHarnessId;
 export type WorkflowPermissionMode = "legacy" | "permissive" | "restricted" | "interactive" | "sandbox-read-only" | "sandbox-workspace-write" | "full-access";
 /** Workers with no sandbox flag and no per-invocation allowlist. */
 export type WorkflowDialPermissionMode = Extract<WorkflowPermissionMode, "legacy" | "permissive" | "full-access">;
@@ -77,8 +133,31 @@ export type CodexWorkflowPermissionMode = Extract<WorkflowPermissionMode, "legac
 export type CursorWorkflowPermissionMode = Extract<WorkflowPermissionMode, "legacy" | "permissive" | "full-access" | "sandbox-workspace-write">;
 export type DevinWorkflowPermissionMode = Extract<WorkflowPermissionMode, "legacy" | "permissive" | "restricted" | "full-access">;
 export type OmpWorkflowPermissionMode = Extract<WorkflowPermissionMode, "legacy" | "permissive" | "restricted" | "full-access">;
-export type WorkflowWorkerPermissionMode<W extends WorkflowWorkerId> = W extends "claude-code" ? ClaudeWorkflowPermissionMode : W extends "codex-cli" ? CodexWorkflowPermissionMode : W extends "cursor" ? CursorWorkflowPermissionMode : W extends "devin" ? DevinWorkflowPermissionMode : W extends "omp" ? OmpWorkflowPermissionMode : WorkflowDialPermissionMode;
 export declare const WORKFLOW_SESSION_PERSISTENCE_WORKERS: readonly ["claude-code", "codex-cli", "omp"];
+/** Remote Amp executors: hosted orbs and operator-declared runners. */
+export type AmpRemoteWorkflowWorkerId = Extract<WorkflowWorkerId, "amp-orb" | "amp-runner">;
+/**
+ * Workers whose full options can be built from `{ worker, model, ... }` alone.
+ * TypeScript's smarter union checking (TS 3.5+) decomposes a wide `worker`
+ * discriminant across the options union, so a helper typed against the full
+ * {@link WorkflowWorkerId} that cannot supply remote workers' required fields
+ * (`project`, `runnerId`) would silently accept remote ids as invalid tasks.
+ * Loose helpers must narrow to this.
+ */
+export type WorkflowWorkerIdWithoutRequiredOptions = Exclude<WorkflowWorkerId, AmpRemoteWorkflowWorkerId>;
+/**
+ * Remote Amp executors (orb, runner) read tool permissions from the remote
+ * machine's Amp settings or the ampcode.com project; Prism has no
+ * per-invocation override that reaches them.
+ */
+export type AmpRemoteWorkflowPermissionMode = Extract<WorkflowPermissionMode, "legacy">;
+export type WorkflowWorkerPermissionMode<W extends WorkflowWorkerId> = W extends "claude-code" ? ClaudeWorkflowPermissionMode : W extends "codex-cli" ? CodexWorkflowPermissionMode : W extends "cursor" ? CursorWorkflowPermissionMode : W extends "devin" ? DevinWorkflowPermissionMode : W extends "omp" ? OmpWorkflowPermissionMode : W extends AmpRemoteWorkflowWorkerId ? AmpRemoteWorkflowPermissionMode : WorkflowDialPermissionMode;
+/** Documented orb sizes (https://ampcode.com/docs/orbs/sizes-and-costs); `a1.3xlarge` needs Gigawatt/Enterprise. */
+export declare const AMP_ORB_SIZES: readonly ["a1.tiny", "a1.small", "a1.medium", "a1.large", "a1.xxlarge", "a1.3xlarge"];
+export type AmpOrbSize = (typeof AMP_ORB_SIZES)[number];
+/** Amp thread visibility values (`--visibility`). */
+export declare const AMP_THREAD_VISIBILITIES: readonly ["private", "unlisted", "workspace", "group"];
+export type AmpThreadVisibility = (typeof AMP_THREAD_VISIBILITIES)[number];
 export type WorkflowSessionPersistenceWorkerId = typeof WORKFLOW_SESSION_PERSISTENCE_WORKERS[number];
 export type WorkflowSessionPersistence = "persistent" | "ephemeral";
 /** @deprecated Use WorkflowSessionPersistence. */
@@ -105,17 +184,46 @@ type WorkflowTaskWorkerOptionsFor<W extends WorkflowWorkerId> = WorkflowTaskWork
     readonly worker: W;
     readonly permission?: WorkflowWorkerPermissionMode<W>;
 } & (W extends "amp-code" ? {
-    readonly sessionPersistence?: never;
     readonly catalogModel?: WorkflowHarnessCatalogModel<"amp-code">;
-    readonly effort?: WorkflowHarnessEffort<"amp-code">;
-} : W extends WorkflowSessionPersistenceWorkerId ? {
+} : W extends "amp-runner" ? {
+    readonly catalogModel?: WorkflowHarnessCatalogModel<"amp-code">;
+} : {
+    readonly catalogModel?: never;
+}) & (W extends WorkflowEffortWorkerHarnessId ? {
+    readonly effort?: WorkflowHarnessEffort<W>;
+} : {
+    readonly effort?: never;
+}) & (W extends WorkflowSessionPersistenceWorkerId ? {
     readonly sessionPersistence?: WorkflowSessionPersistence;
 } : {
     readonly sessionPersistence?: never;
+}) & (W extends AmpRemoteWorkflowWorkerId ? {
+    readonly labels?: ReadonlyArray<string>;
+} : {
+    readonly labels?: never;
+}) & (W extends "amp-orb" ? {
+    /**
+     * Amp project for the orb (`--project`): namespace/name, owner/repo, or repository URL.
+     * Narrows to discovered projects after `prism workflow refresh-harness-types`.
+     */
+    readonly project: WorkflowHarnessProject<"amp-orb">;
+    /** `--orb-size`; defaults to the project's size. */
+    readonly size?: AmpOrbSize;
+    /** Thread visibility; defaults to Amp's own default. Cosmetic: not part of cache identity. */
+    readonly visibility?: AmpThreadVisibility;
+} : {
+    readonly project?: never;
+    readonly size?: never;
+    readonly visibility?: never;
+}) & (W extends "amp-runner" ? AmpRunnerTargetOptions : {
+    readonly runnerId?: never;
+    readonly runnerDir?: never;
 });
 export type WorkflowTaskWorkerOptions = (WorkflowTaskWorkerOptionsCommon & {
     readonly worker?: undefined;
     readonly permission?: WorkflowPermissionMode;
+    readonly catalogModel?: never;
+    readonly effort?: never;
     readonly sessionPersistence?: never;
 }) | {
     [W in WorkflowWorkerId]: WorkflowTaskWorkerOptionsFor<W>;
@@ -128,8 +236,10 @@ export interface WorkflowTaskModelResolution {
     readonly model: string;
     /** Harness-side inference provider (e.g. hermes `--provider xai-oauth`), from the modelspace target or harness default. */
     readonly provider?: string;
-    /** Harness-bound model variant, such as Codex reasoning effort. */
+    /** Model-selection variant, such as OpenCode's `provider/model#variant`. */
     readonly variant?: string;
+    /** Harness-bound reasoning effort from a modelspace target. */
+    readonly effort?: string;
     readonly source: WorkflowTaskModelResolutionSource;
 }
 /**
@@ -139,11 +249,16 @@ export interface WorkflowTaskModelResolution {
  * `undefined` so per-worker CLIs that tolerate an omitted --model flag
  * (e.g. opencode) keep doing so.
  */
-export declare const resolveWorkflowTaskModelResolution: (task: AnyWorkflowTask, options?: {
+export declare const resolveWorkflowTaskModelResolution: (task: AnyWorkflowWorkerTask, options?: {
     readonly worker?: string;
     readonly fallbackModel?: string;
 }) => WorkflowTaskModelResolution | undefined;
-export declare const resolveWorkflowTaskModel: (task: AnyWorkflowTask, options?: {
+export declare const resolveWorkflowTaskModel: (task: AnyWorkflowWorkerTask, options?: {
+    readonly worker?: string;
+    readonly fallbackModel?: string;
+}) => string | undefined;
+/** Task-level effort is the explicit override; modelspace effort is the fallback. */
+export declare const resolveWorkflowTaskEffort: (task: AnyWorkflowWorkerTask, options?: {
     readonly worker?: string;
     readonly fallbackModel?: string;
 }) => string | undefined;
@@ -215,20 +330,66 @@ export interface WorkflowTaskDefinition<Id extends string, Output extends Workfl
     readonly phase?: string;
     readonly cacheKey?: string;
     readonly worker?: WorkflowTaskWorkerOptions;
-    readonly finish?: WorkflowFinishOptions<Schema.Schema.Type<Output>>;
+    readonly finish?: WorkflowFinishOptions<Output["Type"]>;
 }
 export type WorkflowTask<Id extends string = string, Output extends WorkflowOutputSchema = WorkflowOutputSchema> = WorkflowTaskDefinition<Id, Output> & {
     readonly kind: "workflow-task";
 };
-export type AnyWorkflowTask = WorkflowTask<string, WorkflowOutputSchema>;
-export type WorkflowTaskOutput<Task extends AnyWorkflowTask> = Schema.Schema.Type<Task["output"]>;
-export declare const resolveWorkflowTaskSessionPersistence: (task: Pick<AnyWorkflowTask, "worker">, effectiveWorker?: string | undefined) => WorkflowSessionPersistence | undefined;
-export declare const assertWorkflowTaskSessionPersistence: (task: AnyWorkflowTask) => void;
+/**
+ * A workflow task whose output type is erased.
+ *
+ * A task is invariant in its output type (`WorkflowFinishOptions` consumes it in
+ * callback positions), so `defineWorkflow({ tasks: [build, review] })` only
+ * accepts a heterogeneous tuple when the element bound erases that type. The
+ * erasure is deliberately local to this bound: `WorkflowOutputSchema` keeps
+ * `unknown` so ordinary authoring and `defineTask` inference stay precise, and
+ * `WorkflowTaskOutput<Task>` still reads the concrete output of a concrete task.
+ *
+ * The encoded side and the service-free requirement (`never, never`) are not
+ * erased. This is a deliberate loss of proof at the task-collection boundary,
+ * not sound existential quantification.
+ */
+export type AnyWorkflowWorkerTask = WorkflowTask<string, Schema.Codec<any, unknown, never, never>>;
+/**
+ * A Jev task whose question types are erased. Like the worker erasure above,
+ * this keeps heterogeneous `tasks: [...] tuples writable while concrete
+ * `jev(...)` calls keep their precise inferred output.
+ */
+export type AnyJevTask = JevTask<string, any>;
+export type AnyWorkflowTask = AnyWorkflowWorkerTask | AnyJevTask;
+export type WorkflowTaskOutput<Task extends AnyWorkflowTask> = Task["output"]["Type"];
+export interface JevTaskDefinition<Id extends string, Q extends JevQuestions> extends JevRequest<Q> {
+    readonly id: Id;
+    /** Per-HTTP-attempt timeout override passed to the JevClient call. */
+    readonly timeoutMs?: number;
+    readonly phase?: string;
+    readonly cacheKey?: string;
+}
+export type JevTask<Id extends string = string, Q extends JevQuestions = JevQuestions> = JevTaskDefinition<Id, Q> & {
+    readonly kind: "jev";
+    readonly output: JevResultCodec<Q>;
+};
+/**
+ * Construct a native Jev decision task. The state/questions are validated,
+ * deep-copied, and frozen immediately so identity hashing and execution can
+ * never disagree, and the output codec is derived from the questions.
+ */
+export declare const jev: <const Id extends string, const Q extends JevQuestions>(definition: JevTaskDefinition<Id, Q>) => JevTask<Id, Q>;
+export declare const resolveWorkflowTaskSessionPersistence: (task: Pick<AnyWorkflowWorkerTask, "worker">, effectiveWorker?: string | undefined) => WorkflowSessionPersistence | undefined;
+export declare const assertWorkflowTaskSessionPersistence: (task: AnyWorkflowWorkerTask) => void;
+export declare const isWorkflowWorkerTask: (value: unknown) => value is AnyWorkflowWorkerTask;
+export declare const isJevTask: (value: unknown) => value is AnyJevTask;
 export declare const isWorkflowTask: (value: unknown) => value is AnyWorkflowTask;
 export interface WorkflowDefinition<Name extends string, Tasks extends ReadonlyArray<AnyWorkflowTask>> {
     readonly kind: "workflow";
     readonly name: Name;
     readonly tasks: Tasks;
+    /**
+     * Inert scheduling policy. Declaring it registers nothing; only
+     * `prism workflow schedule install` activates a schedule. See
+     * `workflow-scheduler/schedule.ts`.
+     */
+    readonly schedule?: WorkflowSchedule;
 }
 export interface PhaseFraming {
     readonly purpose?: string;
@@ -254,21 +415,37 @@ export type PhaseTaskFinishOptions<Output> = WorkflowFinishOptions<Output> & {
     readonly inherit?: boolean;
 };
 /** Decoded TypeScript value of a phase input contract (unknown when no contract). */
-export type PhaseTaskInputValue<Input extends WorkflowOutputSchema | undefined> = Input extends WorkflowOutputSchema ? Schema.Schema.Type<Input> : unknown;
+export type PhaseTaskInputValue<Input extends WorkflowOutputSchema | undefined> = Input extends WorkflowOutputSchema ? Input["Type"] : unknown;
 export type PhaseTaskDefinition<Id extends string, Input extends WorkflowOutputSchema | undefined = undefined, Output extends WorkflowOutputSchema = WorkflowOutputSchema> = Omit<WorkflowTaskDefinition<Id, Output>, "output" | "phase" | "finish"> & {
     readonly input?: PhaseTaskInputValue<Input>;
     readonly output?: Output;
     readonly phase?: string;
-    readonly finish?: PhaseTaskFinishOptions<Schema.Schema.Type<Output>>;
+    readonly finish?: PhaseTaskFinishOptions<Output["Type"]>;
     readonly brief?: boolean;
 };
 export type PhaseCtxTask<Input extends WorkflowOutputSchema | undefined, DefaultOutput extends WorkflowOutputSchema | undefined> = <const Id extends string, const TaskOutput extends WorkflowOutputSchema = Extract<DefaultOutput, WorkflowOutputSchema>>(def: PhaseTaskDefinition<Id, Input, TaskOutput>) => Effect.Effect<WorkflowTaskOutput<WorkflowTask<Id, TaskOutput>>, WorkflowRuntimeError>;
+/**
+ * A `ctx.jev(...)` definition. When the phase binds an input contract, the
+ * Jev state is that contract's decoded value (it must still be a valid System
+ * One entry — schemas describing functions or class instances do not belong
+ * in state and will fail entry validation at run time).
+ */
+export type PhaseJevTaskDefinition<Id extends string, Input extends WorkflowOutputSchema | undefined, Q extends JevQuestions> = Omit<JevTaskDefinition<Id, Q>, "state"> & {
+    readonly state: Input extends WorkflowOutputSchema ? Input["Type"] & JevEntry : JevEntry;
+};
+export type PhaseCtxJev<Input extends WorkflowOutputSchema | undefined> = <const Id extends string, const Q extends JevQuestions>(definition: PhaseJevTaskDefinition<Id, Input, Q>) => Effect.Effect<JevResult<Q>, WorkflowRuntimeError>;
 export interface PhaseCtx<Name extends string, Input extends WorkflowOutputSchema | undefined, DefaultOutput extends WorkflowOutputSchema | undefined> {
     readonly name: Name;
     readonly sop: string;
     readonly plugin: string;
     readonly phase: string;
     readonly task: PhaseCtxTask<Input, DefaultOutput>;
+    /**
+     * Run a native Jev decision inside this phase. Unlike `ctx.task`, no prompt
+     * framing, serialized-input block, finish criteria, or phase output schema
+     * is applied — a decision is defined by its state and questions alone.
+     */
+    readonly jev: PhaseCtxJev<Input>;
 }
 export declare const phase: <const Name extends string, const Input extends WorkflowOutputSchema | undefined, const Output extends WorkflowOutputSchema | undefined, Result, Err = WorkflowRuntimeError>(runtime: Pick<WorkflowRuntime, "runTask">, contract: PhaseContract<Name, Input, Output>, fn: (ctx: PhaseCtx<Name, Input, Output>) => Effect.Effect<Result, Err, never>) => Effect.Effect<Result, Err | WorkflowRuntimeError, never>;
 export interface WorkflowRuntime {
@@ -285,6 +462,8 @@ export interface DynamicWorkflowDefinition<Name extends string, Result = unknown
     readonly name: Name;
     readonly tasks: readonly [];
     readonly run: (runtime: WorkflowRuntime) => Effect.Effect<Result, Err, never>;
+    /** Inert scheduling policy; see `WorkflowDefinition.schedule`. */
+    readonly schedule?: WorkflowSchedule;
 }
 export type AnyWorkflowDefinition = WorkflowDefinition<string, ReadonlyArray<AnyWorkflowTask>> | DynamicWorkflowDefinition<string>;
 export declare const isWorkflowDefinition: (value: unknown) => value is AnyWorkflowDefinition;
@@ -293,9 +472,11 @@ export declare const defineTask: <const Id extends string, const Output extends
 export declare function defineWorkflow<const Name extends string, const Tasks extends ReadonlyArray<AnyWorkflowTask>>(definition: {
     readonly name: Name;
     readonly tasks: Tasks;
+    readonly schedule?: WorkflowSchedule;
 }): WorkflowDefinition<Name, Tasks>;
 export declare function defineWorkflow<const Name extends string, Result, Err = WorkflowRuntimeError>(definition: {
     readonly name: Name;
     readonly run: (runtime: WorkflowRuntime) => Effect.Effect<Result, Err, never>;
+    readonly schedule?: WorkflowSchedule;
 }): DynamicWorkflowDefinition<Name, Result, Err>;
-export declare const decodeTaskOutput: <Task extends AnyWorkflowTask>(task: Task, value: unknown) => Either<Schema.Schema.Type<Task["output"]>, ParseError>;
+export declare const decodeTaskOutput: <Task extends AnyWorkflowTask | AnyJevTask>(task: Task, value: unknown, options?: SchemaAST.ParseOptions) => Result.Result<Task["output"]["Type"], Schema.SchemaError>;