@senpiper/sp-agent

Senpiper Workbench is Senpiper's Pi-based coding agent and web interface. This package includes the sp terminal application and the web workspace for the same sessions. It uses ~/.sp/agent and routes model traffic through Senpiper Gateway (sp-gateway).

Install

Requires Node.js 22.19 or newer.

See the installation guide for setup with https://sp-api.staging.senpiper.com/, gateway login, and the web workspace.

npm install --global @senpiper/sp-agent
sp

One installation provides both commands:

sp         # Start the terminal agent and its web sidecar
sp-web     # Start the web workspace directly

The web workspace connects to running terminal sessions. Senpiper Workbench owns the agents and their history files; the web UI does not create a competing writer. Run sp-web --help for browser, address, port, and authentication options.

The package bundles the Senpiper Workbench runtime, its required extensions, and the exact @senpiper/sp-web release with its locked dependency tree. You do not need a separate web installation, and npm does not resolve any web dependency at install time.

Platform binaries (the workspace terminal PTY, Next.js SWC, and image processing) are exact-pinned optional dependencies, so npm downloads only the build for your platform. Nothing is compiled and no install script needs approval, including on npm 12. Do not install with --omit=optional: that removes the workspace terminal binary.

Set SP_WEB_DISABLE=1 to run Senpiper Workbench without automatically starting the web sidecar. This does not uninstall the web workspace.

Publishing

Build the web workspace in a disposable copy of its repository, not a checkout running a development server. Pack the production build with npm pack --ignore-scripts.

Set the intended source versions before building. Pass the web tarball and its build lockfile to the Senpiper Workbench release command. The dry run validates the web artifact, builds the Senpiper Workbench tarball, and checks a clean global installation without publishing:

node scripts/publish-sp-packages.mjs --dry-run \
  --registry https://registry.npmjs.org \
  --web-tarball /absolute/path/senpiper-sp-web-0.1.1.tgz \
  --web-lockfile /absolute/path/web-build/package-lock.json \
  --output /absolute/path/release-artifacts

Copy the exact validated web tarball into that output directory alongside the Senpiper Workbench tarball. Keep exactly one tarball for each package there. Log in with an npm account that has write access to the @senpiper scope, then publish from an interactive terminal:

npm run login:sp:npm
npm whoami --registry https://registry.npmjs.org
node scripts/publish-sp-npm-artifacts.mjs /absolute/path/release-artifacts --check
node scripts/publish-sp-npm-artifacts.mjs /absolute/path/release-artifacts

The artifact publisher checks registry hashes, publishes the web workspace first and then the agent, and verifies each published hash. Complete npm's interactive 2FA prompt when requested. --check checks artifacts and registry state without publishing. If interrupted, rerun with the same artifacts; matching published versions are verified and skipped. Do not rebuild between attempts. The private runtime and extension packages remain bundled and do not need separate public releases.

The private packages/sp-web-contract workspace only records the required web version for source development. It is not the web application and is never used as the release artifact.

The supported programmatic entry point is @senpiper/sp-agent/sdk. It does not expose an unbound session constructor.

Concurrent web sessions

Interactive Senpiper Workbench supplies an instance-owned session manager to its required bridge extension. Web create_session {cwd} and resume_session {sessionFile} return {sessionId} for an independently running session. Select its existing-format discovery descriptor to send commands. Terminal replacement and browser disconnection leave other sessions running.

SDK hosts can use the same verified factory:

import { createSpSessionManager } from "@senpiper/sp-agent/sdk";

const sessions = await createSpSessionManager();
try {
  const { sessionId } = await sessions.create("/absolute/project");
  // Discover the descriptor by sessionId and use its authenticated bridge.
} finally {
  await sessions.dispose();
}

createSpAgentSession() also returns its cwd-bound services for hosts constructing an AgentSessionRuntime. Pass the manager as createSpAgentSession({ sessions, ... }) in the runtime factory, then call sessions.attachRuntime(runtime) before binding a terminal UI to install file-acquisition guards. See packages/sp-agent-extensions/CONCURRENT_SESSIONS.md in the source repository for the protocol and lifetime rules.

Third-party notices

Senpiper Workbench includes Pi code under the MIT license below. The web workspace's upstream license and T3 attribution are included in the installed @senpiper/sp-web package as LICENSE and THIRD_PARTY_NOTICES.md. Other dependencies retain their own licenses.

MIT License

Copyright (c) 2025 Mario Zechner

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.