live

Documentation

Overview

Package live implements the live peek: "what is the agent on that machine doing right now". It has two halves behind one small surface — a serving half that enumerates and renders THIS machine's in-progress sessions straight from the transcript files (filesystem-fresh, the index and the archive are never touched), and a client half that SSHes a named machine and invokes the remote rawclaw's serving half over the pipe. One hop, seconds-fresh, raw bytes rendered without interpretation.

Index

• Constants
• func FormatAge(secs int64) string
• func ServeList(w io.Writer, limit int) error
• func ServeSession(w io.Writer, prefix string, tail int, includeTools, jsonOut bool) error
• type Client
  • func NewClient(machine, dest string) *Client
  • func (c *Client) List(ctx context.Context, w io.Writer, limit int, jsonOut bool) error
  • func (c *Client) Session(ctx context.Context, w io.Writer, prefix string, tail int, ...) error
• type Session

Constants

const DefaultListLimit = 10

DefaultListLimit caps the session list when the caller passes no limit.

const DefaultSessionTail = 40

DefaultSessionTail is how many trailing messages a session render shows when the caller passes no tail — enough to see what the agent is doing right now without replaying the whole session.

Functions

func FormatAge

func FormatAge(secs int64) string

FormatAge renders seconds as a compact "how long ago": 42s, 5m, 3h, 2d. Exported because the client half renders remote-computed ages with it.

func ServeList

func ServeList(w io.Writer, limit int) error

ServeList writes the machine's top-level sessions as a JSON array ordered by last activity (file mtime) descending, capped at limit (<=0 = default). An empty corpus is an empty array, not an error — the client renders the "nothing recent" story. This is the pipe format `rawclaw live --serve` speaks; keep it append-only compatible.

func ServeSession

func ServeSession(w io.Writer, prefix string, tail int, includeTools, jsonOut bool) error

ServeSession renders the current transcript of the top-level session whose id starts with prefix: a one-shot read of the live file, so messages written seconds ago are included. tail caps the rendered messages (<=0 = default); includeTools opts the human render into tool calls (stripped by default, matching the display posture of every other surface); jsonOut switches to the machine shape, which always carries the raw text. An unmatched or ambiguous prefix is a distinct, actionable error.

Types

type Client

type Client struct {
	Machine string
	Dest    string
	// contains filtered or unexported fields
}

Client peeks one remote machine over SSH. Machine is the user-facing name (for error stories); Dest is the ssh destination it resolved to.

func NewClient

func NewClient(machine, dest string) *Client

NewClient returns a client dialing dest (as resolved from machine) with the real ssh adapter.

func (*Client) List

func (c *Client) List(ctx context.Context, w io.Writer, limit int, jsonOut bool) error

List invokes the remote rawclaw's serving half and renders its session list: a human table by default (remote-computed ages, so clock skew never lies), or the raw JSON bytes under jsonOut. limit<=0 uses the serve default.

func (*Client) Session

func (c *Client) Session(ctx context.Context, w io.Writer, prefix string, tail int, includeTools, jsonOut bool) error

Session streams the remote rendering of one in-progress session — a one-hop read of the live transcript, so messages written seconds ago are included. The remote bytes pass through verbatim (text or, under jsonOut, JSON). includeTools crosses the pipe only when set: the stripped render is the remote's own default, so the default peek stays compatible with remotes that predate the flag.

type Session

type Session struct {
	SessionID    string `json:"session_id"`
	Source       string `json:"source"`  // "claude" | "codex"
	Project      string `json:"project"` // basename of the working dir ("" if unknown)
	CWD          string `json:"cwd,omitempty"`
	LastActivity string `json:"last_activity"` // marked-UTC RFC3339 (timefmt seam), from the file mtime
	AgeSeconds   int64  `json:"age_seconds"`   // now - mtime on the serving machine
	SizeBytes    int64  `json:"size_bytes"`
}

Session is one row of the live session list — the JSON contract between the serving half (remote) and the client half (local). Age is computed on the serving machine against its own clock, so cross-machine clock skew never distorts the "how fresh is this" story.