jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a6ec352f0745542b907ca7a166ab61edfd7aeda9
paseo/docs/glossary.md
T
Mohamed BoudraandGitHub 21deb08673 Make workspace IDs opaque, independent of the filesystem path (#1503) 
* Make workspace IDs opaque, independent of the filesystem path

Workspace IDs were the resolved checkout/worktree path, so code could
treat an ID as a path: prefix matching, deriving directories from it,
falling back to a path when a lookup missed. IDs are now opaque -
compared only by exact equality and never used as a path. Anything
path-shaped resolves the workspace record first and reads its cwd.

New workspaces get a generated `wks_` ID; existing path-shaped IDs are
read from disk and never regenerated, so there is no migration and no
change to the wire or persisted schemas. Groundwork for running
multiple workspaces in a single directory.

* Keep attachment scope key stable and align refetch test

The attachment scope key keeps `workspace=` instead of `wsid=` so existing
persisted drafts are not orphaned; the rename was cosmetic. The SDK refetch
test no longer asserts a filter, matching refetch fetching one page and
selecting by id client-side.

* Fix live agent updates in directories without a registered workspace

The opaque-ID work removed buildProjectPlacementForCwd's directory
fallback, so an agent running in a folder with no registered workspace
(e.g. a fresh non-git dir) produced a null placement. forwardAgentUpdate
then threw "Workspace not found", the error was swallowed by its catch,
and no agent_update was emitted — live model/thinking switches and status
updates silently stopped. Caught by the live-preferences e2e suite.

The fallback builds a directory-scoped project placement keyed by the
path. That key is a project grouping key (non-git projects group by
path), not a workspace id, so it stays within the opaque-id rule.

* Always run server worktree archive, even without a resolved workspace

Archiving bailed out entirely when the workspace was not found in the
client store, so a race or stale state could make "archive" do nothing
server-side with only a console.warn. The server archive is keyed by
worktreePath, which is always available, so it now runs regardless; only
the optimistic client-side updates (keyed by workspace id) are gated on
the workspace being resolved.

* Expect a directory-scoped placement for unregistered agent dirs

This unit test asserted the no-placement behavior reverted in the live
agent-update fix, which had broken live model/thinking switching. Update
it to expect the directory-scoped placement now emitted for an agent in a
directory with no registered workspace.

* Fix opaque workspace routing in app E2E

* Preserve workspace IDs during partial bootstrap

* Fix archive flows for opaque workspace IDs

* Stop treating opaque workspace IDs as filesystem paths

Workspace IDs are opaque (wks_<hex>), but several call sites still passed
the id where a directory was expected, which broke those flows for opaque
IDs. The branch switcher sent the id as a cwd to branch/stash/checkout git
operations, and server archive/reconcile cleanup keyed git-watch and
subscription teardown by id, leaking that state.

Git and filesystem operations now take the workspace directory; the opaque
id is used only for identity and cache keys. Archive/reconcile cleanup
routes through a single teardownArchivedWorkspace helper that keeps the key
split explicit: runtime store by id, git watch and subscription by cwd.
Path-derived grouping keys are renamed to directory keys, and the helpers
are split into workspace-identity and workspace-directory so the id-vs-path
boundary is obvious.
2026-06-14 22:03:27 +08:00

7.3 KiB
Raw Blame History

Paseo Glossary

Authoritative terminology. UI label wins. Don't invent synonyms; use what's here.

  • Project — Logical grouping of workspaces sharing a git remote (or main repo root). UI: "Project" / "Add project". Code: ProjectSummary (packages/app/src/utils/projects.ts:22), projectKey (packages/server/src/server/workspace-registry-model.ts:16). Forbidden: "Repo", "Repository" as UI label.
  • Workspace — One concrete cwd on one daemon, with git state; belongs to exactly one project. Its id is opaque workspace identity; its cwd is the filesystem directory. UI: "Workspace". Code: WorkspaceDescriptorPayload (packages/protocol/src/messages.ts:2178). Don't confuse with: Branch (one branch can back many workspaces via worktrees). Forbidden: "Folder", "Directory" as UI label.
  • Workspace kind — "directory" | "local_checkout" | "worktree". Code: PersistedWorkspaceKind (packages/server/src/server/workspace-registry-model.ts:8).
  • Agent — See Agent session. UI still says "Agent" / "New Agent" in places, but moving toward Agent session as the canonical term. Code: AgentSnapshotPayload (packages/protocol/src/messages.ts:608). Forbidden: "Task", "Job", "Run".
  • Daemon — Local Paseo server process; identified by serverId. UI: "Daemon" (system contexts only). Code: serverId in ServerInfoStatusPayloadSchema (packages/protocol/src/messages.ts:1936), DaemonClient (packages/client/src/daemon-client.ts).
  • Host — Client-side connection profile pointing at a daemon; bundles one or more HostConnections. UI: "Host" / "Add host" / "Switch host". Code: HostProfile (packages/app/src/types/host-connection.ts:37). Forbidden: "Connection" (means HostConnection, not host).
  • Project host entry — One row in a project for a single (project, daemon) pair, aggregating that daemon's workspaces in the project. Internal. Code: ProjectHostEntry (packages/app/src/utils/projects.ts:11). Don't introduce "Checkout" as a synonym.
  • Placement — One workspace's relationship to its project (projectKey, projectName, git checkout snapshot). Internal. Code: ProjectPlacementPayload (packages/protocol/src/messages.ts:2113).
  • Branch — Plain git branch. UI: "Switch branch". Code: currentBranch in WorkspaceGitRuntimePayloadSchema (packages/protocol/src/messages.ts:2136); BranchSwitcher (packages/app/src/components/branch-switcher.tsx).
  • Worktree — Paseo-managed git worktree (~/.paseo/worktrees/{name}); also a workspaceKind value. UI: CLI + paseo.json keys (worktree.setup, worktree.teardown) only. Code: ProjectCheckoutLiteGitPaseoPayload (packages/protocol/src/messages.ts:2092); CLI paseo worktree (packages/cli/src/commands/worktree/index.ts:8). Forbidden: "Checkout" as a synonym.
  • Repository / Remote — Internal git inputs (remoteUrl, mainRepoRoot) used to derive projectKey. No UI label.
  • Agent session — One running instance of an agent inside a workspace (one provider, one model, one cwd, one timeline). The conceptual unit; in the UI this opens as a tab. Moving toward this as the canonical term over "Agent". Code: AgentSnapshotPayload (packages/protocol/src/messages.ts:608).
  • Session — Two senses: (a) per-client connection to a daemon, internal; (b) user-facing agent session, see Agent session. Code: Session (packages/server/src/server/session.ts) for (a). Don't confuse with: provider-side agent session log.
  • Profile — Internal name for the persisted shape of a host. Code: HostProfile (packages/app/src/types/host-connection.ts:37). Never user-facing.
  • Provider — Agent backend (Claude Code, Codex, Copilot, OpenCode, Pi, OMP). UI: "Provider". Code: ProviderSnapshotEntry (packages/protocol/src/messages.ts:198).
  • Model — A specific LLM offered by a provider. UI: "Model" / "Select model". Code: AgentModelDefinition (packages/protocol/src/messages.ts:187).
  • Tab — UI surface representing one session inside a workspace. Not a conceptual unit; use Agent session when talking about the model. Code: WorkspaceTabDescriptor (packages/app/src/screens/workspace/workspace-tabs-types.ts).
  • Terminal — Workspace-scoped PTY shell streamed over the binary mux channel. UI: "Terminal". Code: TerminalStreamFrame (packages/protocol/src/terminal-stream-protocol.ts).
  • Schedule — Cron-style trigger that creates new agents. UI: CLI/MCP (paseo schedule, create_schedule). Don't confuse with: Heartbeat (cron prompt back into the same agent) or Loop (iterative re-execution of one agent).
  • Heartbeat — Cron-style prompt sent back into the same agent/conversation. MCP: create_heartbeat. Use for reminders and babysitting where the status should return inline.
  • Mode — Provider-specific operational mode (plan, default, full-access, …). UI: icon-only. Code: modeId in AgentSessionConfig (packages/protocol/src/messages.ts:257).
  • Attachment — GitHub PR or Issue bound to an agent prompt. UI: "Attach issue or PR". Code: AgentAttachment (packages/protocol/src/messages.ts:782).
  • Composer — The whole prompt surface for sending work to an agent. Code: Composer (packages/app/src/composer/index.tsx). Don't call this "message input" except for the text-entry subcomponent.
  • Composer input — The text-entry surface inside the composer. Code: MessageInput (packages/app/src/composer/input/input.tsx).
  • Composer toolbar — The bottom control row inside the composer input. Contains agent controls, attachment button, voice controls, and stop/send controls. Code: leftContent, beforeVoiceContent, and rightContent slots in MessageInput (packages/app/src/composer/input/input.tsx). Forbidden: "Status bar".
  • Agent controls — Provider, model, mode, thinking, and provider-feature controls for an agent or draft agent. Code: AgentControls / DraftAgentControls (packages/app/src/composer/agent-controls/index.tsx). Forbidden: "Agent status bar".
  • Composer footer — Optional area rendered below the composer input but still inside the keyboard-shifted composer layout. Code: Composer.footer (packages/app/src/composer/index.tsx).
  • Composer track — A contextual lane above the composer input. Specific tracks use the <thing> track form: Queue track, Subagents track. Code: queue track inside Composer (packages/app/src/composer/index.tsx), SubagentsTrack (packages/app/src/subagents/track.tsx).
  • Attachment tray — The selected-attachments row inside the composer input, above the text input. Code: renderAttachmentTray (packages/app/src/composer/index.tsx). Forbidden: "Attachment bar".
  • Conflict — Two distinct senses; do NOT use the bare word in UI copy without qualifying which: (a) stale-write conflict on paseo.json ("Config changed on disk", code stale_project_config, packages/app/src/screens/project-settings-screen.tsx:593); (b) git merge conflict (no current UI string).

Inconsistencies (documented, not papered over)

  • CLI --host <host> description "Daemon host target" (packages/cli/src/utils/command-options.ts:5) blurs daemon/host; the app keeps them distinct.
  • WorkspaceDescriptorPayloadSchema.workspaceKind accepts legacy "checkout" on the wire (packages/protocol/src/messages.ts:2187) while PersistedWorkspaceKind does not (packages/server/src/server/workspace-registry-model.ts:8).
Reference in New Issue View Git Blame Copy Permalink