room

Documentation

Overview

Package room reads the *room* — the current state of the human↔agent interaction — and turns it into a runtime policy. It is the integration layer the friction/cadence signals feed into: not "is the user angry", but "what is the interaction state, and how should the agent behave right now".

This is a reducer, in the literal memcode sense: it folds the event log (plus the live friction reading) into a RoomState. Normal agents flatten tone, cadence, interrupts, denials, loops and acceptance into plain text and miss when the interaction has changed. memcode treats them as first-class signals.

The output is a policy, because reading the room only matters if behavior changes: under repair the agent executes the user's correction immediately and narrowly (frustration demands ACTION — the 2026-07-18 eggshells incident proved that stall-and-confirm makes an angry user angrier; the prose lives server-side in roomGuidance); when the user is exploring it reasons openly instead of editing; when urgent it gets terse and acts. The Policy fields are ADVISORY — only MemoryWeight is consumed today; the room never tightens the permission gate.

Index

• type Intent
• type Loop
• type Mode
• type Outcome
• type Policy
• type Signals
  • func Gather(ctx context.Context, st store.Store, sessionID string) Signals
• type State
  • func Assess(cur mood.Reading, sig Signals) State
• type Trust

Types

type Intent

type Intent string

Intent is what the user is trying to do right now.

const (
	Working       Intent = "working"       // neutral, making progress
	Exploring     Intent = "exploring"     // curious / idea generation
	Understanding Intent = "understanding" // confused / wants explanation
	Correcting    Intent = "correcting"    // fixing the agent's course
	Executing     Intent = "executing"     // urgent, wants action not talk
)

type Loop

type Loop string

Loop is the risk that the AGENT (not the user) is stuck going in circles.

const (
	NoLoop Loop = "none"
	Rising Loop = "rising"
	Stuck  Loop = "stuck"
)

type Mode

type Mode string

Mode is the agent's operating mode derived from the room.

const (
	Normal  Mode = "normal"
	Repair  Mode = "repair"  // things are going badly — stop and fix
	Explain Mode = "explain" // user is confused — clarify, don't pile on
	Explore Mode = "explore" // user is curious — reason openly
	Execute Mode = "execute" // user is urgent — act, be terse
	Replan  Mode = "replan"  // the agent is looping — re-plan from context
)

type Outcome

type Outcome string

Outcome is the fate of the last agent session (acceptance telemetry).

const (
	OutcomeUnknown   Outcome = "unknown"
	OutcomeAccepted  Outcome = "accepted"  // committed
	OutcomeCorrected Outcome = "corrected" // manually edited after
	OutcomeRejected  Outcome = "rejected"  // reverted / reset
)

type Policy

type Policy struct {
	AllowAutoWrite bool   `json:"allow_auto_write"` // false ⇒ confirm every write
	ShowStatus     bool   `json:"show_status"`      // surface diff/status before continuing
	AskBeforeNext  bool   `json:"ask_before_next"`  // pause for confirmation between steps
	SummarizeLast  bool   `json:"summarize_last"`   // recap the last action
	Terse          bool   `json:"terse"`            // minimize narration
	MemoryWeight   string `json:"memory_weight"`    // normal | strong (for directions given now)
}

Policy is the concrete behavior the runtime should adopt.

type Signals

type Signals struct {
	Interrupts         int
	Denials            int
	RepeatedCorrection bool
	LoopRisk           Loop
	LastOutcome        Outcome
}

Signals are the event-derived inputs to the reducer (separate from the live friction reading so Assess stays a pure, testable function).

func Gather

func Gather(ctx context.Context, st store.Store, sessionID string) Signals

Gather reduces the recent event log into Signals (interrupts, denials, loop risk, last session outcome).

type State

type State struct {
	Friction  string  `json:"friction"`   // low | elevated | high (from mood)
	MoodState string  `json:"mood_state"` // the mood.State
	Intent    Intent  `json:"intent"`
	Urgency   string  `json:"urgency"` // low | medium | high
	Trust     Trust   `json:"trust"`
	LoopRisk  Loop    `json:"loop_risk"`
	Outcome   Outcome `json:"last_outcome"`
	Mode      Mode    `json:"mode"`
	Policy    Policy  `json:"policy"`
}

State is the assessed room.

func Assess

func Assess(cur mood.Reading, sig Signals) State

Assess folds the live friction reading and the event-derived signals into a RoomState + Policy. Pure and deterministic.

type Trust

type Trust string

Trust is the direction the user's confidence is moving.

const (
	Steady   Trust = "steady"
	Dropping Trust = "dropping"
	Low      Trust = "low"
)