ScoutPi Workbench

A Pi-native spatial runtime for understanding and operating geospatial data, imagery, and evidence.

ScoutPi Workbench gives Pi a small, typed spatial runtime instead of a permanent collection of scenario tools. Pi is the primary operator: it can research a dataset, create a declarative adapter, verify it, compile an investigation, supervise compute and exports, control the spatial canvas, and preserve a successful workflow as a skill. The Workbench is an operator console for observing that state, reviewing evidence, and intervening when needed.

Forest, flood, agriculture, urban change, water, climate, and disaster tasks are possible inputs. They are not hard-coded product branches.

The spatial canvas switches between MapLibre 2D and CesiumJS 3D with real elevation terrain and an explicit ellipsoid fallback. A generic hazard-exposure overlap contract can answer questions such as “how much baseline vegetation intersects a flood proxy,” while preserving thresholds, data provenance, artifacts, and the distinction between a satellite proxy and confirmed damage.

The interface is deliberately not a manual GIS editor:

Surface	Meaning
Left rail: From Pi	Read-only task history issued through Pi, with the current Pi focus marked
Center: Pi spatial focus	The region, observable, year, imagery, and 2D/3D perspective currently controlled by Pi
Right rail: Pi understanding	The task, current spatial state, tested hypothesis, selected data, evidence, workflow, and run history available to Pi

The user gives the task to Pi, not to the Workbench. The canvas follows Pi by default. A human can temporarily inspect another task, year, layer, or renderer without mutating Pi's state, then select Follow Pi to return to the current Agent focus. Direct plan/run/export controls are hidden in the normal product surface; developers can opt into local test controls with VITE_SCOUTPI_MANUAL_CONTROLS=1.

Why This Runtime

question + claims + region + time
  -> Pi lifecycle trace + dynamic Earth tool profile
  -> token-bounded Context Pack with source provenance
  -> observable roles
  -> registered adapter search
  -> Agent drafts a missing adapter when needed
  -> schema validation + revision + fingerprint + live probe
  -> deterministic InvestigationSpec and AnalysisDAG
  -> supervised Earth Engine job or direct map tiles
  -> bounded local export and numerical checks
  -> evidence critic + EarthStory
  -> successful trace compiled into a guarded workflow
  -> optional signed trigger delegation for bounded dry-run replay
  -> token/cost telemetry + replay evidence

The model does not execute generated Python, JavaScript, shell, or arbitrary Earth Engine expressions. Pi creates declarative contracts; reviewed runtime code executes them.

Implemented

• Three registered Pi gateway tools, dynamically activated as core, analysis, and report profiles
• Official Pi 0.80 execution contract with TypeBox schemas, AbortSignal, streaming progress, lifecycle events, and structured failures
• Event-only governance extension with parameter-bound, single-use user approval receipts
• Event-only observability extension with privacy-preserving Agent run traces and provider-reported token/cost usage
• Event-only durable checkpoint extension with atomic revisions, integrity checks, compaction hints, and one-time recovery context
• Event-only Context Bridge with provider-neutral candidates, mixed-text token budgets, provenance, user-reviewed writeback staging, and an opt-in idempotent Wisdom Weasel RAG Core adapter
• Event-only Browser Evidence Bridge with allowed-root import, artifact hashes, explicit claim/hypothesis relations, and Agent-trace attachment
• Deterministic Evidence Reviewer that blocks dry-run claims, unsupported findings, broken plan/job/source provenance, and adapter-declared proxy overclaims before EarthStory persistence
• Event-only durable trigger extension with identity-bound HMAC grants, manual/interval/event conditions, idempotent replay, cooldown/expiry/run limits, and no additional model tool
• Local stdio MCP compatibility server with four compact gateways, resource links, and no live/admin operations
• Reviewed Backend Plugin SDK with manifests, validation hooks, bounded progress, cancellation, timeouts, and result limits
• Progressive-disclosure Earth investigation skill
• Dynamic scoutpi.earth.adapter.v1 registry with revisions, SHA-256 fingerprints, enable/disable state, and audit events
• Live adapter probes that check collection availability, sample time, required bands, and quality-mask bands
• Typed InvestigationSpec -> DatasetPlan -> AnalysisDAG compiler with cost and evidence checks
• Dry run, inline Earth Engine metrics, Drive export, task polling, cancellation, and retryable local export jobs
• Direct Earth Engine raster tiles in MapLibre 2D and CesiumJS 3D with real elevation terrain, without first downloading a GeoTIFF
• Generic hazard-change × baseline-exposure overlap assessment with bounded thresholds, hectare metrics, compact artifacts, and explicit proxy caveats
• Durable scoutpi.spatial-view.v1 state so Pi can focus a plan, observable, year, and 2D/3D renderer while the Workbench follows without browser automation
• Bounded geedim GeoTIFF export with scale/pixel review, manifest, byte count, and SHA-256
• Safe CSV/JSON/GeoJSON statistics without arbitrary code execution
• Generated scoutpi.earth.skill.v1 drafts with confirmed publishing and overwrite protection
• Automatic workflow candidates from verified successful jobs, explicit promotion, deterministic replay, cost assertions, and adapter-drift rejection
• Pi-oriented Vue operator console with collapsible task/state rails, a synchronized 2D/3D spatial canvas, evidence, execution state, artifacts, workflows, and a responsive Runtime Center
• Persistent English/Simplified Chinese Workbench localization for navigation, controls, dialogs, charts, runtime states, and observable roles while preserving user-authored evidence text verbatim
• Pi Capability Broker over tools and commands, with a durable path-safe capability profile and operator-facing Extensions view, so market-provided research, MCP, memory, browser, context, goals, security, interoperability, evaluation, and subagent capabilities are reused rather than copied
• Privacy-safe real Pi RPC evaluation with an isolated Skill/runtime surface, outcome-based workspace scoring, approval-bypass detection, model error classification, compact traces, and explicit token/turn/tool budgets
• Integrity-bound Evaluation Store and Workbench Evaluation view for Pi RPC, token/context benchmarks, generic end-to-end evidence flow, and restart recovery proof

The core does not silently ship an active domain catalog. examples/adapter-packs/earth-engine-starter.json is an explicit demo pack and remains separate from runtime code.

Quick Start

Requirements: Node.js 22.6+, pnpm, uv, and Python 3.11-3.13. The checkout pins Python 3.13 for reproducible local development.

git clone https://github.com/7155/scoutpi-workbench.git
cd scoutpi-workbench
pnpm install
uv sync --extra pipeline
pnpm examples:seed
pnpm check
pnpm workbench:dev

Open http://127.0.0.1:5173. The loopback API runs at http://127.0.0.1:17420.

pnpm examples:seed imports the demo adapter pack into ignored local workspace state. Omit it when Pi should construct every adapter from primary documentation.

The dry-run path does not need Earth Engine credentials. Live compute, probes, tiles, and exports require authentication:

uv run earthengine authenticate

Set EARTHENGINE_PROJECT when the account or deployment requires an explicit Google Cloud project.

Optional Cesium ion terrain and OSM buildings are configured in ignored local state:

cp apps/web/.env.example apps/web/.env.local

Set an origin-restricted, assets:read-only VITE_CESIUM_ION_TOKEN. Without a valid token the Workbench continues with ArcGIS WorldElevation3D and no hosted building layer; credentials are never required for the analytical runtime.

External MCP hosts can start the separate local stdio surface with pnpm mcp:stdio. It does not alter Pi's three-tool surface and intentionally omits live execution, exports, registry mutation, publication, and approval issuance.

Optional Python Profiles

uv sync --extra gee        # official Earth Engine API only
uv sync --extra pipeline   # Earth Engine + geedim + geetools
uv sync --extra workbench  # Earth Engine + geemap + leafmap
uv sync --extra climate    # Earth Engine + wxee
uv sync --extra full       # all reviewed foundational backends

The Workbench reports installed backends. Optional libraries do not add Pi tool schemas.

Pi Integration

Install from GitHub:

pi install git:github.com/7155/scoutpi-workbench

Or install the current checkout:

pi install /absolute/path/to/scoutpi-workbench

The repository is also structured as a publishable pi-package for Pi's npm-backed gallery, but no npm publication is claimed by this README. pnpm package:verify builds a temporary tarball, rejects development/private files and local credentials, extracts it, and starts all seven extensions plus the investigation skill through a real offline Pi RPC process. The npm tarball is the Pi runtime distribution; clone the repository to develop or run the Vue Workbench.

The package exposes seven extensions and one skill. Context, browser evidence, durable triggers, governance, observability, and checkpoints are event-only; the model still sees at most these three Earth tools:

Tool	Responsibility
earth_workspace	Adapter/backend registry, catalog routing, planning, probes, execution, export, artifacts, telemetry, recipes, and workflows
python_analysis	Bounded statistics over approved local artifact roots
earth_story	Evidence-bound story creation and persisted review artifacts

Important earth_workspace operations:

adapter_register / adapter_import / adapter_list
adapter_probe / adapter_enable / adapter_disable
contract / catalog_search / plan / preview / visualize
view_get / view_set
run / status / cancel / retry
export / export_local / artifacts
skill_save / skill_list / skill_publish
save_recipe / load_recipe / list_recipes
backend_list / backend_probe / telemetry
workflow_compile / workflow_list / workflow_replay / workflow_status

Pi starts with only earth_workspace active, then activates python_analysis and earth_story when the task reaches analysis or reporting. High-risk operations are intercepted by scoutpi-governance and require a real ctx.ui.confirm() receipt; model-authored confirmed: true is not trusted.

Use /earth-ecosystem in Pi to refresh and inspect reusable peer capabilities after package configuration changes. The same sanitized scan is persisted for the Workbench Runtime Center. ScoutPi does not fetch, install, update, enable, or remove packages; those decisions remain in Pi's official package manager:

pi list
pi config
pi install npm:<reviewed-package>
pi update --extensions
pi remove npm:<package>

Review packages in the official Pi extension catalog. Cross-session memory comes from an installed Pi provider; this package does not register a second memory tool surface.

To use the existing Wisdom Weasel input-method Core as the Context provider:

export SCOUTPI_IME_CORE_ROOT=/absolute/path/to/wisdom-weasel-rag-ime
export SCOUTPI_IME_CORE_DB="$HOME/Library/Application Support/RagIme/rag-ime.sqlite"

The adapter queries the existing Core through a fixed, versioned subprocess contract and reuses one bounded worker during the Pi session. Timeout/cancellation kills the worker, idle/session shutdown closes it, and SCOUTPI_IME_CONTEXT_PERSISTENT=0 restores one-shot execution. It does not enable raw debug output. Writeback remains disabled unless the operator also sets:

export SCOUTPI_IME_CONTEXT_WRITEBACK=1

That path still requires direct Pi UI approval. It stages an integrity-bound delivery and writes only through the Core's own privacy-aware InputMethodAdapter, with deterministic event tags for retry deduplication; ScoutPi never issues SQL against the IME database.

Use /earth-triggers to inspect durable workflow automation and /earth-trigger-approve <trigger-id> to issue an identity-bound dry-run delegation after direct review. Trigger automation never expands the three-tool model surface.

For an existing Edge session, authenticated web research, and browser-managed downloads, install BrowserBridge separately:

pi install git:github.com/7155/scoutpi-browserbridge

Runtime State

Complete plans and results are written below .scoutpi/earth_workspace; Pi receives compact IDs, states, and artifact paths.

.scoutpi/earth_workspace/
├── adapters/             # versioned runtime adapters
├── approvals/            # short-lived, single-use user approval receipts
├── skills/               # validated skill drafts
├── plans/                # immutable typed plans
├── jobs/                 # job state, requests, manifests, GeoTIFF/JSON artifacts
├── recipes/              # reusable InvestigationSpec inputs
├── workflows/            # compiled deterministic workflow contracts
├── workflow_runs/        # replay assertions and terminal state
├── telemetry/            # content-minimal operation metrics
├── stories/              # EarthStory JSON and Markdown
└── registry_events.jsonl # adapter audit trail

.scoutpi/runs/            # privacy-preserving Pi Agent traces and exact model usage
.scoutpi/checkpoints/     # content-minimal session recovery state and journals
.scoutpi/context/         # budgeted Context Packs and reviewed provider writebacks
.scoutpi/evidence/        # normalized browser evidence, copied artifacts and graphs
.scoutpi/triggers/        # signed delegations, durable triggers, event receipts and replay ledger
.scoutpi/pi-ecosystem/    # sanitized Pi tool/command capability profile for operators
.scoutpi/evaluations/     # privacy-safe benchmark, Agent, demo and recovery reports

Temporary Earth Engine tile URLs are for visualization. Download/export is used only when a durable local artifact, offline computation, evidence package, or downstream delivery is required.

Local API

Endpoint	Purpose
GET /api/environment	Earth Engine auth and optional backend capabilities
GET /api/mcp	Local MCP compatibility profile, tools, resources, and blocked operations
GET /api/pi-ecosystem	Last sanitized Pi tool/command capability scan and official package guidance
GET /api/backends	Reviewed backend manifests and operation contracts
POST /api/backends/:id/probe	Probe one reviewed backend
GET /api/telemetry	Aggregate operation token, latency, cache and compute proxies
GET /api/evaluations	Integrity-checked Pi, benchmark, end-to-end and recovery reports
GET /api/agent-runs	Pi lifecycle run summaries and provider-reported model usage
GET /api/checkpoints	Durable Agent session and interrupted-operation summaries
GET /api/context/packs	Token-bounded context, provenance and provider summaries
GET /api/context/writebacks	Pending, approved and rejected memory-provider outbox records
GET /api/evidence	Investigation-scoped canonical browser evidence records
POST /api/evidence/import	Import and artifactize an allowlisted BrowserBridge evidence file
POST /api/evidence/:id/bind	Bind a source to an investigation, claim, hypothesis, and explicit relation
GET /api/evidence/graph/:id	Browser claims, hypotheses, completed live runs, and finding coverage
GET /api/evidence/review/:id	Persisted claim, computation, provenance, counterevidence, and proxy review
GET/POST /api/triggers	List durable triggers or create a reviewable draft
POST /api/triggers/:id/approve	Issue a loopback-operator dry-run delegation
POST /api/triggers/:id/state	Pause, resume, or revoke a trigger
POST /api/triggers/:id/invoke	Idempotently invoke an active manual trigger
GET /api/trigger-runs	Read the durable trigger replay ledger
GET /api/delegations	Read signature-free delegation summaries
POST /api/trigger-events	Dispatch a bounded named event and persist only its hash/count receipt
GET /api/approvals	Human approval audit receipts
GET /api/contracts/:id	Fetch an adapter, skill, investigation, or export template on demand
GET/POST /api/adapters	List or register declarative adapters
POST /api/adapters/:id/probe	Verify collection and required bands against Earth Engine
POST /api/adapters/:id/state	Enable or disable an adapter
GET /api/catalog	Search enabled workspace adapters
POST /api/plans	Validate a spec and compile a plan
GET /api/plans/:id/visualization	Create a short-lived Earth Engine tile layer
POST /api/plans/:id/run	Start a dry run or Earth Engine execution
POST /api/plans/:id/export-local	Queue a supervised geedim GeoTIFF export
GET /api/jobs/:id?refresh=true	Refresh provider task state
POST /api/jobs/:id/cancel	Cancel a remote task or active local worker
POST /api/jobs/:id/retry	Retry a persisted local export as a new job
GET /api/jobs/:id/artifacts/:name	Read one bounded job artifact
GET/POST /api/skills	List or save generated skill definitions
POST /api/skills/:id/publish	Confirm and publish a generated Pi skill
GET /api/workflows, POST /api/workflows/compile	List workflows or compile one from a successful job
POST /api/workflows/:id/replay	Deterministically replay with drift and cost assertions
GET /api/workflow-runs/:id	Refresh a replay record

Verification

pnpm typecheck
pnpm test
pnpm python:check
pnpm harness:earth
pnpm harness:guangxi-flood
pnpm harness:mcp
pnpm harness:interview
pnpm harness:interview-demo
pnpm harness:recovery
pnpm package:verify
pnpm web:build

The Guangxi harness proves only the typed planning and artifact path by default. After Earth Engine authentication, pnpm harness:guangxi-flood-live performs the bounded Sentinel-1/Sentinel-2 proxy overlap computation. Its hectare output remains an investigation estimate, not a confirmed damage statistic.

The three interview harnesses are deterministic and do not call a paid model or live Earth Engine. On the fixed fixtures used by the current revision, harness:interview measured 1,478 -> 380 estimated schema tokens against eagerly disclosing eight runtime contracts (74.29%), 1,394 -> 384 delivered context tokens (72.45%), and 3 exploration control calls -> 1 workflow replay call (66.67%). Re-run the command after code changes; these are measured snapshot results, not permanent product claims.

The local Context Provider benchmark never invokes a model or writes candidate text into its report:

SCOUTPI_IME_CORE_ROOT=/absolute/path/to/wisdom-weasel-rag-ime \
SCOUTPI_IME_CORE_DB=/absolute/path/to/rag-ime.sqlite \
pnpm harness:context-provider

The real Pi RPC harness is opt-in because it can call a paid model:

SCOUTPI_HARNESS_KEY_FILE=/path/outside/the/repo/key.md \
SCOUTPI_PI_MODEL=gpt-5.6-sol \
pnpm harness:pi

harness:pi performs a model-list preflight only. Start the real extension process without a model turn using pnpm harness:pi-rpc; run paid end-to-end cases explicitly with pnpm harness:pi-live. Each live case must load and read the isolated investigation Skill before calling an Earth gateway, and is scored against persisted plans, jobs, artifacts, approvals and policy boundaries rather than assistant wording alone. Reports contain hashes, counts, safe operation labels and provider-reported usage, never raw prompts, tool payloads, provider URLs or credentials.

The current live smoke path also verifies a real Dynamic World tile and a small geedim GeoTIFF with Rasterio metadata inspection. Live checks depend on the operator's Earth Engine account and are not part of CI.

Documentation

• Interview entry and architecture story
• Interview demo script
• Resume bullets
• Runtime architecture
• Agent-built adapters and skills
• Backend Plugin SDK
• Runtime governance and observability
• Durable Agent checkpoints
• Context Bridge
• Browser Evidence Bridge
• Evidence Reviewer
• Workbench localization
• Spatial canvas and 2D/3D runtime
• MCP compatibility server
• Durable triggers and delegation
• Workflow Compiler
• Pi RPC Harness
• Pi ecosystem reuse audit
• Pi package and gallery release
• Project notes

Project Status

The typed runtime, dynamic registry, Workbench, direct tiles, local export, and deterministic dry-run paths are implemented. Live results still depend on account authorization, quota, dataset availability, and requested region/scale. ScoutPi never labels a plan, mock, or missing artifact as a computed finding.

Implementation References

The product direction and the Pi -> typed investigation -> supervised compute -> evidence Workbench architecture are original to this project. The implementation is independent and does not copy source from the projects below. They informed specific APIs and engineering tradeoffs:

Project	What was studied	ScoutPi boundary
earendil-works/pi and upstream badlogic/pi-mono	Typed extension lifecycle, RPC mode, commands, skills, user UI and active-tool APIs	Pi remains the host Agent loop; ScoutPi contributes domain tools plus event-only governance and tracing.
modelcontextprotocol/typescript-sdk	Stable 1.x stdio server, resources, resource links, annotations, and in-memory protocol testing	ScoutPi exposes four high-level compatibility gateways; it does not replace Pi or implement another generic MCP client.
google/earthengine-api	Initialization, map IDs, batch exports, task status, and cancellation	The worker exposes typed operations and never evaluates generated Earth Engine code.
CesiumGS/cesium	3D globe, imagery providers, camera control, workers, and Vite deployment boundaries	Optional lazy 3D renderer over ScoutPi's existing typed region and tile contracts; no separate Agent tool or scenario branch.
gee-community/geemap	Analyst-facing Earth Engine maps, charts, and export conventions	Optional review backend; BrowserBridge does not click through geemap widgets.
leftfield-geospatial/geedim	Tiled local GeoTIFF, NumPy, and Xarray delivery	Used behind a bounded, supervised export_local contract.
gee-community/geetools	Reusable Earth Engine preprocessing and object extensions	Pipeline dependency; future operations remain reviewed and typed.
davemlz/eemont	Concise preprocessing and spectral-index API design	Interface reference only to avoid two competing execution dialects.
opengeos/leafmap	Local raster/vector, STAC, PostGIS, and map integration	Optional local-data Workbench backend.
google/Xee and aazuspan/wxee	Earth Engine/Xarray bridges for long time series	Optional climate capability, not default tool surface.
opengeos/GeoAgent	Geospatial adapter metadata and confirmation boundaries	ScoutPi uses a small Pi gateway surface and deterministic compiler.
opendatalab/Earth-Agent	EO task taxonomy and trajectory evaluation ideas	ScoutPi emphasizes reproducible plans, probes, artifacts, and task supervision.
microsoft/Earth-Copilot	Separation of discovery, analysis, and visualization	ScoutPi is local-first, Pi-native, and dynamically adapter-driven.
opengeos/segment-geospatial and HYDRAFloods	Examples of mature algorithm providers	Future optional backends, never hard-coded scenario branches.
7155/scoutpi-browserbridge	Existing-browser research, downloads, and evidence capture	Browser control stays a separate install so Earth tools remain compact.
Pi package catalog, pi-extmgr, and pi-goal	Native package discovery/management and persistent autonomous-goal state	ScoutPi detects and routes compatible peers; it never auto-installs packages or replaces the generic goal loop.
pi-intercom, pi-mcp-adapter, and pi-subagents	Bounded session messaging, lazy schemas/output guards, atomic artifacts, budgets, and watchdog recovery	Reused as peer capabilities; ScoutPi owns only typed domain exchange contracts and deterministic execution.
sysid/pi-extensions	Event interception, symlink-aware path guards, default-deny writes, and optional OS sandboxing	Generic isolation composes with, but does not replace, ScoutPi's parameter-bound domain governance.
7155/wisdom-weasel-rag-ime	Local cross-application RAG/memory, provenance lanes, anti-echo and memory governance	Used through a query-only provider contract; Context Bridge owns task ranking, token budget and runtime trace attachment.

See PI_OPEN_SOURCE_ECOSYSTEM_REUSE_AUDIT.md for the wider reuse decision.

Contributing And Security

See CONTRIBUTING.md for the contract-first workflow and SECURITY.md for the local runtime threat model. Contributions are accepted under the Apache-2.0 license.