# `Magma.Session`
[🔗](https://github.com/marcelotto/magma/blob/v0.3.2/lib/magma/document_types/session.ex#L1)

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.

# `parts`

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

# `response_mode`

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

# `section_type`

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

# `t`

```elixir
@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()
}
```

# `create`

# `find_latest_session_response`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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!`

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

# `load_linked`

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`

```elixir
@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`

# `new!`

# `path_prefix`

# `render`

# `response_mode`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*