sdk

Imported from NekoSekaiMoe/agentboster (subpackage/sdk/AGENTS.md). Install upstream with npx skills add NekoSekaiMoe/agentboster --skill sdk. Copyright stays with the author.

AGENTS.md — subpackage/sdk/

Cross-tier public SDK for the AgentBoster platform. Today the SDK only re-exports the CLI runtime surface (@agentboster-cli/core); the long-term scope covers five surfaces — CLI runtime, Web HTTP API, Workflow DevKit, Desktop IPC/bridge, and the agentd tool protocol. See docs/ARCHITECTURE.md for the tier model and surface maturity.

Layout

• src/index.ts — package entry. Re-exports the CLI surface flat (backwards compatibility for import { ExtensionAPI } from '@agentboster/sdk') plus the four newer surfaces as namespaces (import { web, workflow, desktop, agentd } from '@agentboster/sdk').
• src/cli/index.ts — CLI runtime surface. Explicit re-export list (~350 names mirroring the runtime). Regenerated by scripts/regen-exports.py. Do NOT hand-edit the export block — it's generated. Backed by vendor/core.d.ts stub.
• src/web/ — Web HTTP API surface:
  • auth.ts — AuthSession, PairCodeEntry, IAuthProvider, etc.
  • envelope.ts — CliResult<T> / AgentdResult<T> (the two de-facto response shapes; Web has no canonical envelope type).
  • sse.ts — CliSessionEvent discriminated union (heartbeat / tool-request / lock).
  • routes.ts — request body shapes for high-traffic CLI routes (/api/cli/chat, /api/cli/tool-result, /api/cli/schedules, ScheduleTaskRecord, CliRemoteState).
• src/workflow/ — Workflow DevKit surface:
  • chunks.ts — WorkflowUIMessageChunk, WorkflowStatusData, RuntimeEventPayload, all 4 ChatSource variants.
  • hooks.ts — 3 hook-builder payloads + the 7 lifecycle hook payload types.
  • messages.ts — PersistedMessagePayload, SerializedMessageForDB.
  • dispatch.ts — facade types for startWorkflow / resume*.
  • types.ts — TokenUsage, CompressResult.
  • Backed by vendor/workflow/ai-sdk.d.ts stub for the ai package.
• src/desktop/ — Desktop IPC surface:
  • settings.ts — AppSettings (centralized, 13 Rust fields) + enum unions (CloseAction, ScreenshotFormat, etc.) + DEFAULT_APP_SETTINGS.
  • invoke.ts — DesktopInvokeMap (16 Tauri commands) + makeTypedInvoke(invoke) factory.
  • rpc.ts — RPC bridge types (RpcStartOptions, RpcSessionState, MCP discovery, etc.).
  • events.ts — Tauri event payloads + DesktopEventMap.
  • workspace.ts — WorkspaceState, Pane, SessionRuntime.
• src/agentd/ — Agentd protocol surface:
  • envelope.ts — APIResponse<T> (the daemon-wide envelope).
  • tools.ts — ToolExecRequest/Response, ToolDefinition, SSE exec stream events.
  • sandbox.ts — SandboxProfile (docker/docker-strict/lxc), SandboxMeta, per-agent overrides.
  • security.ts — L0Rule, L1ScoreResult, Decision, L2ConfirmRequest.
  • node.ts — NodeRegisterRequest/Response, NodeHeartbeatRequest, AgentCgroupStat, liveness constants.
  • paths.ts — wire-level Task/Session/Message/AgentConfig/ HealthResponse/BotSource/BotCapabilities.
• src/compat.ts — SDK-only cross-version helpers.
• vendor/core.d.ts — CLI runtime stub (all types → any) so the SDK type-checks without the cli workspace. Regenerated by scripts/regen-stubs.py.
• vendor/workflow/ai-sdk.d.ts — minimal stub for the ai package (UIMessage, UIMessageChunk, StepResult) so the Workflow surface type-checks without ai installed.
• scripts/ — one regen script per surface:
  • regen-stubs.py + regen-exports.py — CLI stub + re-export list.
  • regen-web.py, regen-workflow.py, regen-desktop.py, regen-agentd.py — drift detectors. Each scans its surface's source-of-truth files, extracts exported names, and reports mismatches against the SDK mirror. They do NOT generate code — porting is by hand, drift detection is automated.
• docs/ — canonical docs: PACKAGES.md, CAPABILITY_MODEL.md, PACKAGE_CAPABILITY_TEMPLATE.md, ARCHITECTURE.md. The Desktop-specific docs (ICONS, PERMISSIONS, THEMES_DESKTOP_MAPPING, RELEASES) stayed in desktop/docs/.
• examples/ — five reference CLI extensions, each covering a distinct pattern. Type-checked by examples/tsconfig.json (less strict than the SDK itself — examples are reference code, not production code).
• README.md — author-facing intro covering all five surfaces.

When the CLI runtime's public surface changes

Whenever cli/packages/coding-agent/src/index.ts adds or removes an export:

cd subpackage/sdk
yarn regen-cli   # or: python3 scripts/regen-stubs.py && python3 scripts/regen-exports.py
yarn check:lint

This regenerates both vendor/core.d.ts (the stub used for standalone type-check) and src/cli/index.ts's CLI export block. Commit both.

When any other tier's public contract changes

Each of the four newer surfaces has its own drift detector. Run all of them after touching the source tier:

cd subpackage/sdk
yarn regen-web        # reports drift against lib/auth, lib/cli, app/api/cli/**
yarn regen-workflow   # reports drift against types/workflow.ts, lib/workflow/**
yarn regen-desktop    # reports drift against desktop Rust + bridge.ts + main.ts
yarn regen-agentd     # reports drift against subpackage/agentd Go structs
# or all at once:
yarn regen-all

The drift detectors do NOT auto-fix — they report which source-tier exports are missing or stale in the SDK mirror. Porting is by hand. To silence intentional omissions (helpers, runtime-only functions), add the symbol to the INTENTIONALLY_SKIPPED allowlist at the top of the relevant regen-*.py script.

Module

Standalone npm package (@agentboster/sdk). NOT part of the cli/ Yarn workspace — install it independently. Ships as TypeScript source (the CLI runtime compiles extensions via jiti), so there is no build step.

Toolchain

Biome is configured by biome.json at the SDK root. The SDK has no yarn.lock and ships no runtime deps — Biome and TypeScript are provided by the repo root's node_modules, so all commands assume you've run yarn install at the repo root first.

Commands

There is no yarn install for the SDK package itself — it has no runtime dependencies. From the repo root after yarn install:

# Type-check (SDK + examples). Use the repo-root binaries; the SDK
# package itself doesn't ship tsc.
node node_modules/typescript/bin/tsc -p subpackage/sdk/tsconfig.json --noEmit --ignoreDeprecations 6.0
node node_modules/typescript/bin/tsc -p subpackage/sdk/examples/tsconfig.json --noEmit --ignoreDeprecations 6.0

# Biome lint (no --write; --write mutates the tree and hides failures).
node node_modules/@biomejs/biome/bin/biome check --error-on-warnings subpackage/sdk/src/ subpackage/sdk/examples/ subpackage/sdk/scripts/

# Drift detection (read-only; reports mismatches between source tiers
# and the SDK mirrors). See the per-surface regen sections below.
python3 subpackage/sdk/scripts/regen-web.py
python3 subpackage/sdk/scripts/regen-workflow.py
python3 subpackage/sdk/scripts/regen-desktop.py
python3 subpackage/sdk/scripts/regen-agentd.py

The --ignoreDeprecations 6.0 flag silences TS 6.x's TS5101 warning about baseUrl, which is the only TS-6-specific noise the SDK hits.

There is no build script — the SDK is consumed as .ts source. The CLI runtime compiles extensions on load via jiti; other surfaces are pure type re-exports consumed at type-check time.

Conventions

• Re-exports, not copies. A type belongs in the SDK only if it is already public in its source tier. Don't duplicate type definitions here; if a type is missing, add it to the tier's source of truth first (CLI: core/extensions/types.ts; Web: lib/auth/, app/api/cli/**; Workflow: types/workflow.ts; Desktop: src-tauri/src/lib.rs, src/rpc/bridge.ts; Agentd: Go structs under subpackage/agentd/), then port.
• One surface at a time. Each surface lives under its own src/<surface>/ subdirectory with its own stub (if needed) and regen path. Do not mix surfaces in the same file — it breaks independent drift detection.
• CLI flat, others namespaced. The CLI surface is re-exported flat at the package root for backwards compatibility. The four newer surfaces (Web / Workflow / Desktop / Agentd) are exported as namespaces to avoid name collisions (CLI and Desktop both export RpcSessionState; CLI and Agentd both export ToolDefinition). When you add a new type to a non-CLI surface, it is reachable only via the namespace (sdk.desktop.AppSettings, sdk.agentd.APIResponse).
• Manifest namespace. Document both agentboster (current) and pi (legacy) in examples. The runtime accepts both; new docs prefer agentboster.
• Tier-local implementations win. The SDK is a curated view, not a fork. Each tier's internals stay in that tier; only the public contract is mirrored here.
• Each type carries a // Source: <relative path>:<line> comment. The regen scripts use these for drift detection and reviewers use them to verify the port is faithful.
• Helpers go in src/compat.ts. Cross-version helpers (shims for API changes between runtime versions) live there. Don't inline them in examples.

Adding new public types

For the CLI runtime (ready):

1. Add the type to cli/packages/coding-agent/src/core/extensions/types.ts (the source of truth).
2. Re-export from cli/packages/coding-agent/src/core/extensions/index.ts and (if it's truly public) from coding-agent/src/index.ts.
3. Run yarn regen-cli to refresh vendor/core.d.ts and src/cli/index.ts.
4. If it has a cross-version compatibility story, add a helper in sdk/src/compat.ts.
5. Document in sdk/docs/PACKAGE_CAPABILITY_TEMPLATE.md if it's part of the recommended authoring flow.

For the Web / Workflow / Desktop / Agentd surfaces (ready):

1. Add the type to the tier's source of truth (Web: route handler inline zod or a new lib/.../types.ts; Desktop: Rust struct with serde tags, or TS interface in bridge.ts / main.ts; Agentd: Go struct in clawless/types.go or similar).
2. Run the surface's regen script (yarn regen-<surface>) and confirm it reports the new export as MISSING.
3. Hand-port the public shape into the SDK under src/<surface>/. Add a // Source: <relative path>:<line> comment so the next reviewer can verify the port is faithful.
4. If the surface has a stub (Web: none; Workflow: ai-sdk.d.ts; Desktop: none; Agentd: none), extend it for any new external packages the port references.
5. Run yarn check:lint and the surface's regen script again — the drift detector should now report the export as MIRRORED.
6. If the type is large or has a deep dependency closure, mirror only the wire shape and use unknown for nested types you don't need to type today; add a // TODO: tighten when <upstream> lands comment so future work is discoverable.

Docs sync

When desktop/docs/PACKAGES.md or related docs change, update the copy in sdk/docs/ too. The Desktop copies are kept as the "applied" view (desktop-specific examples inline); the SDK copies are the canonical generic version. Prefer editing the SDK version and let Desktop follow.

When the platform-tier boundaries change (new surface, new auth pattern, new event schema), update docs/ARCHITECTURE.md and the maturity table in README.md together — they describe the same model.