Module workspace 

Workspace mode — two variants.

Github mode (Workspace::open, the default when --workspace DIR is set): the agent activates a GitHub repo via repo_management('org/repo'), the binary clones it into the workspace, and the active repo becomes the bound source root for read_source / grep / list_source. Idle repos auto-sweep after --stale-after-days. Layout: workspace/ repos/// — cloned source inventory.json — per-repo access tracking

Local mode (Workspace::open_local, the manifest-driven workspace: { kind: local, root: ... } variant): the active source root is a fixed local directory, not a clone target. repo_management reports the active root and triggers rebuilds; an set_root_dir tool can swap the root at runtime. Closes the code_review_mcp_server use case from the kglite wishlist.

Both modes share one activation state machine. Existing consumers may use the serialized PostActivateHook callback family; concurrency-aware consumers use ActivationTransactionHook to prepare off-lock and publish only while their request generation is current. Both honour the same last_built_sha gating to skip pointless rebuilds.

Re-exports

pub use crate::server::manifest::WorkspaceKind;

Structs

ActivationId

Monotonically increasing identity for one workspace activation request.

ActivationRequest

Immutable input to an ActivationTransactionHook.

PreparedActivation

Prepared downstream activation that has not yet been published.

Workspace

Workspace runtime state. Shared across MCP request clones via Arc.

Enums

ActivationBuild

Work required for a request-scoped activation.

RevsRequest

A revisions request carried by the activation tools. Count(n) resolves to the newest n stable release tags of the repo’s dominant tag family (plus HEAD); List(revs) is an explicit set of git revspecs used verbatim. The untagged deserialization maps a JSON integer to Count and a JSON array of strings to List, so the tool arg accepts int | [str]. Resolution happens at activate time — see Workspace::resolve_revs.

RootOwnership

Who chose the currently active root.

Type Aliases

ActivationSummaryHook

Optional hook that returns a short agent-facing summary appended to the activation result message — the “graph ready” mini-map / opening steer (e.g. "Graph ready: 9,999 Functions · 656 Classes · 31k CALLS. Open with graph_overview() → cypher_query; grep = literal text only.").

ActivationTransactionHook

Request-scoped activation transaction.

PostActivateHook

Hook fired after a successful clone or update. Receives the absolute path to the cloned repo and the org/repo name. Legacy callback activations are serialized through summary generation. Errors abort publication of the framework’s new active source state; use ActivationTransactionHook when downstream product installation must also be deferred until commit.

PostActivateRevsHook

Hook fired after a successful clone/update when revisions were requested on the activation call (repo_management(revs=…) / set_root_dir(revs=…)). Receives the repo path, the org/repo (or synthetic local) name, and the resolved revspecs in oldest→newest order — for a Count(n) request the final entry is always HEAD, so a downstream multi-rev builder can merge oldest→newest with HEAD’s signature winning. Set via Workspace::with_post_activate_revs.