Documentation
¶
Overview ¶
Package workspace implements the durable, harness-agnostic agent workspace introduced in slice 7.5 of v0.7.
A workspace is a DIRECTORY shared across the steps of a scheduler DAG. It holds:
- .agentctl-workspace.db — a SQLite key/value store for structured memory (the workspace_remember / workspace_recall tools).
- notes.md — an append-only journal (the workspace_note_append tool).
- the step output files written by `agentctl run --output-file` (surfaced by the workspace_list_outputs tool).
The memory tools are exposed to the AGENT over MCP, not as harness-specific native tools, so the same workspace works whether the run uses the Pi adapter or the opencode adapter. agentctl itself is the MCP server (see the `__workspace-mcp` hidden subcommand); this package is the storage layer behind it.
SQLite choice mirrors the session store (slice 6.2): modernc.org/sqlite (pure Go, no CGO) so agentctl stays cross-compilable, WAL + a busy timeout for safe concurrent access, and 0600 perms because remembered values can be sensitive.
Index ¶
- Constants
- type KV
- type Output
- type Workspace
- func (w *Workspace) AppendNote(note string) error
- func (w *Workspace) Close() error
- func (w *Workspace) Dir() string
- func (w *Workspace) ListOutputs() ([]Output, error)
- func (w *Workspace) Recall(ctx context.Context, key string) (value string, found bool, err error)
- func (w *Workspace) RecallAll(ctx context.Context) ([]KV, error)
- func (w *Workspace) Remember(ctx context.Context, key, value string) error
Constants ¶
const DBFileName = ".agentctl-workspace.db"
DBFileName is the SQLite database basename inside a workspace dir. It is hidden (leading dot) and excluded from workspace_list_outputs — it is agentctl's bookkeeping, not a step artifact.
const NotesFileName = "notes.md"
NotesFileName is the append-only journal basename inside a workspace dir. Unlike the DB it IS a regular handoff artifact: it shows up in list_outputs and a downstream step can read it with --input note=@notes.md.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Workspace ¶
type Workspace struct {
// contains filtered or unexported fields
}
Workspace is a handle to one workspace directory + its SQLite KV store. Safe for concurrent use within a process (SQLite serializes writes); across processes the WAL + busy timeout cover concurrent DAG steps that point --workspace at the same dir.
func Open ¶
Open opens (creating if needed) the workspace rooted at dir. The dir is created 0o700 when absent; the DB + its WAL/SHM sidecars are chmod'd 0o600 because remembered values can be secrets. dir must be a real filesystem path (no `file:` URI / `?` DSN forms — same restriction the session store documents).
func (*Workspace) AppendNote ¶
AppendNote appends a timestamped line to notes.md in the workspace dir.
Notes live in a FILE (not the DB) on purpose: the journal is then a first-class handoff artifact — it appears in ListOutputs and a downstream step can consume it with `--input note=@<dir>/notes.md`. The write uses O_APPEND so concurrent small appends from sequential DAG steps don't truncate each other; the workspace model assumes steps sharing a dir run sequentially, which is the common scheduler pattern.
func (*Workspace) ListOutputs ¶
ListOutputs returns the regular files in the workspace dir — the step artifacts written by `--output-file`, plus notes.md. The internal SQLite files (.agentctl-workspace.db + WAL/SHM sidecars) are excluded: they are agentctl bookkeeping, not step outputs. Results are sorted by name for determinism.
func (*Workspace) Recall ¶
Recall returns the value for key. found is false when the key was never remembered (distinct from a remembered empty string).
Source Files