omp

Documentation

Overview

Package omp finds the omp (oh-my-pi) agents running on the machine and what they are doing, from what is on disk: the omp processes (their working directory, and for an agent beekeeper started its environment) and the session files omp writes under ~/.omp/agent/sessions, one JSON line per entry: a title line (rewritten in place), the session header (id, cwd), model changes, and messages of the roles user, assistant and toolResult.

omp keeps no record of which process runs which session file and holds none open: a process runs the session file of its working directory that it created (the header's time is the first one at or after its start), else the one written last since it started (a resumed session).

Index

• Constants
• Variables
• func Discover(sessionsDir string, t *proc.Table, now time.Time) []*claude.Session
• func Ended(sessionsDir string, running []*claude.Session, since time.Time) []*claude.Session
• func Follow(path string, n int) ([]claude.Turn, error)
• func InboxPath(stateDir, id string) string
• func MakeInbox(path string) error
• func ProviderKey(path, provider string) (string, error)
• func ReadTranscript(path string, now time.Time) (claude.Work, claude.Activity)
• func RemoveInbox(path string) (removed bool, err error)
• func Send(path, msg string) error
• func ShellArgv(path string, credentials []string, argv ...string) []string
• func SpendTranscripts(dir string, from, to time.Time) []claude.SpendTranscript
• func Tail(path string, n int) ([]claude.Turn, error)
• func ToolShellPath(stateDir string) string
• func Write(path string, write func(w io.Writer) error) error
• func WriteToolShell(stateDir string) (string, error)

Constants

const (
	EnvAgent = "BEEKEEPER_OMP_AGENT"
	EnvName  = "BEEKEEPER_AGENT_NAME"
)

The environment beekeeper starts an omp agent with: its start id and its roster name, which no session file carries.

const (
	StateBusy  = "busy"
	StateIdle  = "idle"
	StateEnded = "ended"
)

The session states: busy while a turn runs, idle while it waits for a message, ended when no process runs the session.

const Comm = "omp"

Comm is the omp binary's process name.

const EnvCredentials = "BEEKEEPER_OMP_CREDENTIALS" //nolint:gosec // the variables' names, no value

EnvCredentials lists, in an omp agent's environment, the variables that carry a provider's key, separated by spaces: what ToolShell drops.

const Harness = "omp"

Harness is the harness name omp sessions carry (claude.Session.Harness).

const HostPrefix = "omp_"

HostPrefix makes a start id the agent's host session id on the roster: omp_<start id>.

const ToolShell = `#!/bin/sh
# beekeeper's bash for an omp agent's tool commands: the provider keys omp
# runs on stay omp's.
for n in $` + EnvCredentials + `; do unset "$n"; done
exec /bin/bash "$@"
`

ToolShell is the shell omp runs the agent's tool commands in (SHELL): bash without the provider keys of EnvCredentials, which omp passes on with the rest of its environment.

Variables

var ErrKeyValue = errors.New("the models file carries the key itself")

ErrKeyValue is a provider whose apiKey in the models file is a value, which the file then carries.

var ErrNotRunning = errors.New("no omp process reads its inbox")

ErrNotRunning is a message to an agent whose inbox no process reads.

var VarName = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)

VarName is the form of a variable's name as a provider's apiKey names one: upper case, as omp's own variables are named. A key is no name.

Functions

func Discover

func Discover(sessionsDir string, t *proc.Table, now time.Time) []*claude.Session

Discover returns the running omp sessions, newest first. A session's process may not have written its session file yet (omp creates it with the first message): it is listed without a transcript. A process that another omp process started (a subagent) belongs to that session.

func Ended

func Ended(sessionsDir string, running []*claude.Session, since time.Time) []*claude.Session

Ended returns the omp sessions written to since since that no running session runs, most recently active first.

func Follow

func Follow(path string, n int) ([]claude.Turn, error)

Follow is Tail with the agent's tool calls among the turns, as claude.Follow returns them.

func InboxPath

func InboxPath(stateDir, id string) string

InboxPath is the inbox of the agent started under id, in beekeeper's state folder.

func MakeInbox

func MakeInbox(path string) error

MakeInbox creates the inbox FIFO at path, keeping one that exists.

func ProviderKey

func ProviderKey(path, provider string) (string, error)

ProviderKey reads how provider gets its key in the models file at path: the name of the variable it reads it from (VarName), "" for no key (no apiKey, a keyless provider, or none the file has; a missing file has none), or ErrKeyValue when the file holds a value instead of a name.

func ReadTranscript

func ReadTranscript(path string, now time.Time) (claude.Work, claude.Activity)

ReadTranscript reads an omp session file's window for the issues and repositories it is about and its activity: turns (the person's messages), tool calls and failed ones, tokens and cost as omp counted them, and the context its last reply had.

func RemoveInbox

func RemoveInbox(path string) (removed bool, err error)

RemoveInbox removes the inbox at path and its lock file; removed is false when there was none. A process that still reads the inbox keeps its open end, but no message reaches it any more.

func Send

func Send(path, msg string) error

Send writes msg to the inbox at path as one steer command. It never blocks on an inbox no process reads: that refuses it (ErrNotRunning).

func ShellArgv

func ShellArgv(path string, credentials []string, argv ...string) []string

ShellArgv runs argv, omp's command line, with its stdin on the inbox at path: opened for reading and writing, so the inbox never reaches its end while the agent runs, whoever writes to it. Before omp runs, the shell reads one NAME=value line from the inbox for each variable named in credentials and exports it: the provider keys beekeeper hands over, which then live in omp's environment alone. A line that is not the named variable's ends the unit (exit 78), as a key that does not arrive would. omp's protocol output goes nowhere; its log is omp's own (~/.omp/logs) and the unit's journal keeps its errors.

func SpendTranscripts

func SpendTranscripts(dir string, from, to time.Time) []claude.SpendTranscript

SpendTranscripts reads the requests from from up to to of every session file under dir: a session's file in its working directory's folder, its subagents' in the session's own folder below that. A file last written before from has none and is not read; without dir there are none.

func Tail

func Tail(path string, n int) ([]claude.Turn, error)

Tail returns the last n turns of an omp session file: the person's and beekeeper's messages and the agent's words, without thinking, tool calls and tool results.

func ToolShellPath

func ToolShellPath(stateDir string) string

ToolShellPath is where beekeeper keeps ToolShell under its state folder, named bash so that omp takes it for the bash it is.

func Write

func Write(path string, write func(w io.Writer) error) error

Write runs write with the inbox at path open for writing, or refuses when no process reads the inbox (ErrNotRunning). Writes are serialized by a lock file beside the inbox (macOS locks no FIFO), so two writers' lines never interleave, whatever their length.

func WriteToolShell

func WriteToolShell(stateDir string) (string, error)

WriteToolShell puts ToolShell at ToolShellPath, executable, and answers the path; one there with the same content stays.