Graph Surface

Psi exposes a self-describing EQL graph at session root. This graph surface is intended to help humans and future ψ discover what is queryable before guessing attribute names or internal paths.

Purpose

The graph surface provides:

• a compact summary of registered resolvers and mutations
• a capability-oriented graph view over the live query system
• a canonical list of attrs reachable from session-root seeds
• a stable discovery workflow for interactive querying

What this graph is

This is a capability graph.

• Nodes represent operations and domain capabilities.
• Edges represent operation -> capability membership.
• Edge :attribute values annotate those edges with operation IO attrs.

What this graph is not

This is not a full dependency graph.

• Edges do not represent resolver dependency flow.
• Edges do not represent attr-to-resolver links as standalone nodes.
• Edges do not directly encode root reachability.

Canonical discovery workflow

When exploring a running psi instance, prefer this sequence:

1. Query the graph surface for discovery metadata.
2. Read :psi.graph/root-queryable-attrs.
3. Read :psi.graph/capabilities and :psi.graph/domain-coverage.
4. Query the discovered attrs directly.

Examples:

[:psi.graph/root-seeds]
[:psi.graph/root-queryable-attrs]
[:psi.graph/capabilities]
[:psi.graph/domain-coverage]

Then query discovered attrs directly, for example:

[:psi.agent-session/phase :psi.agent-session/model]
[:git.repo/status :git.worktree/count]
[:psi.memory/status]

Session-admin discovery example:

[:psi.runtime-session/active-id
 {:psi.agent-session/context-session-summaries
  [:psi.session-info/id
   :psi.session-info/display-name
   :psi.session-info/created
   :psi.session-info/updated
   :psi.session-info/parent-session-id
   :psi.session-info/worktree-path]}]

Canonical session-admin flow:

1. query :psi.runtime-session/active-id
2. query :psi.agent-session/context-session-summaries
3. choose explicit non-active session ids in caller logic
4. invoke psi-tool(action: "mutate") with psi.extension/close-session

This keeps target selection explicit in caller logic while routing the actual write through the same registered mutation path the runtime already owns.

Prompt lifecycle introspection example:

[:psi.agent-session/last-prepared-turn-id
 :psi.agent-session/last-prepared-message-count
 :psi.agent-session/last-execution-turn-id
 :psi.agent-session/last-execution-turn-outcome
 :psi.agent-session/last-execution-stop-reason]

Root discovery

Notable session-admin root attrs include:

• :psi.runtime-session/active-id — the invoking runtime session id from the live query context
• :psi.runtime-session/list — the explicit in-memory runtime session inventory
• :psi.runtime-session/count — the in-memory runtime session count
• :psi.persisted-session/list — the persisted session inventory for the current worktree
• :psi.persisted-session/list-all — the persisted session inventory across all project directories
• :psi.agent-session/context-session-summaries — compact live runtime context summary for safe operational selection

:psi.graph/root-seeds

The root context attrs injected for session-root querying.

Current seeds are:

• :psi/agent-session-ctx
• :psi/memory-ctx
• :psi/recursion-ctx
• :psi/engine-ctx

These seeds are diagnostic/discovery information. They are not included in :psi.graph/root-queryable-attrs.

:psi.graph/root-queryable-attrs

A sorted vector of keyword attrs reachable from the root seeds via resolvers.

Contract:

• derived by fixed-point reachability
• resolver outputs only
• mutations do not contribute
• seed attrs themselves are excluded
• only keyword attrs are returned
• sorted for deterministic discovery

Graph summary attrs

:psi.graph/resolver-count

Count of registered resolver operations in the introspected graph.

:psi.graph/mutation-count

Count of registered mutation operations in the introspected graph.

:psi.graph/resolver-syms

Set of qualified resolver symbols.

:psi.graph/mutation-syms

Set of qualified mutation symbols.

:psi.graph/env-built

Boolean indicating that a non-empty introspection graph/env is available.

This should be read as a practical readiness signal for graph discovery, not as proof of a stronger internal compiler lifecycle state.

Graph structure attrs

:psi.graph/nodes

Vector of graph nodes.

Node types are restricted to:

• :resolver
• :mutation
• :capability

Typical node fields include:

• :id
• :type
• :domain
• :symbol for operation nodes
• :operation-count for capability nodes

:psi.graph/edges

Vector of graph edges.

Each edge includes:

• :from
• :to
• :attribute

Edge semantics:

• :from is an operation node id
• :to is a capability node id
• :attribute annotates the edge with one IO attr from that operation

:attribute may be:

• a keyword attr
• a join map attr
• nil when an operation has no IO attrs

Domain summary attrs

:psi.graph/capabilities

Rich per-domain summaries for domains present in the graph.

Typical fields include:

• :id
• :domain
• :operation-count
• :resolver-count
• :mutation-count
• :operation-symbols
• :attributes

This surface is useful when you want a richer picture of what a domain exposes.

:psi.graph/domain-coverage

Normalized per-domain operation counts.

Fields:

• :domain
• :operation-count
• :resolver-count
• :mutation-count

This surface differs from :psi.graph/capabilities:

• capabilities reports only domains present in the graph
• domain-coverage includes required zero-count domains

Current required domains are:

• :ai
• :history
• :agent-session
• :introspection

Example queries

Full graph summary

[:psi.graph/resolver-count
 :psi.graph/mutation-count
 :psi.graph/resolver-syms
 :psi.graph/mutation-syms
 :psi.graph/env-built
 :psi.graph/nodes
 :psi.graph/edges
 :psi.graph/capabilities
 :psi.graph/domain-coverage]

Root discovery summary

[:psi.graph/root-seeds
 :psi.graph/root-queryable-attrs]

Capability-oriented exploration

[:psi.graph/capabilities
 :psi.graph/domain-coverage]

Worktree discovery from session root

[:git.worktree/list
 :git.worktree/current
 :git.worktree/count
 :git.worktree/inside-repo?]

Related files

Implementation:

• components/agent-session/src/psi/agent_session/resolvers.clj
• components/introspection/src/psi/introspection/graph.clj

Tests:

• components/agent-session/test/psi/agent_session/graph_surface_test.clj
• components/introspection/test/psi/introspection/graph_test.clj