Magma.Session (Magma v0.3.2)

An interactive prompt document supporting multi-turn conversations with coding agents.

Sessions operate in two modes:

Initial mode: A new session without ***Prompt*** separators, where the entire content (after the controls prologue) forms the prompt.
Continuation mode: A session with ***Prompt*** and ***Response*** separators for multi-turn conversations, where only the last prompt section is assembled for execution.

The response_mode controls whether a response instruction is appended to the assembled prompt (:disabled, :enabled, or :auto).

Stored in the sessions/ directory of the vault.

Summary

Types

parts()

response_mode()

section_type()

t()

Functions

create(name, attrs \\ [], opts \\ [])

find_latest_session_response(session)

Finds the latest response file for a given session.

import_response(session_name)

Imports a response from an external file into the session document.

last_prompt_part(session)

Extracts the AST nodes of the last Prompt section.

load(document)

Loads a document from the given path or document.

load!(document_or_path)

Loads a document from the given path or document and raises an exception in error cases.

load_linked(link)

Loads a document from the given Obsidian link, i.e. a string of the form "[[name]]".

mode(session)

Detects the session mode based on the presence of Prompt separators.

new(name, attrs \\ [])

new!(name, attrs \\ [])

path_prefix()

render(session)

response_mode(session)

Returns the session_response_mode for this session.

Types

parts()

@type parts() :: [{section_type(), [Panpipe.AST.Node.t()]}]

response_mode()

@type response_mode() :: :disabled | :enabled | :auto

section_type()

@type section_type() :: :initial | :prompt | :response | :notes

t()

@type t() :: %Magma.Session{
  aliases: term(),
  content: term(),
  created_at: term(),
  custom_metadata: term(),
  name: term(),
  parts: parts(),
  path: term(),
  response_mode: response_mode() | nil,
  tags: term()
}

Functions

create(name, attrs \\ [], opts \\ [])

find_latest_session_response(session)

@spec find_latest_session_response(t()) :: {:ok, Path.t()} | {:error, :not_found}

Finds the latest response file for a given session.

Returns {:ok, path} if found, {:error, :not_found} if no response files exist.

import_response(session_name)

@spec import_response(String.t() | t()) :: {:ok, t()} | {:error, any()}

Imports a response from an external file into the session document.

Finds the latest response file for the session, reads its content, replaces the import button with the response content, and deletes the response file.

last_prompt_part(session)

@spec last_prompt_part(t()) :: [Panpipe.AST.Node.t()] | nil

Extracts the AST nodes of the last Prompt section.

Returns the AST nodes if in continuation mode. Returns nil if in initial mode (no Prompt sections found).

load(document)

Loads a document from the given path or document.

If the loaded document is not of the proper document type an Magma.InvalidDocumentType exception is returned in an :error tuple.

load!(document_or_path)

Loads a document from the given path or document and raises an exception in error cases.

load_linked(link)

Loads a document from the given Obsidian link, i.e. a string of the form "[[name]]".

If the referenced document is not of the proper document type an Magma.InvalidDocumentType exception is returned in an :error tuple.

mode(session)

@spec mode(t()) :: :initial | :continuation

Detects the session mode based on the presence of Prompt separators.

Returns :initial if no ***Prompt*** separators are found (initial mode). Returns :continuation if ***Prompt*** separators are present (continuation mode).

new(name, attrs \\ [])

new!(name, attrs \\ [])

path_prefix()

render(session)

response_mode(session)

@spec response_mode(t()) :: response_mode()

Returns the session_response_mode for this session.

Checks the session's response_mode field first, falling back to system config.