What causes "process options not available" in sipeed/picoclaw?

Pass process options (with Dispatch.SessionKey set) when constructing the agent loop/runtime

process options not available

Error message

process options not available

What it means

The StopActiveTurn hook requires the process options (opts) to know the dispatch session key it must interrupt; opts == nil means the runtime was built without process options, so there is no session to stop. The hook returns before calling stopActiveTurnForSession.

Source

Thrown at pkg/agent/agent_command.go:279

			info := al.GetActiveTurn()
			if info == nil {
				return nil
			}
			return info
		},
		SwitchChannel: func(value string) error {
			if al.channelManager == nil {
				return fmt.Errorf("channel manager not initialized")
			}
			if _, exists := al.channelManager.GetChannel(value); !exists && value != "cli" {
				return fmt.Errorf("channel '%s' not found or not enabled", value)
			}
			return nil
		},
	}
	rt.StopActiveTurn = func() (commands.StopResult, error) {
		if opts == nil {
			return commands.StopResult{}, fmt.Errorf("process options not available")
		}
		return al.stopActiveTurnForSession(opts.Dispatch.SessionKey)
	}
	if agent != nil && agent.ContextBuilder != nil {
		rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
	}
	rt.ReloadConfig = func() error {
		if al.reloadFunc == nil {
			return fmt.Errorf("reload not configured")
		}
		return al.reloadFunc()
	}
	if agent != nil {
		if agent.ContextBuilder != nil {
			rt.ListSkillNames = agent.ContextBuilder.ListSkillNames
		}
		rt.GetModelInfo = func() (string, string) {
			return agent.Model, resolvedCandidateProvider(agent.Candidates, cfg.Agents.Defaults.Provider)

View on GitHub (pinned to 49183d7e8d)

Solutions

Pass process options (with Dispatch.SessionKey set) when constructing the agent loop/runtime
Guard callers: only surface the stop command when process options are available
If using the stock CLI, restart the process — this indicates broken startup wiring

Defensive patterns

Strategy: type-guard

Validate before calling

if opts == nil { /* do not expose stop/turn commands this session */ }

Type guard

func stopAvailable(opts *ProcessOptions) bool { return opts != nil }

Try / catch

_, err := rt.StopActiveTurn()
if err != nil && strings.Contains(err.Error(), "process options not available") {
    // wiring defect: surface loudly, never retry-loop
}

Prevention

Always construct runtimes with process options that carry Dispatch.SessionKey
Register turn/session commands only when opts are present
Assert opts != nil in constructors when the command set is enabled

When it happens

Trigger: Issuing a stop/interrupt command in an AgentLoop constructed without ProcessOptions (tests, embedded runtimes); calling rt.StopActiveTurn programmatically on a bare runtime; startup ordering where opts are injected after the command table.

Common situations: Embedders wiring commands before process options exist; unit tests exercising the runtime in isolation; refactors that made opts optional in one constructor path.

Related errors

AI-assisted analysis of sipeed/picoclaw@49183d7e8d (2026-08-15). Data as JSON: /api/errors/d6ed88ba10665785. Report an issue: GitHub.