LouiseLM Public API Appendix

Generated by scripts/generate-api-appendix from LuaCATS annotations via lua-language-server --doc. Do not edit by hand.

Scope: the established extension boundaries only -- the headless Session API, typed events, permission policies, and Agent configuration (AGENTS.md section 1). ACP transport internals, UI, schema machinery, mocks, and development helpers are intentionally excluded. AGENTS.md remains the sole Agent-facing (AX) contract; this appendix is a human API reference.

Headless Session API¶

louiselm.session.Api¶

collect_forensics: fun(self: louiselm.session.Api, agent_name: string, acp_session_id: string, options?: louiselm.session.ForensicsOptions, callback?: fun(path?: string, error_message?: string)):boolean, string?
create_session: fun(self: louiselm.session.Api, agent_name: string, options?: louiselm.session.Options, ready_callback?: fun(session?: louiselm.session.Session, error?: string)):(louiselm.session.Session)?, string?
discover_sessions: fun(self: louiselm.session.Api, options?: louiselm.session.DiscoveryOptions, callback: fun(sessions: louiselm.session.DiscoveredSession[], errors: louiselm.session.DiscoveryError[])):boolean, string?
dispose: fun(self: louiselm.session.Api):boolean, string?
flush_recording: fun(self: louiselm.session.Api, callback: fun(error?: louiselm.session.RecordingError)) -- Retry/acknowledge queued facts, including final observations after Disposal.
get_session: fun(self: louiselm.session.Api, id: string):(louiselm.session.Session)?
inspect_agent_limits: fun(self: louiselm.session.Api, agent_name: string):(louiselm.session.LimitsState)?, string?
list_permissions: fun(self: louiselm.session.Api):louiselm.permission.Rule[]?, string?
list_sessions: fun(self: louiselm.session.Api):string[]
load_session: fun(self: louiselm.session.Api, agent_name: string, acp_session_id: string, options?: louiselm.session.Options, ready_callback?: fun(session?: louiselm.session.Session, error?: string)):(louiselm.session.Session)?, string?
on_agent_limits: fun(self: louiselm.session.Api, callback: fun(state: louiselm.session.LimitsState)):fun()?, string?
refresh_agent_limits: fun(self: louiselm.session.Api, agent_name: string, callback: fun(state: louiselm.session.LimitsState, error?: string)):boolean, string?
revoke_permission: fun(self: louiselm.session.Api, id: string):boolean, string?

louiselm.session.ApiOptions¶

forensics_directory: string? -- Override the private Session Forensics directory.
permission_store: (louiselm.permission.Store)? -- Explicit remembered-permission store.
usage_directory: string? -- Absolute private directory for durable turn recording; defaults to usage/ in the shared LouiseLM state directory.

louiselm.session.ForensicsOptions¶

diagnosing_session_id: string? -- Durable identity of the diagnosing Session.

louiselm.session.ForensicsCallback¶

fun(path?: string, error_message?: string)

louiselm.session.Module¶

collect_forensics: fun(agent_name: string, acp_session_id: string, options?: louiselm.session.ForensicsOptions, callback?: fun(path?: string, error_message?: string)):boolean, string? -- Collect Forensics for any live Session in this process.
dispose_all: fun():boolean, string? -- Dispose every live Session in this Neovim process.
exit_verdict: fun():louiselm.session.ExitVerdict[] -- Inspect live Sessions across every headless API.
identity: fun(acp_session_id: string):string?, string? -- Resolve the calling Session’s <agent>/<acp session id> identity.
new: fun(definitions: unknown, default_skills_policy?: unknown, options?: louiselm.session.ApiOptions):(louiselm.session.Api)?, louiselm.agent.ConfigError[] -- Create a headless session API.

louiselm.session.Status¶

louiselm.session.Status:
    | "starting"
    | "ready"
    | "configuring"
    | "preparing"
    | "prompting"
    | "running"
    | "waiting_permission"
    | "cancelling"
    | "error"
    | "disposed"

louiselm.session.Prompt¶

string|table

louiselm.session.TurnIdentity¶

agent: string -- Configured Agent at prompt start.
model: (boolean|string)? -- Advertised Model value, when present; never inferred from its name.
options: table<string, boolean|string> -- Complete supported option tuple at prompt start.
provider: string -- Resolved access/quota service at prompt start.

louiselm.session.State¶

acp_session_id: string? -- Agent-side persistent conversation identifier, once available.
activity: string? -- Current generic tool activity.
agent: string -- Named agent definition.
commands: louiselm.session.AvailableCommand[] -- Latest agent-advertised commands, replaced wholesale on each update.
compactions: louiselm.session.Compaction[] -- Compaction snapshots in first-seen order, including replay.
config_options: louiselm.session.ConfigOption[] -- Supported agent-advertised options in priority order.
context: (louiselm.session.ContextUsage)? -- Latest agent-reported context state.
cost: (louiselm.session.Cost)? -- Latest agent-reported cumulative cost.
current_turn: integer -- Accepted prompt attempts in this local Session, including failed admission; not durable identity.
embedded_context: boolean -- Whether the Agent accepts embedded resource prompt context.
id: string -- Local session identifier.
name: string -- User-facing session name.
recording_error: (louiselm.session.RecordingError)? -- Storage failure or unresolved current Provider; subsequent dispatch requires recovery.
recording_pending: boolean -- Whether the registry has unacknowledged writes.
session_failure: (louiselm.session.SessionFailure)? -- Latest Agent-provided Session failure status.
skills_policy: "inject"|"native"|"off" -- Effective session-static Agent Skills policy.
source: "loaded"|"new" -- Whether the session was created or restored.
status: "cancelling"|"configuring"|"disposed"|"error"|"preparing"...(+5) -- Lifecycle state.
turn_id: string? -- Durable identity of the latest accepted prompt attempt; independent of local turn ordinal.
turn_identity: (louiselm.session.TurnIdentity)? -- Owned identity for the latest accepted attempt; later option changes never rewrite it.
turn_options_changed: boolean -- Whether the current/last attempt had confirmed value changes; unsuitable for fixed-option comparisons.
usage: (louiselm.session.TurnUsage)? -- Latest agent-reported completed-turn usage.
working_dir: string -- ACP working directory.

louiselm.session.AvailableCommand¶

description: string -- Human-readable command description.
name: string -- Command name as advertised by the agent.

louiselm.session.Options¶

cwd: string? -- Working directory for the ACP session.
env: table<string, string>? -- Per-Session Agent process environment overrides.
name: string? -- User-facing session name.
on_event: fun(event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))? -- Initial event listener.
permission_policy: (louiselm.permission.Policy)? -- Policy for agent-requested operations.
permission_store: (louiselm.permission.Store)? -- Remembered-permission owner.
schedule: fun(delay_ms: integer, callback: fun())? -- Testable scheduling boundary; defaults to vim.defer_fn.
start_timeout_ms: integer? -- Milliseconds to wait for the ACP handshake before failing a Session stuck “starting”; defaults to 20000.

louiselm.session.PermissionEntry¶

answered: boolean -- Whether a response was already written for this request.
data: table -- ACP permission request parameters enriched with louiselm metadata.
respond: fun(result: unknown, rpc_error?: louiselm.acp.JsonRpcError):boolean, string? -- Raw ACP responder.

louiselm.session.Session¶

acp_session_id: string? -- Agent-side session identifier.
agent_running: boolean? -- Agent-reported processing, independent of the client prompt response; nil until observed.
attribution_error: (louiselm.session.RecordingError)? -- Unresolved current Provider; cleared only by a confirmed correction.
cancel: fun(self: louiselm.session.Session):boolean, string?
client: (louiselm.acp.Client)? -- ACP client.
codex_turn_failed: boolean? -- Active prompt received systemError before its terminal response.
definition: louiselm.agent.Definition -- Agent process definition.
dispose: fun(self: louiselm.session.Session):boolean, string?
emitter: louiselm.session.EventEmitter -- Event subscribers.
inspect: fun(self: louiselm.session.Session):louiselm.session.State
load_session_id: string? -- Agent-side session identifier to load.
on: fun(self: louiselm.session.Session, callback: fun(event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))):fun()
option_observer_id: string -- Random identity of this live observation stream.
option_sequence: integer -- Number of confirmed value transitions observed outside replay.
option_usage: fun(self: louiselm.session.Session, option_id: string, callback: fun(candidates?: louiselm.session.OptionUsage[], error?: louiselm.session.RecordingError))
options: louiselm.session.Options -- Session options.
owner: louiselm.session.Registry -- Registry that owns this session.
owner_run: (louiselm.workflow.Run)? -- Run that supervised construction of this Session.
permission_active: (louiselm.session.PermissionEntry)? -- Permission request published for a decision.
permission_policy: louiselm.permission.Policy -- Policy for agent-requested operations.
permission_queue: louiselm.session.PermissionEntry[] -- Permission requests waiting for the active one.
permission_store: louiselm.permission.Store -- Remembered-permission owner.
prompt: fun(self: louiselm.session.Session, prompt: string|table, callback?: fun(result: unknown, error?: string)):string?, string?
prompt_callback: fun(result: unknown, error?: string)? -- Current prompt completion callback.
ready_callback: fun(session?: louiselm.session.Session, error?: string)? -- Session startup callback.
ready_callback_called: boolean -- Whether startup callback ran.
recording_turn: { id: string, sequence: integer, finished: boolean, dispatched: boolean }? -- Active recording identity.
replay_user_open: boolean -- Consecutive historical user chunks belong to one prompt.
schedule: fun(delay_ms: integer, callback: fun()) -- Testable scheduling boundary.
set_config_option: fun(self: louiselm.session.Session, id: string, value: boolean|string, callback?: fun(options?: louiselm.session.ConfigOption[], error?: string)):(string|number)?, string?
set_name: fun(self: louiselm.session.Session, name: string):boolean, string? -- Rename the session.
start: fun(self: louiselm.session.Session):boolean, string?
start_timeout_ms: integer -- Milliseconds to wait for the ACP handshake before failing a Session stuck “starting”.
state: louiselm.session.State -- Internal mutable state.
stderr_buffer: string -- Recent stderr output from the agent process, most-recent-last.
transcript_turn: integer -- Observed replay turns plus locally dispatched prompts, excluding unsent attempts.
turn_done_turn: integer? -- Turn for which the completion event was emitted.
usage_history: fun(self: louiselm.session.Session, callback: fun(records?: louiselm.session.ReplayUsage[], error?: louiselm.session.RecordingError))

louiselm.session.OptionUsage¶

error: (louiselm.session.RecordingError)? -- Candidate attribution failure.
provider: string? -- Resolved candidate Provider.
summary: (louiselm.session.CohortSummary)? -- Exact matching committed history.
value: boolean|string -- Candidate advertised value.

louiselm.session.OptionUsageCallback¶

fun(candidates?: louiselm.session.OptionUsage[], error?: louiselm.session.RecordingError)

louiselm.session.DiscoveryOptions¶

cwd: string? -- Exact ACP workspace filter; omit to discover every workspace.

louiselm.session.DiscoveryError¶

agent: string -- Configured agent definition name.
message: string -- Sanitized discovery failure.

louiselm.session.DiscoveryCallback¶

fun(sessions: louiselm.session.DiscoveredSession[], errors: louiselm.session.DiscoveryError[])

louiselm.session.DiscoveryState¶

callback: fun(sessions: louiselm.session.DiscoveredSession[], errors: louiselm.session.DiscoveryError[])
clients: table<string, louiselm.acp.Client>
done: boolean
errors: louiselm.session.DiscoveryError[]
finished: table<string, boolean>
id: integer
remaining: integer
sessions: louiselm.session.DiscoveredSession[]

louiselm.session.Registry¶

agent_limits: table<string, louiselm.session.LimitsState> -- Last observed account-limit state by Agent.
agent_limits_listeners: table<fun(state: louiselm.session.LimitsState), boolean> -- Agent-limit observers.
collect_forensics: fun(self: louiselm.session.Registry, agent_name: string, acp_session_id: string, options?: louiselm.session.ForensicsOptions, callback?: fun(path?: string, error_message?: string)):boolean, string?
create_session: fun(self: louiselm.session.Registry, agent_name: string, options?: louiselm.session.Options, ready_callback?: fun(session?: louiselm.session.Session, error?: string)):(louiselm.session.Session)?, string?
definitions: table<string, louiselm.agent.Definition> -- Normalized named definitions.
discover_sessions: fun(self: louiselm.session.Registry, options?: louiselm.session.DiscoveryOptions, callback: fun(sessions: louiselm.session.DiscoveredSession[], errors: louiselm.session.DiscoveryError[])):boolean, string?
discoveries: table<integer, louiselm.session.DiscoveryState> -- Active adapter discovery operations.
dispose: fun(self: louiselm.session.Registry):boolean, string?
disposed: boolean -- Whether this registry is closed.
flush_recording: fun(self: louiselm.session.Api, callback: fun(error?: louiselm.session.RecordingError)) -- Retry/acknowledge queued facts, including final observations after Disposal.
forensics_store: louiselm.forensics.Store -- Immutable Session Forensics records.
get_session: fun(self: louiselm.session.Registry, id: string):(louiselm.session.Session)?
handle_agent_notification: fun(self: louiselm.session.Registry, session: louiselm.session.Session, message: louiselm.acp.JsonRpcNotification)
inspect_agent_limits: fun(self: louiselm.session.Registry, agent_name: string):(louiselm.session.LimitsState)?, string?
list_permissions: fun(self: louiselm.session.Registry):louiselm.permission.Rule[]?, string?
list_sessions: fun(self: louiselm.session.Registry):string[]
load_session: fun(self: louiselm.session.Registry, agent_name: string, acp_session_id: string, options?: louiselm.session.Options, ready_callback?: fun(session?: louiselm.session.Session, error?: string)):(louiselm.session.Session)?, string?
next_discovery_id: integer -- Next discovery operation number.
next_id: integer -- Next local session number.
on_agent_limits: fun(self: louiselm.session.Registry, callback: fun(state: louiselm.session.LimitsState)):fun()?, string?
order: string[] -- Session ids in creation order.
permission_store: louiselm.permission.Store -- Remembered rules owned by this registry.
recording: louiselm.session.RecordingStore -- Shared durable writer; failed writes gate subsequent prompts.
refresh_agent_limits: fun(self: louiselm.session.Registry, agent_name: string, callback: fun(state: louiselm.session.LimitsState, error?: string)):boolean, string?
remove_session: fun(self: louiselm.session.Registry, id: string)
revoke_permission: fun(self: louiselm.session.Registry, id: string):boolean, string?
sessions: table<string, louiselm.session.Session> -- Live sessions by local id.

louiselm.session.ExitVerdict¶

acp_session_id: string? -- Agent-side Session identifier, once initialized.
agent: string -- Configured Agent name.
recoverable: boolean -- Whether the Agent advertises ACP session/load.
session: louiselm.session.Session -- Live Session represented by this verdict.
turn_active: boolean -- Whether a prompt or autonomous agent processing is still active.

louiselm.session.LimitsStatus¶

louiselm.session.LimitsStatus:
    | "loading"
    | "fresh"
    | "stale"
    | "unavailable"
    | "unsupported"
    | "empty"
    | "unlimited"
    | "not_observed"

louiselm.session.LimitWindow¶

duration_mins: integer -- Exact quota-window duration in minutes.
resets_at: integer -- Unix timestamp in seconds for the next reset.
used_percent: number -- Consumed capacity from zero through one hundred.

louiselm.session.LimitCredits¶

balance: number? -- Remaining workspace credit balance.
unlimited: boolean? -- Whether workspace credits are explicitly unlimited.

louiselm.session.LimitBucket¶

credits: (louiselm.session.LimitCredits)? -- Optional workspace credit state.
id: string -- Stable metered bucket identifier.
label: string? -- Optional user-facing bucket label.
plan_type: string? -- Plan associated with this bucket.
reached_type: string? -- Provider classification for a reached limit.
windows: louiselm.session.LimitWindow[] -- Quota windows for this bucket.

louiselm.session.LimitResetCredit¶

description: string? -- User-facing credit description.
expires_at: integer? -- Unix expiry timestamp in seconds.
id: string? -- Opaque reset-credit identifier.
title: string? -- User-facing credit title.

louiselm.session.LimitResetCredits¶

available_count: integer -- Authoritative available reset-credit count.
credits: louiselm.session.LimitResetCredit[]? -- Optional detail rows.

louiselm.session.LimitsSnapshot¶

buckets: louiselm.session.LimitBucket[] -- Complete normalized bucket list.
default_bucket_id: string? -- Bucket corresponding to the adapter default view.
reset_credits: (louiselm.session.LimitResetCredits)? -- Optional earned reset credits.
unlimited: boolean? -- Whether account limits are explicitly unlimited.

louiselm.session.LimitsState¶

agent: string -- Configured Agent name.
error: string? -- Sanitized reason current data is unavailable or stale.
snapshot: (louiselm.session.LimitsSnapshot)? -- Last good complete snapshot.
status: "empty"|"fresh"|"loading"|"not_observed"|"stale"...(+3) -- Current observation state.
updated_at: integer? -- Local Unix timestamp when the last good snapshot arrived.

louiselm.session.LimitsCapability¶

read_method: string -- ACP custom request returning a complete snapshot.
updated_method: string -- ACP custom notification carrying a complete snapshot.

louiselm.session.ConfigValue¶

description: string? -- Optional agent-provided description.
name: string -- Human-readable value name.
value: string -- Wire value identifier.

louiselm.session.ConfigOption¶

category: string? -- Optional ACP semantic category.
current_value: boolean|string -- Current agent-reported value.
description: string? -- Optional agent-provided description.
id: string -- Wire configuration identifier.
name: string -- Human-readable option name.
options: louiselm.session.ConfigValue[]? -- Select values in agent order.
type: "boolean"|"select" -- Supported input kind.

louiselm.session.ContextUsage¶

percentage: number -- Derived percentage used, clamped to 100 when used exceeds size.
pressure: "critical"|"elevated"|"high"|"normal" -- Passive pressure state.
size: number -- Effective context window size.
stale: boolean -- Whether a model change made this reading stale.
used: number -- Tokens currently in context.

louiselm.session.Cost¶

amount: number -- Agent-reported cumulative amount.
currency: string -- Agent-reported currency.

louiselm.session.TurnUsage¶

cached_read_tokens: number?
cached_write_tokens: number?
input_tokens: number?
output_tokens: number?
thought_tokens: number?
total_tokens: number?

louiselm.session.SessionFailure¶

id: string -- Stable Agent-provided failure identifier.
revision: integer -- Monotonic revision for this identifier.
severity: "error"|"warning" -- Agent-provided urgency.
title: string -- Human-readable status title.

louiselm.session.DiscoveredSession¶

agent: string -- Configured agent definition name.
cwd: string -- Authoritative primary workspace.
session_id: string -- Agent-side ACP session identifier.
title: string? -- Agent-provided display title.
updated_at: string? -- Agent-provided ISO 8601 activity timestamp.

louiselm.session.UsageDimension¶

string

louiselm.session.UsageQuery¶

bucket: ("day"|"hour"|"none")? -- UTC buckets of prepared_at; defaults to none.
filters: table<string, boolean|string|userdata>? -- Conjunction; vim.NIL matches an absent dimension. Turns use starting values.
from: string? -- Inclusive UTC timestamp YYYY-MM-DDTHH:MM:SS[.fff]Z.
group_by: string[]? -- Defaults to no dimensions.
limit: integer? -- Page size, 1..100; defaults to 25.
mixed: ("exclude"|"include"|"only")? -- Defaults to include; fixed-configuration summaries still exclude mixed turns.
offset: integer? -- Zero-based page offset; defaults to zero.
turn_id: string? -- Exact durable turn; events includes that turn’s observations and associated transitions.
until_time: string? -- Exclusive UTC timestamp.
view: ("dimensions"|"events"|"summary"|"turns")? -- Defaults to summary.

louiselm.session.UsageTotals¶

costs: louiselm.session.UsageTotalCurrency[]
outcomes: table<string, integer> -- Counts by observed outcome; unobserved means no terminal observation.
tokens: table<string, louiselm.session.UsageTotalMetric>
turns: integer -- Dispatched turns, including unmeasured and unobserved completions.

louiselm.session.UsageTotalMetric¶

average: number -- Mean over measured turns only.
samples: integer -- Turns reporting this measurement.
total: number -- Sum over measured turns only.

louiselm.session.UsageTotalCurrency¶

average: number -- Mean over measured turns only.
currency: string
samples: integer -- Turns reporting this measurement.
total: number -- Sum over measured turns only.

louiselm.session.UsageRow¶

acp_session_id: string?
agent: string?
bucket_end: string? -- Exclusive UTC bucket boundary.
bucket_start: string? -- Inclusive UTC bucket boundary.
cost_baseline: (louiselm.session.Cost)?
data: table? -- Normalized event metadata, including observed source and established request links.
dimension: string? -- Dimension discovery row.
dimensions: table<string, boolean|string>? -- Summary group; absent values are omitted.
id: string? -- Durable turn ID or option event ID.
kind: string? -- Event kind.
mixed: boolean? -- Changed during turn; excluded from fixed-configuration comparisons.
model: (boolean|string)? -- Starting advertised Model.
observed_at: string? -- Event timestamp.
observer_id: string? -- Option observation stream identity.
options: table<string, boolean|string>? -- Immutable starting tuple.
prepared_at: string?
provider: string? -- Starting resolved Provider.
sequence: integer? -- Order within the recorded stream.
summary: (louiselm.session.UsageTotals)?
turn_id: string? -- Associated durable turn, only when recorded.
value: (boolean|string)? -- Recorded dimension value.

louiselm.session.UsagePage¶

excluded_mixed: integer -- Matching mixed turns excluded from this summary.
mixed_turns: integer -- Mixed turns matching starting-value filters.
next_offset: integer? -- Absent on the last page.
rows: louiselm.session.UsageRow[]
summary: louiselm.session.UsageTotals -- Matching dispatched turns; no Lua aggregation.
timezone: "UTC"
total: integer -- Matching rows, independent of the page size.
view: string

louiselm.session.UsageQueryCallback¶

fun(page?: louiselm.session.UsagePage, error?: louiselm.session.RecordingError)

Typed Events¶

louiselm.session.EventType¶

louiselm.session.EventType:
    | "chunk"
    | "user_chunk"
    | "thought_chunk"
    | "tool_call_started"
    | "tool_call_finished"
    | "permission_requested"
    | "permission_cancelled"
    | "config_options_changed"
    | "commands_changed"
    | "usage_updated"
    | "compaction_updated"
    | "recording_changed"
    | "prompt_rejected"
    | "state_changed"
    | "turn_done"
    | "error"

louiselm.session.EventBase¶

session_id: string -- Local session identifier.

louiselm.session.StateChangedData¶

activity: string? -- Current generic tool activity.
previous_status: ("cancelling"|"configuring"|"disposed"|"error"|"preparing"...(+5))? -- Previous state when the lifecycle changed, absent for refreshes.
status: "cancelling"|"configuring"|"disposed"|"error"|"preparing"...(+5) -- Current lifecycle state.

louiselm.session.StateChangedEvent¶

data: louiselm.session.StateChangedData
session_id: string -- Local session identifier.
type: "state_changed"

louiselm.session.ConfigOptionsChangedEvent¶

data: louiselm.session.ConfigOption[] -- Complete supported option state in agent order. Confirmed value changes are queued for persistence before publication; request attribution lives in option_events.
session_id: string -- Local session identifier.
type: "config_options_changed"

louiselm.session.CommandsChangedData¶

commands: louiselm.session.AvailableCommand[] -- Complete supported command state in agent order.
diagnostics: string[] -- Messages for advertised entries skipped as malformed.

louiselm.session.CommandsChangedEvent¶

data: louiselm.session.CommandsChangedData
session_id: string -- Local session identifier.
type: "commands_changed"

louiselm.session.UsageUpdatedData¶

context: louiselm.session.ContextUsage -- Current context usage.
cost: (louiselm.session.Cost)? -- Current cumulative cost, when reported.

louiselm.session.UsageUpdatedEvent¶

data: louiselm.session.UsageUpdatedData
session_id: string -- Local session identifier.
type: "usage_updated"

louiselm.session.CompactionUpdatedEvent¶

data: louiselm.session.Compaction -- Complete owned snapshot, with stable first-seen placement by ID.
session_id: string -- Local session identifier.
type: "compaction_updated"

louiselm.session.RecordingChangedData¶

error: (louiselm.session.RecordingError)? -- Storage failure or unresolved Session Provider; active work continues, new dispatch requires correction/recovery.
pending: boolean -- Whether this registry has unacknowledged writes.

louiselm.session.RecordingChangedEvent¶

data: louiselm.session.RecordingChangedData
session_id: string -- Local session identifier.
type: "recording_changed"

louiselm.session.PromptRejectedEvent¶

data: { turn_id: string, message: string } -- Asynchronous admission failure; no ACP prompt was sent.
session_id: string -- Local session identifier.
type: "prompt_rejected"

louiselm.session.PermissionData¶

operation: louiselm.permission.Request -- Normalized requested operation.
options: unknown[]? -- Agent-advertised response options.
permission_error: string? -- Non-fatal remembered-permission lookup failure.
policy_decision: "allow"|"ask"|"deny" -- Evaluated policy decision.
remembered_decision: ("allow"|"deny")? -- A matching rule that could not be replayed through the offered option kinds.
request_id: string|number -- ACP request identifier.
toolCall: table? -- Agent tool call payload.

louiselm.session.PermissionEvent¶

data: louiselm.session.PermissionData
respond: fun(result: unknown, error?: louiselm.acp.JsonRpcError):boolean, string? -- Permission response callback.
session_id: string -- Local session identifier.
type: "permission_requested"

louiselm.session.PermissionCancelledData¶

request_ids: (string|number)[] -- ACP requests the session answered on the consumer’s behalf.

louiselm.session.PermissionCancelledEvent¶

data: louiselm.session.PermissionCancelledData
session_id: string -- Local session identifier.
type: "permission_cancelled"

louiselm.session.GenericEvent¶

data: unknown -- Event-specific payload. For “chunk”/“user_chunk”/“thought_chunk” this is
session_id: string -- Local session identifier.
type: "chunk"|"error"|"thought_chunk"|"tool_call_finished"|"tool_call_started"...(+2)

louiselm.session.Event¶

louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5)

louiselm.session.EventCallback¶

fun(event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))

louiselm.session.EventEmitter¶

clear: fun(self: louiselm.session.EventEmitter)
emit: fun(self: louiselm.session.EventEmitter, event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))
listeners: table<integer, fun(event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))>
next_id: integer -- Next listener identifier.
on: fun(self: louiselm.session.EventEmitter, callback: fun(event: louiselm.session.CommandsChangedEvent|louiselm.session.CompactionUpdatedEvent|louiselm.session.ConfigOptionsChangedEvent|louiselm.session.GenericEvent|louiselm.session.PermissionCancelledEvent...(+5))):fun() -- Remove the listener.
order: integer[] -- Listener registration order.

Permission Policies¶

louiselm.permission.Decision¶

louiselm.permission.Decision:
    | "allow"
    | "deny"
    | "ask"

louiselm.permission.Request¶

command: string[]? -- Command argv.
diff: string? -- Proposed file diff.
kind: "command"|"file_edit"|"unknown" -- Operation being requested.
path: string? -- File being edited.

louiselm.permission.Policy¶

evaluate: fun(self: louiselm.permission.Policy, request: louiselm.permission.Request):"allow"|"ask"|"deny", string? -- Evaluate one operation.
name: string -- Policy name.

louiselm.permission.Lifetime¶

louiselm.permission.Lifetime:
    | "session"
    | "always"

louiselm.permission.Context¶

adapter: louiselm.permission.Adapter -- Exact adapter process identity.
agent: string -- Configured agent name.
session_id: string -- Local session identifier.
workspace: string -- Session working directory.

louiselm.permission.Adapter¶

args: string[]
command: string

louiselm.permission.Rule¶

adapter: louiselm.permission.Adapter
agent: string
command: string[]? -- Exact argv prefix.
decision: "allow"|"deny"
id: string -- Stable scope identifier.
kind: "command"|"file_edit"
lifetime: "always"|"session"
path: string? -- Exact normalized file path.
session_id: string? -- Present only for in-memory session rules.
workspace: string

louiselm.permission.Store¶

clear_session: fun(self: louiselm.permission.Store, session_id: unknown):boolean
evaluate: fun(self: louiselm.permission.Store, context: louiselm.permission.Context, request: louiselm.permission.Request):("allow"|"ask"|"deny")?, string?
list: fun(self: louiselm.permission.Store):louiselm.permission.Rule[]?, string?
path: string -- Persistent JSON file.
remember: fun(self: louiselm.permission.Store, context: louiselm.permission.Context, request: louiselm.permission.Request, decision: unknown, lifetime: unknown):(louiselm.permission.Rule)?, string?
revoke: fun(self: louiselm.permission.Store, id: unknown):boolean, string?
session_rules: table<string, louiselm.permission.Rule>

louiselm.permission.HumanPrompt¶

evaluate: fun(self: louiselm.permission.HumanPrompt, request: louiselm.permission.Request):"allow"|"ask"|"deny", string?
name: "ask-human"
prompt: fun(request: louiselm.permission.Request, respond: fun(decision: "allow"|"ask"|"deny")):boolean, string?? -- Ask the presentation layer to decide.

Agent Configuration¶

louiselm.agent.SkillConfig¶

policy: ("inject"|"native"|"off")? -- Agent-specific policy override.

louiselm.agent.CommandCheck¶

args: string[] -- Arguments passed after the command, verbatim (nothing is auto-appended).
command: string -- Executable that prints a version.
env: table<string, string>? -- Environment variables for the process.

louiselm.agent.Definition¶

args: string[] -- Arguments passed after the command.
capabilities: string[]? -- Capability tags this agent declares support for (e.g. “image-generation”). Matched against needs-capability:* beads labels by the agent selecting work; louiselm neither reads beads nor routes work itself.
command: string -- Executable to start.
env: table<string, string>? -- Environment variables for the process.
latest: (louiselm.agent.CommandCheck)? -- Optional command that resolves the latest available version.
options: table<string, unknown>? -- Agent-specific options. options._meta, when present, is threaded
provider: string|louiselm.agent.ProviderPrefixes|louiselm.agent.ProviderRoute[] -- Explicit access/quota service, exact option routes, or literal option prefixes; required before prompting.
skills: (louiselm.agent.SkillConfig)? -- Effective Agent Skills policy after normalization.
transcript_layout: string? -- Optional Provenance integration for locating this Agent’s historical transcripts on disk; live chat transcripts need no configuration.
upgrade: (string|string[])? -- Upgrade executable and arguments, or nonblank manual update instructions. Displayed only, never executed by LouiseLM; only argv can join the combined upgrade command.
version: (louiselm.agent.CommandCheck)? -- Optional override for querying the installed version, when command args... --version is not the right invocation (e.g. a subcommand-based CLI).

louiselm.agent.ConfigErrorType¶

louiselm.agent.ConfigErrorType:
    | "unknown_key"
    | "wrong_type"
    | "missing_required"
    | "invalid_value"

louiselm.agent.ConfigError¶

expected: string? -- Expected type or shape.
got: string? -- Received Lua type.
message: string -- Human-readable failure.
path: string -- Configuration path containing the error.
type: "invalid_value"|"missing_required"|"unknown_key"|"wrong_type"

louiselm.agent.Definitions¶

table<string, louiselm.agent.Definition>

louiselm.agent.HealthResult¶

available: boolean -- Whether the executable is on PATH.
code: integer? -- Version process exit code.
command: string -- Checked executable.
error: string? -- Specific availability or version failure.
latest_error: string? -- Why the latest-version check did not resolve a version.
latest_version: string? -- First line returned by the configured latest-version check.
ok: boolean -- Whether the executable responded with a version.
outdated: boolean? -- True when both the installed and latest versions resolved and differ.
version: string? -- First line returned by --version.

louiselm.agent.ProcessResult¶

code: integer -- Process exit code.
signal: integer -- Process signal, if terminated by a signal.
stderr: string -- Captured standard error.
stdout: string -- Captured standard output.