jobs

Documentation

Overview

Package jobs runs and tracks detached background agent sessions. A job is a child `memcode` process whose output streams to a log file under .memcode/jobs/<id>/; its metadata (task, pid, status) lives beside the log. Background agents are writers, so they coordinate through a single repo-wide writer lock — the "one serialized writer" half of memcode's concurrency model: any number of read-only explorers may run at once, but mutating jobs run one at a time, queueing on the lock rather than clobbering each other's edits.

Index

• Constants
• func AcquireWriter(ctx context.Context, root string) (release func(), err error)
• func Finish(root, id string, exitCode int, result string) error
• func LogPath(root, id string) string
• func Stop(root, id string) error
• type Job
  • func Get(root, id string) (Job, error)
  • func List(root string) ([]Job, error)
  • func Spawn(root, task, mode, tier string, chrome, reportBack bool, session string) (Job, error)

Constants

const (
	StatusRunning = "running"
	StatusDone    = "done"
	StatusFailed  = "failed"
	StatusStopped = "stopped" // process gone but never recorded a finish
)

Status values for a job.

Functions

func AcquireWriter

func AcquireWriter(ctx context.Context, root string) (release func(), err error)

AcquireWriter blocks until this process holds the repo-wide writer lock, then returns a release func. It coordinates background writer jobs so only one mutates the tree at a time; a stale lock (owner process gone) is reclaimed. ctx cancellation aborts the wait.

func Finish

func Finish(root, id string, exitCode int, result string) error

Finish records a job's terminal status (called by the child when it exits). result is the agent's final text, persisted so a report-back job can feed it to the calling LLM.

func LogPath

func LogPath(root, id string) string

LogPath returns the path to a job's log file.

func Stop

func Stop(root, id string) error

Stop terminates a running job: signals its process (SIGTERM, then SIGKILL if it doesn't exit), and records the job as stopped. Returns an error if the job isn't found or isn't running. This is the safety valve for a runaway detached agent — the TUI/CLI equivalent of /kill for in-session shells.

Types

type Job

type Job struct {
	ID         string    `json:"id"`
	Task       string    `json:"task"`
	Mode       string    `json:"mode"`
	Tier       string    `json:"tier,omitempty"`        // "strong" → the detached child runs on the frontier tier (agent_frontier)
	ReportBack bool      `json:"report_back,omitempty"` // true → on finish, feed Result back to the calling LLM (agent{background}), not just the user
	Result     string    `json:"result,omitempty"`      // the agent's final text (set by Finish) — what gets reported back
	PID        int       `json:"pid"`
	Status     string    `json:"status"`
	ExitCode   int       `json:"exit_code"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at,omitempty"`
}

Job is one background agent session.

func Get

func Get(root, id string) (Job, error)

Get returns one job with live status reconciled.

func List

func List(root string) ([]Job, error)

List returns all jobs, newest first, with live status reconciled (a job recorded as running whose process is gone is reported as stopped).

func Spawn

func Spawn(root, task, mode, tier string, chrome, reportBack bool, session string) (Job, error)

Spawn launches a detached `memcode run <task>` child, redirecting its output to the job log, and records the job as running. The child is invoked with --job <id> so it acquires the writer lock and records its own completion. When chrome is true, --chrome is forwarded so backgrounded browser jobs keep the capability (Chrome always launches with a visible window).