memaxagent

README

Memax Agent SDK

A Go SDK for autonomous agents with application-owned tools and host-controlled policy.

Memax Agent SDK is a Go SDK for building autonomous agents with application-owned tools, host-controlled policy, and provider-neutral orchestration.

It is designed for teams that want agent behavior without hard-coding access to the local filesystem, shell, browser, network, inbox, calendar, or other OS capabilities into the runtime. In Memax, those capabilities are exposed as tools owned by the host application.

The result is an agent runtime that is easier to embed, test, secure, observe, and adapt across different products and environments.

Why Memax Agent SDK

Most agent systems couple orchestration tightly to a fixed environment. Memax is built around a different model:

• Tools are owned by the host application. The SDK does not assume direct access to files, commands, web, or external services.
• Policies stay outside the core runtime. Approval, permissions, budgets, checkpoints, storage, and tool implementations remain application decisions.
• Providers are replaceable. Model integrations are exposed through provider-neutral interfaces, with support for multiple providers.
• Sessions are durable and inspectable. The runtime is designed for resumable work, event streaming, and host-side observability.
• Stacks are composable. You can build from the low-level runtime or start from higher-level presets for coding, personal-assistant, and managed-worker workflows.

What the SDK includes

Runtime kernel

The core runtime provides the orchestration primitives needed to run an agent in an application-controlled environment:

• provider-neutral model streaming interfaces
• session lifecycle management and append-only persistence
• resumable and forkable sessions
• context-window policies, summarization, and compaction
• structured tool registry and execution
• JSON Schema validation for tool inputs and structured outputs
• permission hooks and approval callbacks
• task state, planner integration, and bounded subagents
• run budgets for turns, model calls, tool calls, tokens, and duration
• usage events, traces, and observability hooks

Capability adapters and toolkits

The repository also includes host-owned toolkits and adapters for common agent capabilities, including:

• workspace, patch, diff, restore, and checkpoint operations
• command execution and verification backends
• web search and fetch contracts
• memory and result storage integration
• scheduling, messaging, notes, and telemetry support

Opinionated stacks

For faster adoption, the SDK includes reusable stacks built on the same runtime:

• stack/coding for coding-agent workflows
• stack/personal for personal-assistant and knowledge workflows
• stack/cloudmanaged for managed multi-tenant worker workflows

These stacks provide pre-wired policies, tools, and presets while preserving the same host-owned execution model.

Current status

Memax Agent SDK is usable today and strongest in coding-agent orchestration. The broader platform shape already includes personal and managed-cloud stacks, but those areas are still maturing.

If you are evaluating the project today, the safest framing is:

• the runtime kernel is real and embeddable
• the coding stack is the most mature path
• the personal and cloud-managed stacks are active expansion areas

Key features

• Go-native autonomous agent runtime
• application-owned tool execution model
• OpenAI and Anthropic model adapters
• resumable sessions and append-only transcript storage
• structured permissions and approval callbacks
• bounded subagent execution with parent/child session correlation
• deterministic evaluation harness for orchestration scenarios
• coding workflow presets such as safe_local, ci_repair, and interactive_dev
• personal workflow presets such as personal_assistant and research_partner
• managed-worker building blocks for queues, quotas, run stores, and remote workers
• optional OpenTelemetry integration

Installation

Requires Go 1.24+.

Add the SDK to your project:

go get github.com/MemaxLabs/memax-go-agent-sdk@latest

Or clone the repository and build from source:

git clone https://github.com/MemaxLabs/memax-go-agent-sdk.git
cd memax-go-agent-sdk
go test ./...

Real-world example

A production-facing example built on top of this SDK is Memax Code, the Memax coding-agent CLI. It uses the SDK as its runtime foundation while adding CLI ergonomics, session UX, rendering, local configuration, and product-focused defaults for coding workflows.

Getting started

There are two common ways to adopt the SDK:

1. Start from a stack preset

If you want a batteries-included starting point, begin with one of the stack packages and attach your own backends.

Example shape using the coding stack:

cfg := coding.CIRepair()
cfg.Workspace = workspaceStore
cfg.Verifier.Verifier = verifier
cfg.Command.Runner = runner

stack, err := coding.New(cfg)
if err != nil {
    panic(err)
}

See the examples under examples/ for end-to-end setup.

2. Embed the runtime directly

If you need full control, build on the core runtime and register only the tools, policies, stores, and hooks your application wants to expose.

The root package centers on Query and QueryAsync, which drive a session, stream model events, execute requested tools through the registered tool registry, and continue until the run reaches a final result or stop condition.

Repository guide

Core packages

• agent.go — main runtime query loop
• session/ — session storage and lifecycle
• tool/ — tool registry and execution contracts
• planner/ — planner integration and task state wiring
• permission/ — permission policies and approval hooks
• prompt/, identity/, skill/ — prompt assembly and agent identity support
• model/, providers/ — provider-neutral model interfaces and adapters

Stacks

• stack/coding/ — coding-agent workflow assembly and presets
• stack/personal/ — personal-assistant workflow assembly and presets
• stack/cloudmanaged/ — managed multi-tenant worker assembly and stores

Toolkits and adapters

• workspace/, checkpoint/, toolkit/, web/, memory/, messaging/, notes/, scheduling/, telemetry/

Examples

Representative examples include:

• examples/coding_stack
• examples/coding_safe_local_stack
• examples/personal_stack
• examples/cloudmanaged_remote_stack
• examples/server_embedding

Documentation

Project documentation lives in docs/:

• Architecture
• Server integration
• Coding stack presets
• Personal stack presets
• Observability
• Skills
• Roadmap
• Versioning

Development

Run the test suite:

go test ./...

Explore runnable examples:

go run ./examples/coding_stack

Some examples require provider credentials or host-owned backends to be configured before they can run successfully.

Design principles

Memax is intentionally designed around a few core principles:

• host ownership over environment access
• clear separation between runtime and capabilities
• durable sessions and observable execution
• composable stacks instead of a single fixed product surface
• policy as configuration and integration, not hidden behavior

Open source status

This repository is being developed in the open as the foundation for a broader agent platform. APIs and higher-level stacks will continue to evolve, but the project is intended to be useful today for embedders who want a Go-native agent runtime with explicit control over tools and policy.

License

This project is licensed under the Apache License 2.0. See LICENSE.

Documentation

Overview

Package memaxagent provides a Go-native agent orchestration SDK.

The package is intentionally provider- and filesystem-neutral. Agent autonomy comes from the orchestration loop, session state, context-window policy, permissions, hooks, tool selection, and the tool execution contract. Concrete tools decide whether they operate on a real filesystem, virtual filesystem, remote API, browser sandbox, database, or in-memory workspace.

The main entry point is Query. Query creates or resumes a session, persists the user prompt, streams a provider-neutral model.Client, executes requested tools through a tool.Registry, appends tool results, and continues until the model returns a final assistant message or a configured stop condition is reached. Callers consume the returned Event channel to drive CLIs, servers, tests, logs, traces, or custom UIs.

Callers can supply raw system prompts or use the prompt and identity packages to assemble deterministic prompt parts from an agent profile, active tools, selected skills, and host instructions. The raw prompt path remains available for embedders that need complete control.

QueryAsync starts the same run shape without blocking the caller on startup I/O. This is useful for HTTP and WebSocket servers that want all session, hook, and prompt setup work to happen outside the request dispatch path.

Applications provide capabilities by registering tools. The core never bypasses the tool layer for files, shell commands, network calls, approvals, checkpoints, task state, or delegation. This keeps policy and workspace ownership in the host application while preserving a reusable autonomous loop.

Index

• Variables
• func Drain(events <-chan Event) (string, error)
• func EffectiveToolSpecs(opts Options) ([]model.ToolSpec, error)
• func ObserveEvent(ctx context.Context, event Event)
• func Query(ctx context.Context, prompt string, opts Options) (<-chan Event, error)
• func QueryAsync(ctx context.Context, prompt string, opts Options) <-chan Event
• func WithEventObserver(ctx context.Context, observer EventObserver) context.Context
• type ApprovalEvent
• type ApprovalSummaryEvent
• type CommandEvent
• type ContextEvent
• type Event
• type EventKind
• type EventObserver
• type EventObserverFunc
  • func (f EventObserverFunc) ObserveEvent(ctx context.Context, event Event)
• type MemoryCandidatesEvent
• type Options
  • func (o Options) Merge(override Options) Options
• type RunEvent
• type ScheduledRunNotificationEvent
• type SkillEvent
• type TenantEvent
• type VerificationEvent
• type WorkspaceEvent

Variables

var ErrMissingModelClient = errors.New("memaxagent: model client is required")

Functions

func Drain

func Drain(events <-chan Event) (string, error)

Drain consumes a query event stream and returns the final result or error.

func EffectiveToolSpecs

func EffectiveToolSpecs(opts Options) ([]model.ToolSpec, error)

EffectiveToolSpecs returns the model-facing tool specifications after the agent applies runtime tool injection, such as progressive skill loading. It returns the runtime superset and does not apply per-turn ToolSelector filtering, which depends on the current conversation state. It also does not load SkillSource contents; it only exposes the runtime load_skill tool spec when progressive skill loading is configured.

func ObserveEvent

func ObserveEvent(ctx context.Context, event Event)

ObserveEvent sends one host-owned event through the observer attached to ctx. This is useful for optional stack-level lifecycle signals that are not emitted directly by Query/QueryAsync but should still flow through the same audit and observability seam.

func Query

func Query(ctx context.Context, prompt string, opts Options) (<-chan Event, error)

Query runs an autonomous agent loop for a single prompt and streams events.

func QueryAsync

func QueryAsync(ctx context.Context, prompt string, opts Options) <-chan Event

QueryAsync starts Query in a goroutine and reports startup failures as EventError values instead of returning them synchronously.

This is useful in server handlers that need SDK startup work, such as session store access or user-prompt hooks, to run outside the caller goroutine. Startup failures are observed by Query before it returns; the synthesized channel events below are not observed a second time.

func WithEventObserver

func WithEventObserver(ctx context.Context, observer EventObserver) context.Context

WithEventObserver returns a child context that observes emitted agent events through observer. Nil observers leave ctx unchanged. Observation is scoped to the context value: code that creates a fresh context must reattach the observer if it wants events under that new context to remain observable.

Types

type ApprovalEvent

type ApprovalEvent struct {
	Action     string
	Reason     string
	InputHash  string
	Summary    ApprovalSummaryEvent
	Requested  bool
	Approved   bool
	Consumed   bool
	SingleUse  bool
	InputBound bool
}

ApprovalEvent describes approval request, decision, and consumption events. Action is the approved or requested action/tool name. Requested, Approved, Consumed, SingleUse, and InputBound are set according to the event kind.

type ApprovalSummaryEvent

type ApprovalSummaryEvent struct {
	Title       string
	Description string
	Risk        string
	Paths       []string
	Changes     int
	Added       int
	Modified    int
	Deleted     int
	ByteDelta   int
}

ApprovalSummaryEvent is a compact host-facing summary of an approval request.

type CommandEvent

type CommandEvent struct {
	Operation          string
	CommandID          string
	Command            string
	Argv               []string
	CWD                string
	Status             string
	PID                int
	TTY                bool
	SignalsProcessTree bool
	Cols               int
	Rows               int
	InputBytes         int
	ExitCode           int
	TimedOut           bool
	DurationMS         int
	StdoutBytes        int
	StderrBytes        int
	OutputTruncated    bool
	NextSeq            int
	ResumeAfterSeq     int
	OutputChunks       int
	DroppedChunks      int
	DroppedBytes       int
}

CommandEvent describes one host-owned command lifecycle observation. `run_command` uses Action "run" and populates process status fields. Managed command sessions populate Action "start", "write", "read", "resize", or "stop" plus CommandID, Status, PID, TTY, SignalsProcessTree, Cols, Rows, NextSeq, ResumeAfterSeq, OutputChunks, DroppedChunks, and DroppedBytes as appropriate. "write" additionally sets InputBytes. Command output text remains in the paired EventToolResult so transcript-visible tool behavior stays explicit.

type ContextEvent

type ContextEvent struct {
	OriginalMessages int
	SentMessages     int
}

type Event

type Event struct {
	Kind            EventKind
	SessionID       string
	ParentSessionID string
	Turn            int
	Time            time.Time

	Message      *model.Message
	ToolUse      *model.ToolUse
	ToolUseDelta string
	ToolResult   *model.ToolResult
	Usage        *model.Usage
	Context      *ContextEvent
	Compaction   *contextwindow.CompactionRecord
	Memory       *MemoryCandidatesEvent
	Skill        *SkillEvent
	Workspace    *WorkspaceEvent
	Verification *VerificationEvent
	Approval     *ApprovalEvent
	Tenant       *TenantEvent
	Command      *CommandEvent
	Run          *RunEvent
	Notification *ScheduledRunNotificationEvent
	Result       string
	Err          error
}

Event is emitted by Query as the orchestration loop progresses.

type EventKind

type EventKind string

const (
	EventSessionStarted EventKind = "session_started"
	EventModelRequest   EventKind = "model_request"
	EventAssistant      EventKind = "assistant"
	// EventToolUseStart is emitted when a provider starts streaming a tool-use
	// block before the full JSON input is complete.
	EventToolUseStart EventKind = "tool_use_start"
	// EventToolUseDelta is emitted for incremental provider tool-use input
	// chunks. The complete, executable call is still emitted as EventToolUse.
	EventToolUseDelta EventKind = "tool_use_delta"
	EventToolUse      EventKind = "tool_use"
	// EventToolResult is emitted for tool execution results. If streaming fails
	// after an early safe tool has started, a cancellation result may be emitted
	// before EventError so observers do not see an orphaned tool-use event.
	EventToolResult     EventKind = "tool_result"
	EventUsage          EventKind = "usage"
	EventContextApplied EventKind = "context_applied"
	// EventContextCompacted is emitted when a context policy produces a
	// compaction record, such as replacing older transcript messages with a
	// summary.
	EventContextCompacted EventKind = "context_compacted"
	// EventMemoryCandidates is emitted after a valid final answer has been
	// distilled and before EventResult. Candidates are proposals only; the SDK
	// does not persist them unless Options.MemoryCandidateHandler is configured.
	EventMemoryCandidates EventKind = "memory_candidates"
	// EventMemoryCandidateHandlerError is emitted when an optional memory
	// candidate handler fails. It is non-terminal; EventResult is still emitted.
	EventMemoryCandidateHandlerError EventKind = "memory_candidate_handler_error"
	// EventSkillDiscovery is emitted when the prompt exposes progressive skill
	// metadata for a model request. It is emitted per prompt build, so a context
	// retry can produce more than one discovery event for the same turn.
	EventSkillDiscovery EventKind = "skill_discovery"
	// EventSkillSearch is emitted when a skill catalog search tool returns.
	EventSkillSearch EventKind = "skill_search"
	// EventSkillLoaded is emitted when load_skill returns full instructions.
	EventSkillLoaded EventKind = "skill_loaded"
	// EventSkillResourceLoaded is emitted when read_skill_resource returns a
	// supporting resource.
	EventSkillResourceLoaded EventKind = "skill_resource_loaded"
	// EventWorkspacePatch is emitted when a workspace patch tool applies file
	// changes.
	EventWorkspacePatch EventKind = "workspace_patch"
	// EventWorkspaceDiff is emitted when a workspace diff tool reports changes.
	EventWorkspaceDiff EventKind = "workspace_diff"
	// EventWorkspaceCheckpoint is emitted when a workspace checkpoint is
	// created.
	EventWorkspaceCheckpoint EventKind = "workspace_checkpoint"
	// EventWorkspaceRestore is emitted when a workspace checkpoint is restored.
	EventWorkspaceRestore EventKind = "workspace_restore"
	// EventVerification is emitted when a verification tool reports pass/fail
	// status for a host-owned check.
	EventVerification EventKind = "verification"
	// EventApprovalRequested is emitted when an approval request tool result is
	// observed. It is followed by EventApprovalGranted or EventApprovalDenied
	// for the same result.
	EventApprovalRequested EventKind = "approval_requested"
	// EventApprovalGranted is emitted when an approval request was granted.
	EventApprovalGranted EventKind = "approval_granted"
	// EventApprovalDenied is emitted when an approval request was denied.
	EventApprovalDenied EventKind = "approval_denied"
	// EventApprovalConsumed is emitted when a later tool result carries metadata
	// showing that an approval grant was consumed for that attempt.
	EventApprovalConsumed EventKind = "approval_consumed"
	// EventTenantDenied is emitted when a tenant validator denies a session
	// start, model request, or tool use.
	EventTenantDenied EventKind = "tenant_denied"
	// EventCommandFinished is emitted when a command tool returns process
	// status and retained output metadata.
	EventCommandFinished EventKind = "command_finished"
	// EventCommandStarted is emitted when start_command creates a managed
	// command session.
	EventCommandStarted EventKind = "command_started"
	// EventCommandOutput is emitted when read_command_output or
	// wait_command_output returns buffered output for a managed command session.
	EventCommandOutput EventKind = "command_output"
	// EventCommandInput is emitted when write_command_input writes stdin to a
	// managed command session and optionally observes fresh output.
	EventCommandInput EventKind = "command_input"
	// EventCommandStopped is emitted when stop_command stops a managed command
	// session.
	EventCommandStopped EventKind = "command_stopped"
	// EventCommandResized is emitted when resize_command_terminal changes a PTY
	// session's terminal geometry.
	EventCommandResized EventKind = "command_resized"
	// EventRunStateChanged is emitted when a host-owned durable background or
	// proactive run changes lifecycle state, such as queued, running,
	// succeeded, failed, or canceled. Run events with TriggerName set identify
	// personal proactive scheduled-run occurrences.
	EventRunStateChanged EventKind = "run_state_changed"
	// EventScheduledRunNotificationClaimed is emitted when a personal
	// scheduled-run notification outbox record is leased to a delivery worker.
	EventScheduledRunNotificationClaimed EventKind = "scheduled_run_notification_claimed"
	// EventScheduledRunNotificationDelivered is emitted when a personal
	// scheduled-run notification outbox record is acked as externally delivered.
	EventScheduledRunNotificationDelivered EventKind = "scheduled_run_notification_delivered"
	// EventScheduledRunNotificationFailed is emitted when a personal
	// scheduled-run notification delivery attempt is marked retryable.
	EventScheduledRunNotificationFailed EventKind = "scheduled_run_notification_failed"
	// EventScheduledRunNotificationDeadLettered is emitted when a personal
	// scheduled-run notification exhausts retry policy and requires host
	// intervention.
	EventScheduledRunNotificationDeadLettered EventKind = "scheduled_run_notification_dead_lettered"
	// EventScheduledRunNotificationRequeued is emitted when a host requeues a
	// failed or dead-lettered personal scheduled-run notification.
	EventScheduledRunNotificationRequeued EventKind = "scheduled_run_notification_requeued"
	EventError                            EventKind = "error"
	EventResult                           EventKind = "result"
)

type EventObserver

type EventObserver interface {
	ObserveEvent(context.Context, Event)
}

EventObserver observes emitted agent events as they happen. Observers are host-owned and non-authoritative: they can mirror events to logs, metrics, audit stores, or tracing systems without changing the event stream seen by callers. Observation runs synchronously on the event-emission path, so hosts with slow sinks should wrap them behind an async or buffered adapter to avoid backpressuring the agent loop.

type EventObserverFunc

type EventObserverFunc func(context.Context, Event)

EventObserverFunc adapts a function to EventObserver.

func (EventObserverFunc) ObserveEvent

func (f EventObserverFunc) ObserveEvent(ctx context.Context, event Event)

ObserveEvent calls f(ctx, event).

type MemoryCandidatesEvent

type MemoryCandidatesEvent struct {
	Candidates []memory.Candidate
}

type Options

type Options struct {
	Model model.Client

	Tools           *tool.Registry
	Permissions     permission.Checker
	Sessions        session.Store
	Hooks           *hook.Runner
	Context         contextwindow.Policy
	ContextRetry    contextwindow.Policy
	ToolSelector    tool.Selector
	Budget          budget.Governor
	ResultStore     resultstore.Store
	Output          output.Contract
	Tracer          telemetry.Tracer
	Meter           telemetry.Meter
	PromptBuilder   prompt.Builder
	PromptProfile   prompt.Profile
	Identity        identity.Identity
	Tenant          tenant.Scope
	TenantValidator tenant.Validator
	Planner         planner.Policy
	MemorySource    memory.Source
	MemoryDistiller memory.Distiller
	// MemoryCandidateHandler handles distilled memory candidates after they are
	// emitted as EventMemoryCandidates. Nil preserves the safe default: propose
	// candidates but do not persist them. Handler errors emit
	// EventMemoryCandidateHandlerError but do not prevent the final result.
	MemoryCandidateHandler memory.CandidateHandler
	Memories               []memory.Memory
	SkillSource            skill.Source
	SkillResourceSource    skill.ResourceSource
	SkillDisclosure        skill.DisclosureMode
	Skills                 []skill.Skill

	SystemPrompt       string
	AppendSystemPrompt string
	SessionID          string
	ParentSessionID    string
	MaxTurns           int
	// MaxFinalDenials controls how many before-final denials may be repaired
	// with transcript prompts before the run fails. Zero uses the SDK default;
	// a negative value disables finalization retries.
	MaxFinalDenials    int
	MaxToolConcurrency int
	MaxRunDuration     time.Duration
}

Options configures one agent run.

func (Options) Merge

func (o Options) Merge(override Options) Options

Merge returns a copy of o with non-zero fields from override applied. Slice fields replace the base when override provides a non-nil slice, including an explicitly empty slice. This is used by composed agents and evals to share the same option override semantics as new fields are added.

type RunEvent

type RunEvent struct {
	RunID        string
	Status       string
	Prompt       string
	WorkerID     string
	TriggerName  string
	OccurrenceAt time.Time
	Result       string
	Error        string
}

RunEvent describes one durable host-owned run lifecycle transition. Status is one of the stack-defined lifecycle states such as queued, running, succeeded, failed, or canceled. TriggerName and OccurrenceAt are set for personal proactive scheduled runs. Result is set by stacks that expose a terminal user-facing result, including partial terminal output, through lifecycle notifications.

type ScheduledRunNotificationEvent

type ScheduledRunNotificationEvent struct {
	// NotificationID is the host-owned outbox record ID.
	NotificationID string
	// RunID is the scheduled-run ID that produced the notification.
	RunID string
	// Status is the scheduled-run lifecycle status that produced the notification.
	Status string
	// TriggerName is the scheduled trigger name, when the notification came from a trigger.
	TriggerName string
	// OccurrenceAt is the deterministic scheduled occurrence time, when present.
	OccurrenceAt time.Time
	// DeliveryStatus is the notification delivery status after the transition.
	DeliveryStatus string
	// WorkerID is the delivery worker that claimed or updated the notification.
	WorkerID string
	// Attempts is the number of delivery attempts after the transition.
	Attempts int
	// DeliveryError is the latest delivery failure reason, when present.
	DeliveryError string
	// DeliverAfter is the next eligible delivery time.
	DeliverAfter time.Time
	// DeliveredAt is set when the notification reaches delivered status.
	DeliveredAt time.Time
	// DeliveryUpdatedAt is the timestamp of the delivery-state transition.
	DeliveryUpdatedAt time.Time
}

ScheduledRunNotificationEvent describes one host-owned personal notification outbox delivery transition. Status is the scheduled-run lifecycle status that produced the notification. DeliveryStatus, WorkerID, Attempts, DeliveryError, DeliverAfter, DeliveredAt, and DeliveryUpdatedAt describe the current delivery state after the transition.

type SkillEvent

type SkillEvent struct {
	Action         string
	SkillName      string
	ResourceName   string
	Query          string
	SelectedSkills []string
	Selected       int
	Omitted        int
	Matches        int
	PromptBytes    int
	MetadataOnly   bool
}

SkillEvent describes one skill lifecycle observation. Fields are populated according to Action: "discovery" uses SelectedSkills, Selected, Omitted, PromptBytes, and MetadataOnly; "search" uses Query, Matches, and MetadataOnly; "load" uses SkillName; "resource_load" uses SkillName and ResourceName.

type TenantEvent

type TenantEvent struct {
	Boundary   string
	TenantID   string
	SubjectID  string
	Attributes map[string]string
	Reason     string
}

TenantEvent describes one tenant-policy denial. QueryAsync can emit this before EventError for startup denials that happen before an event stream would otherwise exist.

type VerificationEvent

type VerificationEvent struct {
	Operation   string
	Name        string
	Passed      bool
	Diagnostics int
	Paths       []string
}

VerificationEvent describes one host-owned verification check, such as a test, typecheck, lint, or custom policy validator. Failed checks are expected to arrive as tool error results so the model can repair and retry.

type WorkspaceEvent

type WorkspaceEvent struct {
	Operation    string
	Paths        []string
	Changes      int
	Added        int
	Modified     int
	Deleted      int
	ByteDelta    int
	CheckpointID string
	BaseID       string
}

WorkspaceEvent describes one workspace lifecycle observation derived from tool result metadata. Operation is one of "patch", "diff", "checkpoint", or "restore". Patch and diff events use Paths, Changes, Added, Modified, Deleted, and ByteDelta; checkpoint and restore events use CheckpointID. Diff events may also set BaseID.