adk_run (erlang_adk v0.7.0)

View Source

Public, reconnectable invocation API.

Runs are owned by a supervised adk_invocation process rather than by the process which starts or subscribes to them. Subscribers receive:

{adk_run_event, RunId, Sequence, Event} {adk_run_terminal, RunId, Sequence, Outcome}

Outcome is one of {completed, Output}, {paused, Event}, {cancelled, Reason}, or {failed, Reason}. Every run commits exactly one terminal outcome. A late subscriber receives the bounded event replay and the same terminal outcome while the run remains retained.

HTTP and other back-pressure-sensitive consumers should use subscribe_credit/2,3 and acknowledge each delivered sequence with ack/2,3. A credit subscriber has at most one unacknowledged run message in its mailbox. The original subscribe/1,2 push protocol remains unchanged for local Erlang processes which already drain their mailboxes promptly.

Summary

Types

outcome/0
run_id/0

Functions

ack(RunId, Sequence)

Return credit for the exact event Sequence just consumed.

ack(RunId, Subscriber, Sequence)
await(RunId)
await(RunId, Timeout)
cancel(RunId)
cancel(RunId, Reason)
resume(PausedRunId, ToolResponse)

Resume a terminal paused run as a new supervised run.

resume(PausedRunId, ToolResponse, Opts)
start(Runner, UserId, SessionId, Message)
start(Runner, UserId, SessionId, Message, Opts)
status(RunId)
subscribe(RunId)
subscribe(RunId, Subscriber)
subscribe_credit(RunId, Cursor)

Subscribe with one-message credit starting strictly after Cursor.

subscribe_credit(RunId, Subscriber, Cursor)
unsubscribe(RunId)
unsubscribe(RunId, Subscriber)

Types

outcome/0

-type outcome() ::
          {completed, binary() | adk_content:content()} |
          {paused, term()} |
          {cancelled, term()} |
          {failed, term()}.

run_id/0

-type run_id() :: binary().

Functions

ack(RunId, Sequence)

-spec ack(run_id(), non_neg_integer()) -> ok | {error, term()}.

Return credit for the exact event Sequence just consumed.

ack(RunId, Subscriber, Sequence)

-spec ack(run_id(), pid(), non_neg_integer()) -> ok | {error, term()}.

await(RunId)

-spec await(run_id()) -> outcome() | {error, term()}.

await(RunId, Timeout)

-spec await(run_id(), timeout()) -> outcome() | {error, term()}.

cancel(RunId)

-spec cancel(run_id()) -> ok | {error, term()}.

cancel(RunId, Reason)

-spec cancel(run_id(), term()) -> ok | {error, term()}.

resume(PausedRunId, ToolResponse)

-spec resume(run_id(), term()) -> {ok, run_id()} | {error, term()}.

Resume a terminal paused run as a new supervised run.

The paused run remains immutable and retained for inspection. The returned run has its own event sequence and terminal outcome, while status/1 links the two runs through resumed_to and parent_run_id. Only one resume may be accepted for a paused run.

resume(PausedRunId, ToolResponse, Opts)

-spec resume(run_id(), term(), map()) -> {ok, run_id()} | {error, term()}.

start(Runner, UserId, SessionId, Message)

-spec start(adk_runner:runner(), binary(), binary(), term()) -> {ok, run_id()} | {error, term()}.

start(Runner, UserId, SessionId, Message, Opts)

-spec start(adk_runner:runner(), binary(), binary(), term(), map()) -> {ok, run_id()} | {error, term()}.

status(RunId)

-spec status(run_id()) -> {ok, map()} | {error, term()}.

subscribe(RunId)

-spec subscribe(run_id()) -> ok | {error, term()}.

subscribe(RunId, Subscriber)

-spec subscribe(run_id(), pid()) -> ok | {error, term()}.

subscribe_credit(RunId, Cursor)

-spec subscribe_credit(run_id(), non_neg_integer()) -> {ok, map()} | {error, term()}.

Subscribe with one-message credit starting strictly after Cursor.

The result includes the invocation's latest sequence and terminal state at the subscription boundary. If Cursor is older than the bounded replay window, no subscription is installed and {error, {replay_gap, Details}} is returned. Callers must acknowledge each event before another event is released. A terminal message does not need acknowledgement.

subscribe_credit(RunId, Subscriber, Cursor)

-spec subscribe_credit(run_id(), pid(), non_neg_integer()) -> {ok, map()} | {error, term()}.

unsubscribe(RunId)

-spec unsubscribe(run_id()) -> ok | {error, term()}.

unsubscribe(RunId, Subscriber)

-spec unsubscribe(run_id(), pid()) -> ok | {error, term()}.