workspaceio

type ArtifactRef ¶

type ArtifactRef struct {
	// SavedAs is the artifact key returned by the artifact service.
	SavedAs   string
	Version   int
	Ref       string
	MIMEType  string
	SizeBytes int64
	// Path is the workspace-relative source path that was persisted.
	Path string
}

ArtifactRef describes a workspace file that has been persisted via Workspace.SaveArtifact. Field names mirror the workspace_save_artifact LLM tool output schema so callers can move between the two without a translation layer.

type File ¶

type File struct {
	Path      string
	Data      []byte
	MIMEType  string
	SizeBytes int64
	Truncated bool
}

File is an in-memory snapshot of a workspace file produced by Workspace.Collect. It mirrors the fields of codeexecutor.File but uses []byte for Data so callers can mutate it freely. Truncated reports whether the backend hit its internal read cap; the framework does not act on it — callers should check the flag themselves and decide whether to retry, fail, or accept the partial bytes.

type SaveArtifactOption ¶

type SaveArtifactOption func(*SaveArtifactOptions)

SaveArtifactOption mutates SaveArtifactOptions.

func WithSaveArtifactMaxBytes(n int64) SaveArtifactOption

type SaveArtifactOptions ¶

type SaveArtifactOptions struct {
	MaxBytes int64
}

SaveArtifactOptions controls Workspace.SaveArtifact behavior.

type Workspace ¶

type Workspace struct {
	// contains filtered or unexported fields
}

Workspace is a thin facade over codeexecutor.WorkspaceFS plus ProgramRunner, bound to the current invocation's workspace. Use WorkspaceFromContext from inside agent callbacks (BeforeAgent / AfterAgent / BeforeTool / AfterTool / BeforeModel / AfterModel / your own tool's Run) to obtain one; tests can also construct one directly via New.

The methods are deliberately thin pass-throughs to the underlying codeexecutor backend — the framework does not impose extra budgets, truncation policies, or batch loops on top. Callers that want those policies write them in the callback.

Type shape:

Workspace is intentionally a concrete type rather than an interface. Backend variation lives one layer below at codeexecutor.WorkspaceFS and codeexecutor.ProgramRunner; Workspace is a single user-facing facade on top of any engine. Promoting it to an interface should wait until a second user-facing implementation actually exists (for example, a remote workspace client speaking RPC instead of going through Engine).

The zero value is not usable; obtain a *Workspace via WorkspaceFromContext (or New from tests / framework wiring).

Concurrency:

Workspace has no internal locking. The struct simply forwards each call to the underlying codeexecutor backend, so concurrent callers inherit whatever guarantees that backend offers. The framework does not standardize those guarantees; in practice callbacks should serialize their workspace operations when ordering matters (a PutFiles followed by a Collect against the same path is the canonical example).

Scope and backend caveats:

• Workspace always operates on the current invocation's workspace. Path arguments are interpreted relative to the workspace root (or to the workspace ${WORK} / ${OUT} / ${RUNS} env paths). Workspace never reaches outside the workspace, never touches the skill / profile store, and never references arbitrary remote filesystems.
• Whether two nodes can read the same workspace depends entirely on the executor backend. local/container executors are single-node by construction; pcg123 + CFS can persist if the backend is configured to share the same workspace id, and cube-style sandboxes depend on whether the runtime exposes a stable workspace handle. Mirror state into your own shared store from a callback when you need cross-node visibility.

func New(
	exec codeexecutor.CodeExecutor,
	reg *codeexecutor.WorkspaceRegistry,
) *Workspace

func WorkspaceFromContext(ctx context.Context) (*Workspace, bool)

func (w *Workspace) Collect(
	ctx context.Context,
	patterns ...string,
) ([]*File, error)

func (w *Workspace) PutFiles(
	ctx context.Context,
	files ...codeexecutor.PutFile,
) error

func (w *Workspace) RunProgram(
	ctx context.Context,
	spec codeexecutor.RunProgramSpec,
) (codeexecutor.RunResult, error)

func (w *Workspace) SaveArtifact(
	ctx context.Context,
	relPath string,
	opts ...SaveArtifactOption,
) (*ArtifactRef, error)

func (w *Workspace) StageInputs(
	ctx context.Context,
	specs []codeexecutor.InputSpec,
) error