Workspaces candidate reference

This page describes the unreleased Workspace candidate. It is not a production availability announcement. Workspace access requires account enablement and the matching server and client versions. The candidate still needs its staging qualification before release.

What does a Workspace contain?

A Workspace keeps a project’s files and main conversation together. An agent is an execution identity. Its manager role selects who handles the main conversation by default. A worker runs a task on a selected working copy. A task group gives workers a shared token budget.

The root copy holds the Workspace's current files. A proposal copy lets a worker make changes for review. A revision identifies immutable saved files. It is an opaque ID, not a Git commit. A changeset records the proposed changes and their review. Acceptance updates the root only after the required save and review checks succeed.

These resources support source code, reports and media. Text changes can require conflict resolution. Binary files require review of the available versions. Each concurrent worker needs its own ready copy. Account capacity, storage limits and task-group budgets still apply.

How do manager and external coordination differ?

Creating a Workspace without a manager option creates a default manager identity. It does not start a run. This candidate CLI command creates that Workspace:

plori workspace create reports --idempotency-key reports-create-1

Use the returned Workspace ID to open its main conversation in the web client. For a document task, ask the manager to draft a report and delegate a review. For a code task, ask it to change a named source file and delegate a test review. Inspect the resulting files and saved revisions before accepting changes.

An external coordinator can create a Workspace with no default manager:

plori workspace create reports --manager none --idempotency-key reports-external-1

It then chooses copies, task groups and workers explicitly. See the CLI coordination commands and MCP connection guide. The same workflow can edit /report.md or a source file. Use exact returned IDs and stable idempotency keys. A new name does not identify a previous request.

In REST and MCP creation input, omit default_manager_agent_id to create a manager, supply an agent UUID to select that identity, or supply null for none. Changing the default manager affects future selection. It does not change the executor recorded on an existing run.

What does saved mean?

A completed run and a saved revision are separate results. Inspect the worker's save_state and saved_revision_id, then read that revision. A ready saved revision does not mean the changeset is accepted. Pending, failed or unconfirmed saves require inspection before review.

Recovery can recreate a lost copy from its last ready revision. Writes after that revision can be lost. During a run, the platform saves a changed copy every 60 seconds, and it saves again when the run ends and before a planned stop. Recovery does not restart a process or restore its open file descriptors, locks or memory mappings. Do not assume it restores an active SQLite WAL session. Inspect the recovered copy and start a new run from known saved files.

How do costs, retention and deletion work?

Task-group budgets use cache-weighted tokens. Cost reports return charged money for a selected time window. A missing or null amount means unknown, not zero. Resource observations are paginated and do not represent a complete total until you have read every page.

Stopping a worker or group preserves files and history subject to retention. Retiring an executor prevents future assignments. Neither action accepts its changes. The retention policy determines when copies and revisions are eligible for cleanup. Expiry does not prove physical erasure. Pins require an operator policy that permits them.

At the revision limit, Plori automatically retires the oldest unreferenced revisions so saves can continue. Current revisions, copy bases and heads, active work, changeset references, and retention holds stay protected. An unchanged save reuses its revision.

If protected revisions occupy every slot, Plori returns workspace_storage_limit_reached. Retry after pending work finishes or retained references or pins are released. History shows retired revisions as deleting, then deleted after cleanup. Their slots become available immediately. Their bytes stay charged until scheduled cleanup completes.

Deleting a Workspace erases its files and history through asynchronous cleanup. An accepted deletion request does not prove that physical erasure is complete. Legacy agent deletion remains destructive for its mapped Workspace. Use executor retirement when you want to preserve the Workspace.

Must existing clients migrate?

Workspace APIs are additive. Existing agent, run and session IDs remain the compatibility identifiers for adopted records. Adoption preserves the legacy mapping. Independent execution identities have a separate inventory and are not included in the legacy agent list.

Use Workspace worker submission for a worker continuation, with the selected executor, private session and ready copy. Legacy invoke_agent is not the continuation API for an independent Workspace worker. Existing clients still need qualification against the same candidate as the new clients before release.

See the candidate API reference for request and response contracts.