Code tour

Pi Sych starts in extensions/workbench/index.ts. The workbench adds guidance at the beginning of a supervisor turn, loads project-scoped configuration, and registers the tools and commands that connect Pi to the focused runtime modules.

Dispatch and worker lifecycle

dispatch_worker is a request/result protocol rather than a task queue. A supervisor supplies a bounded task packet: the requested capability mode, expected result, relevant files, selected skills, model role, context mode, and timeout. The workbench passes that packet to the worker engine, which resolves the files, requires a bootstrapped worker directory, creates a temporary runtime location, and starts a separate Pi worker process. Clean context is the default. Trajectory context uses Pi’s session manager on a private snapshot to create a temporary branch immediately before the exact dispatching assistant entry. The worker can submit exactly one immutable validated result: status, summary, files, and limitations. Dispatch accepts it only after a normal exit and verifies that reported project files still exist. Cancellation, timeout, spawn failure, a signal exit, and a non-zero exit take precedence over a result file; none is a successful result.

Project state and SYNC

project_status is the mechanical view of project state. It reads SYNC.json, reports changed or missing tracked files and dependency impact, and can atomically acknowledge files that a human has reviewed. A hash change says only that content changed; the tool deliberately does not decide whether that change is correct or conceptually important.

Compaction and configuration

The workbench can invoke custom compaction when configuration enables it. The compaction module builds a bounded snapshot of selected project state and the conversation, asks the active supervisor model for structured working memory, filters its file references, and appends a small number of unreviewed proposals to the inbox. Returning no custom result leaves Pi’s standard compactor in control. Configuration is resolved through the config-directory module so the workbench, worker setup, model catalog, and optional local resources agree on where private settings live.

Optional integrations

MCPorter is an explicit remote-research adapter. It is only added to a worker that requested remote research, and its diagnostics describe configuration without exposing credentials. Such a worker also receives PEW-PEW when the supervisor’s active web tool has validated pi-pew-pew package provenance; disabled or excluded PEW-PEW remains absent. A separately installed active web tool remains directly usable by the supervisor. Plannotator is separate from the workbench: it is a narrow human-review adapter that brings feedback from a message or file back into the review flow rather than controlling plans or project state.

Literature search is a direct supervisor tool and a gated worker tool. The workbench registers literature_search for supervisor lookup. The worker extension also registers it, while the worker engine exposes it only when the selected skills include exact research. A query flows to the resolved local SQLite FTS5 database and comes back as metadata, snippets, scores, and source paths. The supported papers plus external-content papers_fts schema stores canonical metadata separately and indexes filepath, title, abstract, tags, and DOI; its full FTS5 contract and database-resolution order are in configuration.

For declarations and source links generated from the current runtime source, see the live generated code reference.