introspect

Documentation

Overview

Package introspect is memcode's read-only intelligence surface — the commands the agent reaches through the single `memcode` tool (overview, map, context, why, recall, next, recap, memories, sources, session, acceptance, doctor, jobs) and the TUI's "orient me" slash shortcuts, plus the two ambiguity classifiers (plan-intent, follow-up steer-vs-queue) and the personality greeting.

It was carved off the agent Session god-object. The Engine reaches Session state through a narrow Deps struct (data fields + a few callbacks), so the package depends on neither runtime nor the full Session type — the import direction stays runtime → introspect (a clean leaf below the agent hub).

Index

• type Deps
• type Engine
  • func New(d Deps) *Engine
  • func (e *Engine) ArchDoc() string
  • func (e *Engine) Intelligence(ctx context.Context, command, arg string) (string, bool)
  • func (e *Engine) MemcodeTool(ctx context.Context, input json.RawMessage) (string, bool)
  • func (e *Engine) PersonalityBlurb(ctx context.Context) string
• type Redactor

Types

type Deps

type Deps struct {
	Root         string
	Store        store.Store
	Runner       *llm.Runner
	Prov         provider.ModelProvider // raw provider, for capability checks (doctor) + the ClassifyFollowup guard
	Redactor     Redactor
	SessionID    string
	Model        string
	Personality  string // chosen voice; drives PersonalityBlurb
	LastUserText string // the active task (set by scoreTurn); ClassifyFollowup's anchor

	// ToolLine prints a tool-call marker line (runtime's s.toolLine). May be nil.
	ToolLine func(shown bool, verb, arg, status string, failed bool)
	// Complete runs a side-channel LLM call through the session's instrumented plumbing
	// (wire trace — runtime's s.sideComplete). May be nil (tests) → falls back to Runner.
	Complete func(ctx context.Context, purpose llm.Purpose, req wire.Request) (wire.Response, error)
	// ExtraChecks appends session-scoped rows to /doctor (runtime's classifier traffic —
	// s.classifierChecks). May be nil.
	ExtraChecks func() []doctor.Result
	// ChatRequest stamps the session chat spec (personality fact + redaction) onto
	// a request — runtime's s.chatSpec("").request. Used by PersonalityBlurb. May be nil.
	ChatRequest func(wire.Request) wire.Request
	// Jobs dispatches the shell-management command (list|kill|tail) — runtime's
	// s.introspectJobs, which stays on Session (it's the shell domain, not introspection).
	Jobs func(target string) (string, bool)
}

Deps is the subset of *runtime.Session the introspection commands need. The runtime.Session fills it (via s.introspect()) and constructs an Engine. Data fields hold session state; the callbacks are the runtime-internal seams the commands call through (tool-line rendering, chat-spec request building, and the job-management dispatch that stays on Session).

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

Engine answers the read-only intelligence commands over a Deps. Construct one per call with New; it holds no mutable state of its own.

func New

func New(d Deps) *Engine

New builds an Engine over the given dependencies.

func (*Engine) ArchDoc

func (e *Engine) ArchDoc() string

ArchDoc renders the architecture/flow diagrams extracted verbatim from the repo's docs (ARCH.md / README). Deterministic — no model, no synthesis.

func (*Engine) Intelligence

func (e *Engine) Intelligence(ctx context.Context, command, arg string) (string, bool)

Intelligence runs a read-only memcode intelligence command (predict, overview, …) and returns its text — used by the TUI's "orient me" slash shortcuts. arg fills target/query for the commands that take one. Same code path as the agent's memcode tool, so the answer is identical to `memcode <command>`.

func (*Engine) MemcodeTool

func (e *Engine) MemcodeTool(ctx context.Context, input json.RawMessage) (string, bool)

MemcodeTool dispatches the single `memcode` agent tool into memcode's own intelligence — calling the internal packages DIRECTLY (no subprocess, no shell strings), so the agent uses memcode through one structured, instrumentable tool instead of re-deriving everything by hand.

func (*Engine) PersonalityBlurb

func (e *Engine) PersonalityBlurb(ctx context.Context) string

PersonalityBlurb asks the model for a one-line greeting in the CURRENTLY-set voice — a quick taste so the user immediately hears the personality they just picked. It reuses the chat spec (which carries the personality fact, so the doctrine composer applies the voice envelope), runs ONE tool-less call on a cheap model with a hard cost fuse, and is best-effort: any error or an empty voice returns "" and the caller simply prints nothing.

type Redactor

type Redactor interface {
	Redact(s string) string
}

Redactor is the redaction seam (runtime's *secrets.Redactor satisfies it). Defined here so introspect needn't import the secrets package.