All docs

Workspaces

Workspaces are persistent multi-step projects. They use the local model to plan, review, optionally research, execute steps, and write artifacts to disk.

Main classes

  • WorkspaceController: owns the workspace list and orchestrates agent runs.
  • WorkspaceAgent: performs planning, review, research, refinement, and execution.
  • WorkspaceStore: persists workspace folders, plans, logs, README files, and generated artifacts.
  • workspaceRunProvider: holds live in-memory progress for smooth UI updates.

Storage layout

Each workspace is a folder under the application documents directory:

text
workspaces/<id>/
workspace.json
plan.json
README.md
logs.ndjson
files/

Files are normal local files. Logs are append-only NDJSON. Generated artifacts are written under files/.

Creation

WorkspaceController.create builds a workspace with:

  • A generated id.
  • Name derived from the goal when no name is supplied.
  • Goal.
  • Optional description.
  • Optional schedule.
  • Auto-run flag.
  • Draft status.

The workspace is saved immediately, the list reloads, and planning starts asynchronously.

Planning loop

WorkspaceAgent.preparePlan follows this flow:

  1. Mark workspace as planning.
  2. Draft a JSON step plan through utility generation.
  3. Sanitize placeholder or clarification-only steps.
  4. Persist the plan.
  5. Run an expert review pass.
  6. Gather web research if the goal requires external facts.
  7. Refine the plan using critique and research.
  8. Save a README.
  9. Mark the workspace as ready.

Prompts are schema-locked because small models need tight output rails.

Plan sanitation

The agent removes steps that ask the user for more information or wait for input. If the model returns an unusable plan, the agent creates a default two-step plan:

  • Work out the approach.
  • Produce the deliverable.

This keeps workspace execution biased toward delivering output instead of stalling.

Execution

WorkspaceAgent.execute runs ready steps in dependency order. Steps execute one at a time because the local engine is single-threaded for generation. Dependency order is still respected so outputs can feed later steps.

Supported step tools include:

  • reason
  • search
  • document
  • spreadsheet
  • code
  • email
  • message
  • device

Document, spreadsheet, code, email, and message outputs are saved as files. Sending is not silent. Drafts are saved for review.

Logs and live progress

The agent writes every meaningful event to logs.ndjson and also pushes live updates through callbacks:

  • Status changes.
  • Step changes.
  • Log rows.
  • Current activity text.

The controller coalesces workspace list reloads so rapid progress events do not cause disk reads on every update.

Scheduling

Workspaces can be scheduled through WorkspaceController.setSchedule. Scheduling delegates to DeviceActions.scheduleWorkspace, which registers a native schedule. When the user taps the notification, the native side invokes runWorkspace through the assist channel, and Flutter opens and runs the workspace.

Failure behavior

Corrupt workspace folders are skipped instead of crashing the list. Failed steps are marked failed and logged. Pending steps with unmet dependencies are marked skipped. The workspace ends as failed if any step failed.

PreviousAgent tools and MCPNextVoice