PromptRunner.AgentControl (PromptRunnerSDK v0.12.1)

Agent-directed control for a linear packet run.

A provider may request that Prompt Runner continue to the next prompt, repeat the current prompt in a fresh session, finish the selected sequence, or stop because progress is blocked. Requests are scoped to one prompt iteration and are consumed only after that iteration satisfies its ordinary verifier.

The provider may also publish a durable project cursor with progress/3. Progress is authenticated to the same invocation but stored separately: it can be refreshed repeatedly and never consumes the first-wins terminal request.

Successful early finish remains verifier-owned: the packet's completion_verify contract must pass before the runner accepts finish.

Summary

Types

action()

config()

invocation()

Functions

attach_llm(llm, invocation)

Adds the invocation variables to the provider subprocess environment.

completion_report(plan, map)

Runs the packet-level completion contract.

config(options)

Returns the normalized packet configuration.

consume(invocation)

Reads and authenticates the request for one invocation.

decorate_prompt(body, invocation, config, finish_failure \\ nil)

Appends the linear-control instructions sent to the provider.

enabled?(plan)

Whether the plan enables agent-directed execution.

prepare(run_dir, run_id, prompt_id, iteration)

Creates one fresh request scope for a prompt iteration.

progress(cursor, summary, opts \\ [])

Atomically publishes nonterminal progress from inside the provider subprocess.

read_progress(invocation)

Reads and authenticates the progress record for one invocation.

request(action, opts \\ [])

Writes one directive from inside the provider subprocess.

requested_action(arg1, config)

Returns the explicit request or the configured default.

Types

action()

@type action() :: :continue | :repeat | :finish | :blocked

config()

@type config() :: %{
  enabled?: boolean(),
  default_action: :continue | :repeat,
  max_iterations: pos_integer(),
  completion_verify: map()
}

invocation()

@type invocation() :: %{
  request_file: String.t(),
  progress_file: String.t(),
  token: String.t(),
  run_id: String.t(),
  prompt_id: String.t(),
  iteration: pos_integer()
}

Functions

attach_llm(llm, invocation)

@spec attach_llm(map(), invocation()) :: map()

Adds the invocation variables to the provider subprocess environment.

completion_report(plan, map)

@spec completion_report(PromptRunner.Plan.t(), config()) ::
  PromptRunner.Verifier.report()

Runs the packet-level completion contract.

config(options)

@spec config(PromptRunner.Plan.t() | map() | nil) ::
  {:ok, config()} | {:error, term()}

Returns the normalized packet configuration.

consume(invocation)

@spec consume(invocation()) :: {:ok, map() | nil} | {:error, term()}

Reads and authenticates the request for one invocation.

decorate_prompt(body, invocation, config, finish_failure \\ nil)

@spec decorate_prompt(String.t(), invocation(), config(), map() | nil) :: String.t()

Appends the linear-control instructions sent to the provider.

enabled?(plan)

@spec enabled?(PromptRunner.Plan.t()) :: boolean()

Whether the plan enables agent-directed execution.

prepare(run_dir, run_id, prompt_id, iteration)

@spec prepare(String.t(), String.t(), String.t(), pos_integer()) ::
  {:ok, invocation()} | {:error, term()}

Creates one fresh request scope for a prompt iteration.

progress(cursor, summary, opts \\ [])

@spec progress(String.t(), String.t(), keyword()) :: {:ok, map()} | {:error, term()}

Atomically publishes nonterminal progress from inside the provider subprocess.

read_progress(invocation)

@spec read_progress(invocation()) :: {:ok, map() | nil} | {:error, term()}

Reads and authenticates the progress record for one invocation.

request(action, opts \\ [])

@spec request(
  action() | String.t(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Writes one directive from inside the provider subprocess.

requested_action(arg1, config)

@spec requested_action(map() | nil, config()) :: action()

Returns the explicit request or the configured default.