Jidoka.Session (Jidoka v0.9.0)

Ergonomic session facade backed by Jidoka.Session.Data.

Jidoka.Session.Data is the durable data contract. This module is the developer-facing API for starting, running, resuming, and inspecting sessions without reaching into lower-level execution modules for common workflows.

Summary

Types

agent_input()

async_result()

chat_result()

opts()

request_input()

run_result()

session_input()

t()

Functions

await(request, opts \\ [])

Waits for a request handle returned by chat_async/3.

cancel(request, opts \\ [])

Cancels an active asynchronous session request.

chat(session_or_id, input, opts \\ [])

Runs one turn for a session and returns final assistant text.

chat_async(session_or_id, input, opts \\ [])

Starts one session chat turn asynchronously.

fork(session_or_id, opts \\ [])

Creates a new session from a safe snapshot in an existing session.

get(store, session_id)

Fetches a persisted session from a configured session store.

list(store)

Lists persisted sessions from a configured session store.

pending_reviews(session_or_store)

Lists pending human-review requests from a session or session store.

recover(session_id, opts \\ [])

Recovers a session after its durable worker lease expires.

recoverable(store, opts \\ [])

Lists stored sessions that are ready for crash recovery.

replay(session)

Returns a data-only replay view for a session.

resume(session_or_id, opts \\ [])

Resumes the latest hibernated snapshot for a session.

run(session_or_id, request_input, opts \\ [])

Runs one turn for a session and returns the full session result.

start(agent_or_plan, opts \\ [])

Starts a new session for an agent, spec, or plan.

start(agent_or_plan, session_id, opts)

Starts a new session with an explicit session id.

write_memory(session, content, opts \\ [])

Writes one memory entry through the configured memory store.

Types

agent_input()

@type agent_input() :: Jidoka.Turn.Plan.input()

async_result()

@type async_result() :: {:ok, Jidoka.Chat.Request.t()} | {:error, term()}

chat_result()

@type chat_result() ::
  {:ok, t(), String.t()}
  | {:hibernate, t(), Jidoka.Snapshot.t()}
  | {:cancelled, Jidoka.Cancellation.t()}
  | {:error, term()}

opts()

@type opts() :: keyword()

request_input()

@type request_input() :: Jidoka.Turn.Request.input()

run_result()

@type run_result() ::
  {:ok, t(), Jidoka.Turn.Result.t()}
  | {:hibernate, t(), Jidoka.Snapshot.t()}
  | {:error, term()}

session_input()

@type session_input() :: t() | String.t()

t()

@type t() :: Jidoka.Session.Data.t()

Functions

await(request, opts \\ [])

@spec await(Jidoka.Chat.Request.t(), opts()) :: chat_result()

Waits for a request handle returned by chat_async/3.

cancel(request, opts \\ [])

@spec cancel(Jidoka.Chat.Request.t(), opts()) ::
  {:ok, Jidoka.Cancellation.t()} | {:error, term()}

Cancels an active asynchronous session request.

chat(session_or_id, input, opts \\ [])

@spec chat(session_input(), String.t(), opts()) :: chat_result()

Runs one turn for a session and returns final assistant text.

The updated session is returned with the text so caller-managed sessions do not lose durable state when no store is configured.

chat_async(session_or_id, input, opts \\ [])

@spec chat_async(session_input(), String.t(), opts()) :: async_result()

Starts one session chat turn asynchronously.

Pass stream: true to stream request-scoped Jidoka.Event values to the caller mailbox while the request is running.

fork(session_or_id, opts \\ [])

@spec fork(session_input(), opts()) :: {:ok, t()} | {:error, term()}

Creates a new session from a safe snapshot in an existing session.

The source session stays unchanged. By default, this function forks the latest snapshot. Pass snapshot: to select another stored snapshot.

get(store, session_id)

@spec get(Jidoka.Session.Store.store(), String.t()) :: {:ok, t()} | {:error, term()}

Fetches a persisted session from a configured session store.

list(store)

@spec list(Jidoka.Session.Store.store()) :: {:ok, [t()]} | {:error, term()}

Lists persisted sessions from a configured session store.

pending_reviews(session_or_store)

@spec pending_reviews(t() | Jidoka.Session.Store.store()) ::
  {:ok, [Jidoka.Review.Request.t()]} | {:error, term()}

Lists pending human-review requests from a session or session store.

recover(session_id, opts \\ [])

@spec recover(String.t(), opts()) :: run_result()

Recovers a session after its durable worker lease expires.

recoverable(store, opts \\ [])

@spec recoverable(Jidoka.Session.Store.store(), opts()) ::
  {:ok, [t()]} | {:error, term()}

Lists stored sessions that are ready for crash recovery.

replay(session)

@spec replay(t()) :: {:ok, Jidoka.Session.Replay.t()} | {:error, term()}

Returns a data-only replay view for a session.

resume(session_or_id, opts \\ [])

@spec resume(session_input(), opts()) :: run_result()

Resumes the latest hibernated snapshot for a session.

run(session_or_id, request_input, opts \\ [])

@spec run(session_input(), request_input(), opts()) :: run_result()

Runs one turn for a session and returns the full session result.

start(agent_or_plan, opts \\ [])

@spec start(agent_input(), opts() | String.t()) :: {:ok, t()} | {:error, term()}

Starts a new session for an agent, spec, or plan.

The returned value is a Jidoka.Session.Data struct. A DSL agent module is accepted directly:

{:ok, session} = Jidoka.Session.start(MyApp.SupportAgent, "support-123")

Pass store: ... to persist the session immediately.

start(agent_or_plan, session_id, opts)

@spec start(agent_input(), String.t(), opts()) :: {:ok, t()} | {:error, term()}

Starts a new session with an explicit session id.

write_memory(session, content, opts \\ [])

@spec write_memory(t(), String.t(), opts()) ::
  {:ok, Jidoka.Memory.WriteResult.t()} | {:error, term()}

Writes one memory entry through the configured memory store.