Lightbulb SDK and MCP

Python SDK, MCP server, CLI, and governed company worker for the Lightbulb Partners platform. Build typed business process primitives and custom project workflows, or connect Claude Code, Codex, or Cursor to Lightbulb domain agents, workspaces, connectors, builders, approvals, and AutoCompany.

Product boundary: this release line is suitable for controlled internal pilots. It is not yet a generally available external developer platform, and a locally verified capability is not a production-certified provider outcome. Spring remains the sole authority for tenant scope, RBAC, approvals, credentials, and live writes. See stability and support policy for the support and deprecation policy.

For the MCP host integration details (authentication, tool surface, troubleshooting), see MCP integration guide. For partner-facing setup, governance, and hosted MCP guidance, see the Lightbulb Partners Docs: https://www.lightbulbpartners.com/developers

Starting in 0.14, Connector Execution, executable primitives, durable custom-project runtime contracts, runtime telemetry, and connector conformance are supported SDK surfaces. The broad endpoint client remains beta. AsyncLightbulbClient provides complete behavioral parity, with hot paths async-native and long-tail methods thread-forwarded. Pin a minor version for production projects.

0.25.5 source candidate

Adds book backfill, owner digest, books and labour evidence, a recurring sales ledger, owner mandate, growth goals, the company gym and the collections loop. The platform also admits raw monthly Xero reports as governed reads for the company worker. Publication remains subject to complete package acceptance.

QuickBooks Online books now read into the same sealed snapshot as Xero's (company_books, company_backfill, and company_bootstrap from QuickBooks' company info), and company_team builds the team from the payroll's governed pages: each worker's hours and the cost of their hour, as the profiles every staffing document uses when none are passed.

Start here

• Install and verify your package, then connect an MCP host.
• Use the curated Python namespaces and typed custom projects.
• Run a governed company worker when the corresponding package release and host services are available.
• Browse the developer reference for the capability catalog, operational guides, release provenance, and support.

The developer reference separates the published PyPI package, public source, and reviewed source candidate. A release-note entry below can describe changes that have not been published yet. Check the PyPI release history for the versions available to install. Installing a package does not provision or start a Lightbulb host.

Work without the local runtime

Choose your starting path:

The following commands require a package containing the 0.24 additions. They do not read credentials, register work, or call providers:

lightbulb-company-worker --source-template
lightbulb-company-worker --bundle company-bundle.json --sources company-sources.json --preflight

A successful preflight means the configuration passed offline checks. Host permissions, account custody, engine-record existence and provider certification remain explicitly unchecked. Never interpret that report as deployment approval.

On an enabled host, add --status to the normal worker configuration to read operational evidence without claiming work. Add --report-html status.html for a portable report. Reports can contain private company references; retain them under the same access policy as other company artifacts.

One governed developer journey

Use the SDK through one five-step path:

1. Declare a typed primitive or Company Blueprint and select its exact version.
2. Validate it and preview it locally with external effects disabled.
3. Publish the immutable definition digest; publication does not grant effect authority.
4. Start or resume the exact hosted run, where Spring resolves scope, permission, approval, idempotency, and any Connector Tool Binding.
5. Observe sanitized events, evidence references, and the terminal outcome; treat missing or ambiguous provider observation as unresolved, never as success.

The compact seven-operation Golden Loop protocol is the primary model-facing interface. Raw domain and connector operations are an advanced surface and do not bypass the same Spring authority.

Curated SDK namespaces

New code should use the small lazy namespaces instead of adding package-root imports:

from lightbulb.core import JwtAuth, PermissionDenied
from lightbulb.hosted import AsyncLightbulbClient, LightbulbClient
from lightbulb.runtime import BusinessProcessPrimitive, ExecutablePrimitiveRuntime
from lightbulb.domains.finance import (
    PrepareJournalEntryInput,
    ReconcileJournalPostResult,
)

lightbulb.core and lightbulb.runtime are Supported. lightbulb.hosted and lightbulb.domains.finance are Beta; pin the SDK minor version. Importing a namespace is lazy and does not import its owning implementation modules. The finance namespace is the bounded journal-to-close lighthouse contract, not live-write authority: provider-backed operations remain quarantined until the exact capability version has current Spring-owned certification evidence.

Install

Install the latest published package from PyPI, then inspect its version:

python -m pip install --upgrade lightbulb-sdk
lightbulb version
python -m pip index versions lightbulb-sdk

For reproducible projects, pin the exact version reported by lightbulb version in your dependency lock. Beta API consumers should remain within that minor version until they have reviewed the migration notes. The package targets Python 3.10 and later; clean installation and upgrade acceptance currently covers Python 3.10–3.13.

The public repository is the source mirror. Prefer PyPI for installation. For source installs, select an immutable release tag or commit. The live developer documentation distinguishes the published version from a reviewed candidate; development source does not establish publication.

Quick start — connect an MCP host

python -m pip install --upgrade lightbulb-sdk
lightbulb setup
lightbulb version

lightbulb setup is an interactive wizard: device-flow login (browser handles MFA), probe /api/users/me, then merge a lightbulb MCP server entry into Claude Code (.mcp.json / .claude.json), Codex (~/.codex/config.toml), or Cursor (~/.cursor/mcp.json). For Claude Code it also installs Lightbulb Continuum lifecycle hooks in ~/.claude/settings.json (user target) or .claude/settings.json (project target). Existing servers, Claude settings, and unrelated hooks are preserved; backups use .bak.

Choose --target claude-code-user, --target claude-code-project, --target codex, --target cursor, or --target generic. Setup also accepts --yes / --no-write, --skip-login, and --url. Use lightbulb setup --help to inspect the installed version's supported options.

Manual .mcp.json

If you'd rather wire Claude Code by hand:

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com",
        "LIGHTBULB_MCP_PROFILE": "adaptive"
      }
    }
  }
}

The MCP server resolves credentials from a cached device-flow token (~/.lightbulb/tokens/) by default, or from env (LIGHTBULB_JWT + LIGHTBULB_TENANT_ID, etc.). Full auth precedence in MCP integration guide.

Lightbulb Continuum for Claude Code

The installed Claude hooks open or resume a private Context Space at session start, load a bounded relevant context pack with each user prompt, and checkpoint prompt, assistant, and compaction-boundary events. This gives Claude Code durable searchable working history; it does not change Claude's native context-window limit. Run /hooks in Claude Code to inspect the active hooks.

Each Context Space has a default 10,000,000-token indexed-storage ceiling. The host still receives only a small prompt-aware pack (up to its requested bounded budget); it can search and read deeper evidence by opaque reference. In other words, Continuum virtualizes a much larger working set behind the model rather than pretending the provider accepted a 10-million-token prompt. Repository continuity fingerprints let Codex and Claude Code resume the same private space without uploading a raw repository path or remote URL; an explicit LIGHTBULB_CONTEXT_REF can link other sessions. At the storage ceiling, automatic capture changes to read-only mode while pack, search, and read continue; a rejected append never disables recall of the full existing corpus.

For user custody and lifecycle control, the SDK exposes context_export(...), context_archive(...), and context_delete(...). Export is cursor/item/byte bounded; deletion is exact-scope and enters the server's grace-period purge workflow. These destructive lifecycle controls are intentionally not delegated to the model-facing MCP tool catalog.

Set LIGHTBULB_CONTEXT_CAPTURE=0 to disable all automatic capture, or explicitly set LIGHTBULB_CONTEXT_CAPTURE_TOOLS=1 to opt into storing redacted tool inputs and outputs. Tool capture is off by default because tool results can contain credentials or company-scoped data. Re-running lightbulb setup updates only Lightbulb's own handlers and leaves other Claude hooks intact.

To share one project-scoped Continuum across supported coding harnesses, run lightbulb setup --context-company-ref <company:...> --context-project-ref <project:...> for each host. Both selectors are rename-stable public refs and are reauthorized against the signed-in account on every hook invocation. When hooks are disabled or unavailable, the local stdio context_* MCP tools accept the same optional company_ref + project_ref pair and resolve it through authenticated discovery; they never accept tenant/user/internal-ID scope from the model.

Cross-harness Dynamic Workflows

Protocol 1.4 gives Claude, Claude Code, Codex, ChatGPT, and the Lightbulb harness one durable planner → builder → fresh-evaluator loop. The sync and async clients expose exactly eight operations: dynamic_workflow_start, dynamic_workflow_attach, dynamic_workflow_status, dynamic_workflow_next_assignment, dynamic_workflow_submit_plan, dynamic_workflow_submit_builder_result, dynamic_workflow_submit_evaluator_verdict, and dynamic_workflow_cancel. The stdio and hosted HTTP MCP surfaces delegate those operations to the same Spring authority; neither keeps a competing local hosted checkpoint.

Every mutation is exact-project scoped, revision-checked, idempotent, and receipt-bound. Evaluator acceptance defaults to failure and requires a binding distinct from the builder. MCP session separation is reported honestly as transport assurance; only a Lightbulb-controlled executable runtime can issue the stronger fresh-model-context attestation.

CLI

Running `lightbulb` with no arguments prints status: platform URL, cached token hint, detected Claude/Codex/Cursor configs, and next steps.

lightbulb                    # status (default)
lightbulb setup              # guided auth + MCP config merge
lightbulb version            # installed package version
lightbulb whoami
lightbulb dispatch finance --action chat --message "Quick AR aging summary"
lightbulb search-documents "quarterly revenue" --top-k 5
lightbulb approvals list

Company worker

The company worker, introduced in 0.23.0, runs on a trusted host with authenticated access to the company's Spring services. Inspect the installed command before configuring a deployment:

lightbulb-company-worker --help

Prepare a validated company bundle, exact connector-source bindings, and a host-only receipt-signing key file. The bundle names the project; Spring reauthorizes the selected company, project and user. Recurring source intake requires a whole UTC-day boundary. Keep receipt keys in the host's secret custody and out of MCP configuration, repositories, prompts, and logs.

The following is a deployment command template; its files and company ID must be supplied by your configured host:

lightbulb-company-worker \
  --bundle company-bundle.json \
  --sources observation-sources.json \
  --company-id YOUR_AUTHORIZED_COMPANY_ID \
  --worker-ref company-ops-1 \
  --receipt-key-file /run/secrets/company-receipts \
  --register --once

--register creates missing cadence state and its schedule; --once attempts one due cycle and exits. Omit --once under a process supervisor to continue checking due work. Restart with the same bundle, worker reference and signing key to resume the persisted schedule and authenticated journals. The polling loop does not grant approvals: connector reads and writes still pass through Spring, and an ambiguous provider write requires reconciliation.

Optional --growth-config enables the configured growth host. Optional --sales-config adds reusable business playbooks, existing-thread sales follow-up, expansion and win-back intake, and invoice-reminder coordination. See company sales automation for its exact configuration and connected Communication prerequisites. Sales approvals are polled independently of a retrying daily observation window. --reallocation-ref selects an existing reallocation journal instead; these options are mutually exclusive. The default cadence interval is 86,400 seconds and --interval-seconds accepts 60–604,800 seconds. Daily intake, demand pacing, reallocation, content observations, channel spend, attribution and growth aggregation retain their own evidence and freshness requirements. Complete engine inventory is scoped and bounded; missing coverage is refused.

See the company-worker and operations guide for configuration shapes, durable recovery and deployment prerequisites. Local package checks work without a host; authenticated operations require the configured host and approved provider connections to be available.

Environment variables (CLI & MCP)

Adaptive discovery for MCP hosts

Use adaptive discovery for an on-demand tool surface:

{
  "mcpServers": {
    "lightbulb": {
      "command": "lightbulb-mcp",
      "env": {
        "LIGHTBULB_URL": "https://agents.lightbulbpartners.com",
        "LIGHTBULB_MCP_PROFILE": "adaptive"
      }
    }
  }
}

This profile exposes the Lightbulb control plane rather than every generated domain/connector tool: identity and company selection, the backbone agent, approvals, connector status, workspace context, and the software delivery loop. The backbone agent can still orchestrate domain agents under the user's normal tenant, company, RBAC, and approval rules.

Governed runtime domain actions

The sync and async clients expose an explicit project-scoped lifecycle for runtime ACTION registration:

from lightbulb import RecursiveAgentPolicy

client.active_company_id = company_id
pending = client.register_runtime_domain_action(
    "finance",
    "review_invoice",
    project_id=project_id,
    idempotency_key="runtime-action:review-invoice:v1",
    component_ids=["finance-dashboard"],
    agent_spec={
        "name": "Invoice reviewer",
        "system_prompt": "Review invoices and return evidence.",
        "allowed_tools": ["xero.list_invoices"],
        "model": "gpt-5-mini",
        "domain": "finance",
    },
    execution_policy={"max_iterations": 3, "max_output_tokens": 512},
)
review = client.get_runtime_domain_action(pending["id"], project_id=project_id)
# After explicit human review, an authorized ADMIN/TENANT SDK client may approve.
approved = client.approve_runtime_domain_action(review["id"], project_id=project_id)
assert approved["status"] == "approved"
assert approved["recursive_spawnable"] is True

# Approval does not activate ordinary domain dispatch. Provision this exact,
# opaque revision only for a finite recursive run.
policy = RecursiveAgentPolicy(
    max_depth=2,
    max_total_nodes=4,
    max_cost_usd=1.00,
    max_delegation_context_bytes=4096,
    max_total_delegation_context_bytes=16384,
    allowed_agent_ids=(approved["recursive_agent_id"],),
)
result = client.recursive_agent_execute(
    "Review the selected project's invoices and state missing evidence.",
    inputs={"project_id": project_id},
    policy=policy,
)

Registration requires a selected company, an explicit project UUID, and a caller-owned idempotency key of 1-128 visible ASCII characters. Scope, status, owner, workflow selection, version, digest, and idempotency fields are never accepted in the JSON body. This first contract is immutable v1-only; changing a registered action requires a future revision lifecycle rather than mutating it. Authored specs use only name, system_prompt, allowed_tools, model, and domain; prompts are capped at 16,000 characters, specs at 32 KiB, and tool allow-lists at 16 entries. The example uses a seeded active read-only tool; replace it only with dotted tool names discovered as active in the platform registry. Execution policy accepts only bounded iteration, output-token, runtime, and cost values. Register always lands as pending_approval; list/get are review reads, and approve/reject are separate permissioned SDK transitions. Approval lands in approved and remains absent from ordinary domain dispatch. An approved dynamic-agent workspace response now includes recursive_agent_id plus recursive_spawnable; only that opaque revision may be named in an explicit finite recursive policy. During root preflight and before any authored child can spawn, the worker performs one Spring resolution that rechecks the current actor, exact tenant/company/project access, component RBAC, approval, revision digest, and execution policy. The run then freezes the spec and the intersection of its approved tools with the root's provisioned tool catalog. When a parent delegates, agent.spawn_child and agent.spawn_children accept an optional delegation_context JSON object. Parents should select only the facts, constraints, evidence references, decisions, open questions, and success criteria the child needs. Lightbulb deterministically compacts each packet, binds it to the inherited scope, returns a digest/compaction receipt without the packet contents, and atomically charges it against both policy byte ceilings. Child prompts label the packet as untrusted task data rather than instructions. Runtime-authored children cannot delegate, cannot poll the mutable control plane, and fail closed on unresolved scope, model substitution, or integrity drift. The durable tree enforces finite node/depth/token/cost/deadline limits, and authored children additionally clamp model, tools, runtime, iteration, output-token, and cost authority. The pinned Codex app-server has no request fields for max_iterations or max_output_tokens, so the worker enforces them as an online outer guard: it consumes the exact per-call last values from thread/tokenUsage/updated, interrupts the turn at the approved boundary, and closes the per-node app-server process before another ungoverned run can be reused. Token/cost authority comes from the private atomic tree rollout allocation; the model-visible node budget is only a consistency check and cannot increase it. Missing/malformed telemetry or a changed SDK observation hook fails closed. Because one provider response is already in flight when its usage becomes observable, that response can overshoot a token or estimated-cost boundary; the lightbulb.codex_turn_resource_guard.v1 receipt records the observed usage and overshoot. Guard cost is an explicitly conservative estimate that charges all input at the uncached rate and applies a 1.25 safety multiplier. Each node retains at most 16 raw usage notifications, and an incomplete result returns partial with finish_reason=resource_limit. There is no end-user runtime-action review UI yet. The UUID-backed register/list/get MCP tools are excluded by default and always excluded from the compact, OpenAI-facing Backbone profile. A trusted, non-public local developer surface must set LIGHTBULB_ENABLE_PRIVATE_RUNTIME_ACTION_MCP=true to expose them. None of these lifecycle methods directly dispatches or executes the action. SDK responses retain the server's snake-case scope/version/digest fields; registration also reports idempotent_replay and returns the same resource on an exact replay.

Deployment invariant: V1709 is additive at the schema level, but this feature is not safe across mixed application versions. Keep AGENTS_RUNTIME_REGISTRATION_ENABLED=false until every pre-V1709 server is drained, and disable it before any rollback to a pre-V1709 binary.

Success-aware least-active-memory regulation

The sync and native async clients can preview or execute active-memory regulation with an empirical success-evidence floor:

preview = client.memory_regulate(
    budget=500,
    dry_run=True,
    empirical_success_floor_ppm=950_000,
    empirical_success_min_samples=40,
    empirical_success_lookback_days=90,
    optimize_for_least_active_memory=True,
)

The server counts only exact-owner Memory references from retained successful skill-execution receipts and selects the smallest budget that clears the floor. It rejects insufficient, over-limit, or below-floor evidence before a consequential mutation. The returned quality gate says empirical_reference_retention_not_task_success: compacted digests receive no credit, and this is not a substitute for a held-out task-success evaluator. Mutating calls still require a caller-owned idempotency_key; the MCP tool is preview-only. The monorepo architecture note docs/memory-success-aware-regulation.md defines the metric and authority contract.

For held-out task quality, first request exact virtual candidate bindings:

preview = client.memory_regulate(
    budget=500,
    dry_run=True,
    optimize_for_least_active_memory=True,
    held_out_task_evaluation={
        "task_success_floor_ppm": 850_000,
        "minimum_sample_count": 200,
        "candidate_budgets": [100, 200, 300, 500],
        "authenticated_receipts": [],
    },
)

A trusted evaluator runs the same held-out cohort against the baseline and each returned candidate, then the mutating SDK call supplies its aggregate signed receipts plus an idempotency_key. The server recomputes the current source and candidate plans, rejects drift or any failed success/safety/cost gate, and selects the least active eligible candidate. Empirical reference evidence and held-out task evaluation are mutually exclusive in one request. See docs/memory-held-out-regulation.md; production verification is unavailable until the purpose-specific evaluator key and exact evaluator identities are provisioned.

Governed account-shell customization

The sync and async clients expose the tenant-scoped account-shell lifecycle: read, draft, preview, explicit publish, immutable history, and rollback. MCP exposes only read, draft, and preview so an agent can propose a change without crossing the human publication boundary.

New component placements should use component_version: 2. The closed registry fixes the React implementation and route. A document can set only emphasis, a narrowing page_scope (any, tenant, or company), and the exact registry capability with operation: navigate:

client.create_account_shell_customization_draft({
    "schema": "lightbulb.frontend_customization.v1",
    "surface": "account_shell",
    "name": "Operations",
    "tokens": {"colors": {"primary": "#315efb", "secondary": "#6366f1"}},
    "components": [{
        "component_id": "projects_launcher",
        "component_version": 2,
        "region": "header_actions",
        "props": {
            "emphasis": "primary",
            "visibility": {"page_scope": "company"},
            "action": {
                "capability_id": "service.projects-workspace",
                "operation": "navigate",
            },
        },
    }],
}, base_revision_id=None)

Historical version-1 placements remain readable. Rendering still checks the current viewer's service/RBAC capability; a stored placement never grants access. Routes, URLs, scripts, event handlers, raw CSS, Tailwind code, and iframes are rejected rather than interpreted.

Business primitives and Agent Builder

search_agent_marketplace is the normalized discovery front door for both action listings and domain-worker listings. It keeps business primitives and domain actions as distinct stable IDs, exposes only whitelisted contract metadata, and reports undeclared price/evaluation/risk fields as unknown rather than guessing. Without a domain filter, domain contracts are global discovery metadata and remain unverified. With a domain filter, the SDK performs one authenticated action lookup for that domain and marks only returned rows rbac_visible—never executable. Dispatch still re-checks tenant, selected company, RBAC, plan entitlement, connectors, and HITL policy.

The same contract is available from sync and async Python clients through search_agent_marketplace(...) and from the compact Backbone MCP profile. These discovery rows use stable synthetic IDs, not persisted UUIDs. Every row therefore reports installable=false, lifecycle_installable=false, and the stable reason synthetic_discovery_listing_not_persisted. Never pass a synthetic ID to install, pin, or invoke methods.

#### Publishing a governed action

Publication is tenant-scoped and must start with a preview. The preview resolves an existing server-authoritative action contract and returns the digest for the exact contract bytes the server would publish. Pass that digest back on publish as a compare-and-set guard:

publication = {
    "slug": "invoice-drafter",
    "name": "Invoice Drafter",
    "version": "1.0.0",
    "domain": "finance",
    "action": "create_invoice",
    "visibility": "PRIVATE",
    "pricing_model": "INCLUDED",
    "changelog": "Initial governed release",
}

preview = client.preview_marketplace_action_publication(**publication)
if not preview["publishable"]:
    raise RuntimeError(preview["blockers"])

published = client.publish_marketplace_action(
    **publication,
    expected_contract_digest=preview["expected_contract_digest"],
    idempotency_key="publish-invoice-drafter-1.0.0",
)

final = client.wait_for_marketplace_action_publication(
    published["publication_id"],
    timeout_seconds=120,
)

client.archive_marketplace_action(
    published["listing_id"],
    idempotency_key="archive-invoice-drafter",
    reason="Superseded",
)

The publication allowlist is slug, name, version, domain, action, visibility, pricing_model, and changelog; publish adds only expected_contract_digest. Raw manifests, agent or worker packages, prompts, models, tool policies, and scope IDs are not accepted. PRIVATE is the default. Shared UNLISTED or PUBLIC publication requires a portable platform contract, and PUBLIC is publisher-tier gated. Only INCLUDED pricing is implemented; there is no checkout publication path.

Use get_marketplace_action_publication(publication_id) for one status read, or the bounded wait_for_marketplace_action_publication(...) helper to poll until ready, failed, or archived; an initial scanning response can accompany an already-succeeded publication operation. Publish and archive are replay-safe only when each request carries a stable idempotency key. Archive preserves immutable revisions and audit history and does not uninstall existing company installations.

All five method names are identical on LightbulbClient and AsyncLightbulbClient (await the async calls): preview_marketplace_action_publication, publish_marketplace_action, get_marketplace_action_publication, wait_for_marketplace_action_publication, and archive_marketplace_action.

The Backbone MCP names are preview_agent_marketplace_action_publication, publish_agent_marketplace_action, get_agent_marketplace_action_publication, and archive_agent_marketplace_action. MCP has no wait tool; poll with its get tool.

Persisted marketplace actions use a separate, server-authoritative lifecycle: start with list_marketplace_listings(...) (or the MCP tool list_agent_marketplace_listings) and use the returned UUID listing_id and revision_id.

listings = client.list_marketplace_listings(kind="action")
listing = listings["items"][0]

installed = client.install_marketplace_action(
    listing["listing_id"],
    listing["revision_id"],
    idempotency_key="install-invoice-drafter-2026-07-10",
    deployment_targets=["codex_backbone", "claude_code_domain:finance"],
)
installation_id = installed["installation"]["installation_id"]

# Installation is deliberately inactive until a separate governed decision.
client.activate_marketplace_action(
    installation_id,
    idempotency_key="activate-invoice-drafter-2026-07-10",
)

preview = client.invoke_marketplace_action(
    installation_id,
    {"invoice_id": "invoice-123"},
    dry_run=True,
    idempotency_key="preview-invoice-123",
)

# Live execution is fail-closed unless it binds the exact successful preview
# and the caller explicitly confirms the reviewed request.
live = client.invoke_marketplace_action(
    installation_id,
    {"invoice_id": "invoice-123"},
    dry_run=False,
    preview_invocation_id=preview["invocation_id"],
    confirm_live=True,
    idempotency_key="invoke-invoice-123",
)

The tenant is derived from authentication and the company from the selected company header; neither is accepted in lifecycle request bodies. Every mutation and invocation requires an idempotency key. Invocation defaults to dry-run; live execution requires the successful preview ID for the exact inputs plus an explicit confirmation. Installs pin one immutable scanned revision, activation never auto-approves a separate HITL task, and receipts bind the exact installation, revision digest, request hash, trace/workflow IDs, cost state, and bounded redacted output. Use the matching async methods on AsyncLightbulbClient.

deployment_targets is an optional sequence of governed agent bindings. Its canonical vocabulary is codex_backbone, claude_code_domain (all Claude Code domain agents), and claude_code_domain:<domain> (for example, claude_code_domain:finance). The client rejects unsupported values and allows at most 16 unique targets. Omitting the argument, passing None, or passing an empty sequence installs the action for direct lifecycle invocation only; it is not projected into an agent's automatic tool catalog. The same argument and semantics apply to AsyncLightbulbClient.install_marketplace_action(...).

Worker listings remain discovery-only and report installable=false until a signed package, runtime ABI, SBOM, isolation declaration, and attestations exist.

#### Governed training-pair readiness (no launcher)

The SDK exposes the bounded Spring agent-ops gateway for one active company's exact pinned marketplace action revision:

readiness = client.inspect_training_pair_readiness(
    installation_id,
    listing["revision_id"],
    project_id=project_id,  # optional exact-scope constraint
)

# Inspect the server-derived custody association. A verified response contains
# only a bounded receipt summary; it is evidence, not training readiness.
custody = client.inspect_training_pair_input_custody(
    installation_id,
    listing["revision_id"],
    project_id=project_id,
)

# The backward-compatible flat preflight remains available.
preflight = client.preflight_training_pair(
    installation_id,
    listing["revision_id"],
    project_id=project_id,
)

# This is an explicit request, not a successful admission. Production returns
# the structured lightbulb.training_pair_admission.v1 body with HTTP 503.
unavailable = client.request_training_pair_admission(
    installation_id,
    listing["revision_id"],
    project_id=project_id,
    idempotency_key="training-pair-invoice-drafter-1",
)

# Only a previously persisted, exact-owner pair with an immutable marketplace
# source row can be read. Archived retained projects remain readable.
status = client.get_training_pair_status(pair_handle, project_id=project_id)

The same method names exist on AsyncLightbulbClient. Every call requires a valid selected company. Request bodies contain only installation_id, revision_id, and optional project_id; tenant, company, and actor authority come from authentication and server-side RBAC. Admission additionally requires a 1-200 character visible-ASCII Idempotency-Key. Preflight and status are read-only. Structured readiness returns exact source validity, ordered authority stages, blocked puffer_v4 and prime_verifiers lanes, and one next action. It cannot report admission or execution authority. Status is privacy-minimized and does not return datasets, artifacts, receipts, secrets, or storage locations.

Input-custody inspection is also read-only. The server derives the exact owner and associated receipt; callers cannot provide an owner binding, receipt, storage handle, tenant, company, or actor. The strict lightbulb.training_pair_input_custody.v2 response reports one of five states: authority_unavailable, not_associated, verification_failed, expired, or verified. Only verified includes a privacy-minimized receipt summary with digests, counts, timestamps, cost, the pinned framework commit for both lanes, and the aggregate signed snapshot binding/dataset identity needed for exact workflow-learning reconciliation. It never returns raw receipt evidence, signatures, storage locations, or lane artifact/partition digests, and it always reports admission and execution as unavailable.

The target-company policy overlay is fail-closed. COMPANY has read-only preflight/status access by default and needs an explicit company-scoped agent-ops.training.execute grant for admission requests. The structured 503 is reached only after authentication, target-company RBAC, idempotency-key, project-scope, and marketplace-source validation succeed. It is not an auth or validation fallback.

This is not a training runtime. There is no production admission assembler, scheduler, launcher, or worker persistence/install lifecycle. The gateway's six authoritative blockers are training_profile_unavailable, budget_authority_unavailable, snapshot_authority_unavailable, scheduler_unavailable, metering_unavailable, and artifact_storage_unavailable. The SDK preserves only that exact structured hard-503 admission body; unrelated errors and schema mismatches raise normally. The newer structured-readiness schema additionally reports input_attestation_unavailable because Spring has no trusted production input attestation authority wired to the offline dual-lane registry.

The matching MCP tools are inspect_agent_learning_readiness, inspect_agent_training_input_custody, preflight_agent_training_pair, request_agent_training_pair_admission, and get_agent_training_pair_status. The compact Backbone profile exposes custody inspection instead of the currently impossible admission request; the full profile retains the guarded admission tool for compatibility. The admission tool first returns a v2 request-bound confirmation receipt. After an explicit user request, return that exact confirmation_receipt together with confirm_admission_request=true. The receipt binds installation, revision, optional project, and the idempotency-key digest, so a bare boolean cannot be reused for a different future live request. The server still performs zero writes today.

Lightbulb MCP exposes business primitives as backend Lego blocks over the existing domain-agent and connector surface:

• list_business_primitives discovers primitives such as invoices, supplier

invoice intake, email, contracts, meetings, lead qualification, and onboarding.

• run_business_primitive is the canonical MCP entry to the same versioned

ExecutablePrimitiveRuntime used by the SDK. The Python surface executes locally eligible implementations; the hosted surface resolves authenticated company/project scope and fails closed until its managed Python runtime bridge is available. It never substitutes a Backbone workflow for primitive execution.

• list_executable_business_primitives discovers primitive implementation code

shipped in the Python package, including exact typed input/output schemas.

• run_sdk_business_primitive is the explicit compatibility alias for that same

runtime and remains useful for typed local validation and preview. A caller-provided project, approval, or idempotency value cannot turn a preview into a live write. Consequential effects must return through Spring's governed Connector Execution authority; neither primitive entry point self-authorizes.

• compile_business_workflow creates a portable

lightbulb.business_workflow_definition.v1 draft from selected primitives.

• validate_business_workflow checks primitive order, scope, RBAC, hidden

setup, approval gates, state transitions, recovery, and test coverage.

• simulate_business_workflow dry-runs one synthetic iteration without agents,

connectors, network calls, or external writes.

• compose_business_workflow compiles one SDK source definition and, when

publishing is requested, sends its exact executable projection (steps, triggers, and bounded defaults) through the governed one-shot authoring spine. It never turns the definition back into prose for a second compile. The SDK hashes that projection and reports server verification/normalization separately; richer source metadata stays in the returned client artifact and is not claimed as persisted by the current server schema.

• get_workflow_trigger_catalog and author_workflow_trigger expose the

principal-scoped schedule/event trigger allow-list and governed trigger authoring endpoint. MCP trigger authoring is staging-only and cannot activate a trigger; activation belongs to an explicit human-controlled SDK/product surface. Direct SDK trigger authoring also defaults to disabled. Unknown filters and implicit schedules fail closed.

• Convenience wrappers include business_create_invoice,

business_write_email, business_draft_contract, business_review_contract, and business_schedule_meeting.

Primitives are more than raw connector calls. Each primitive includes setup requirements, trigger events, emitted events, follow-up primitives, and builder guidance, plus a lightbulb.primitive_runtime_contract.v1 runtime contract. Workflow composition carries lightbulb.workflow_compiler_contract.v1 so Agent Builder can sequence primitives, add hidden setup, and preserve approval, observability, retry, and recovery behavior. For example, the email primitive tells Agent Builder to include reply webhooks or polling watchers, thread context capture, reply classification, and follow-up branches so the user does not need to know what a webhook is.

The backend ownership model is: Backbone plans and reasons across primitives; Agent Builder compiles workflow or loop definitions; installed typed SDK implementations execute provider-free previews; AutoCompany/workflow runtime runs repeatable loops; Coding Agent is used only for implementation gaps such as new adapters, new primitives, or approved code-delivery packets. Backbone's action=execute route never treats preview_only as advisory: reply classification, email, invoice, and meeting steps are Pydantic-validated and run with the in-memory connector preview runtime. Consequential catalog entries without a typed implementation (currently contract drafting and employee onboarding) fail closed instead of delegating to an LLM or domain route. An approved external write must use the separately governed hosted connector runtime.

The same SDK-first authoring loop is available directly in Python:

from datetime import timedelta

from lightbulb import (
    compile_business_workflow_definition,
    simulate_business_workflow,
    validate_business_workflow_definition,
)

workflow = compile_business_workflow_definition(
    "Email overdue customers and schedule meetings when they reply",
    primitive_ids=["communication.write_email", "calendar.schedule_meeting"],
    trigger_event="invoice.overdue",
    owner_role="finance_manager",
    inputs={
        "attendees": ["[email protected]"],
        "title": "Invoice follow-up",
    },
    loop=True,
    max_iterations=5,
)
assert validate_business_workflow_definition(workflow)["valid"]

dry_run = simulate_business_workflow(
    workflow,
    approvals={
        "communication.write_email": True,
        "calendar.schedule_meeting": True,
    },
)
assert dry_run["status"] == "completed"
assert dry_run["side_effects"] == "none_simulation_only"

# A false publish flag is a zero-write local draft. Publishing sends this
# validated definition projection through the governed user-plane endpoint (JWT) or
# internal service-plane endpoint (ApiKeyAuth); the server is still the
# validation gate of record and only publishes a valid version.
artifact = client.author_agentic_workflow(
    workflow["objective"],
    definition=workflow,
    publish=True,
)
assert artifact["authoring"]["definitionRecompiled"] is False

trigger = client.author_workflow_trigger(
    artifact["workflowDefinitionId"],
    trigger_type="event",
    event_type="email.received",
    enabled=False,  # stage first; activate only after explicit user confirmation
)

The inputs argument declares additional runtime input keys only. Its values are deliberately not copied into the persisted workflow DSL, so customer data and credentials cannot be multiplied across versioned step configuration. Supply actual values when starting a workflow instance; connector credentials must come from Lightbulb's scoped connector vault, never workflow inputs.

loop=True emits a persisted lightbulb.bounded_workflow_loop.v1 contract. The final action has one exact back edge guarded by $.payload.outputs.continue_loop == true and an unconditional terminal edge. The compiler limits the graph to len(steps) * max_iterations <= 100; Spring validates the mirrored contract and persists iteration/transition counters so a crash or resume cannot mint a fresh budget. Local simulation is deterministic and accepts loop_iterations=max_iterations + 1 only to demonstrate the fail-closed exhaustion result. Authored cost and timeout values still stop the next dispatch; hard cancellation of an already-running provider call remains a separate watchdog concern.

New catalog entries belong in lightbulb.business_primitives. Executable implementations belong behind BusinessProcessPrimitive with Pydantic models and runtime tests. MCP consumes those SDK modules; it is not a second primitive implementation registry.

Executable primitives and custom projects

Version 0.14 adds actual business process implementation code rather than only primitive metadata and Backbone prompts:

• ConnectorExecutionRequest / ConnectorExecutionResult normalize Tool

invocation, errors, approval state, preview behavior, and idempotency.

• HostedConnectorExecutor uses the authenticated Lightbulb control plane for

reads, safe previews, and the staged governed-write contract. The ordinary project API at /api/tools/governed-invoke remains on an explicit production rollout hold: it requires both GOVERNED_CONNECTOR_EFFECT_BOUNDARY_ENFORCED=true and GOVERNED_CONNECTOR_EXECUTION_ENABLED=true, and otherwise fails before dispatch. The verified-envelope hosted-worker lane is a distinct endpoint, /api/internal/tools/governed-invoke, with its own GOVERNED_CONNECTOR_WORKER_ENABLED gate plus exact write/read Tool allowlists and pinned catalog versions. Enabling one lane never enables or certifies the other. In either lane Spring binds dispatch to the exact project account, tenant binding, native adapter/handler, target digest, request, and governed journal/provenance contract. InMemoryConnectorExecutor provides deterministic project tests and local-only idempotent simulation.

• BusinessProcessPrimitive and business_process_primitive provide typed,

versioned implementation contracts that custom projects can extend.

• LightbulbProject declares allowed primitives, allowed connector Tools,

secret references, policy, and event-routed workflows.

• ProjectRuntime resolves deterministic input bindings, routes structured

events, bounds loops, preserves exact project-bound connector account aliases, and pauses on approval, missing input, or policy blocks.

• DurableProjectRuntime adds revisioned pause/resume, schedules, idempotent

event ingestion, expiring worker leases, and crash-safe custody of opaque connector account aliases. Hosted projects persist this state under authenticated tenant/company/project scope.

• RuntimeOutcome recorders automatically capture sanitized status, latency,

approval state, and failure kind without retaining inputs or outputs.

• Connector conformance covers every provider Tool declared by the shipped

executable primitives and can compare those contracts with the live hosted Tool schemas. Production certification additionally requires provider readback, replay/conflict, error, and ambiguous-recovery attestations.

• The initial twelve-tool finance production-conformance packet is explicitly

write-only. It does not certify the governed quickbooks.list_accounts or quickbooks.get_journal_entry READ; each Tool requires its own schema/effect, exact route/account isolation, READ-provenance, output-commitment, and normalized-error evidence without a fabricated approval or write attestation.

The SDK ships executable primitive implementations across communication, finance, calendar, legal, CRM, people, documents, approvals, project delivery, GTM, learning, physical operations, and regulated controls. Writes are preview-only by default. In-memory connector writes require an approval reference and all write requests require derived idempotency keys. Hosted writes additionally require a platform Project UUID. An apply call with no approval reference returns pending_approval plus the opaque ApprovalTask UUID created by Spring. After a human approves it through the normal approvals surface, retry the same run/request with that reference; Spring accepts it once only when Tool, canonical inputs, idempotency identity, scope, and actor match. Caller-declared effects are drift assertions only; uncatalogued or mismatched Tools fail closed. project_ref is correlation metadata only and can never substitute for the authenticated, company-bound Project UUID.

The major operating-domain additions are typed, deterministic control evaluators and bounded lifecycle projections over normalized snapshots. They do not pretend to be an ERP, WMS, MES, HCM, PLM, or GRC system of record. A ready, candidate_validated, or locally advanced result is evidence that the supplied package passed the declared SDK policy; it is never posting, fulfillment, employment, safety, regulatory, or deployment authority.

This change set does not provide live provider-conformance attestations, qualifying SLO or business-outcome measurements, or operator certification. SMS, voice, and WhatsApp transport recovery and the production-disabled worker-side subagent STEP_REQUESTS producer paths also remain uncertified; company-running readiness is false.

Every result is content-bound by deterministic operation/evidence digests and the executable runtime emits versioned receipts. The production evidence and incident contract is in docs/lightbulb-sdk-production-execution-runbook.md.

The canonical governed voice Tools are twilio.place_call_turn and twilio.lookup_call_status. The SDK materializer/observer keeps the raw call SID in private dispatch custody and exposes only an HMAC-bound public receipt. The Spring SMS/voice routes remain dark unless operators install both a reviewed Twilio HTTP transport and a production vault resolver; neither implementation is included here, and a catalog row or test fake is not transport certification. WhatsApp has SDK policy/materialization contracts plus a zero-write observer for short-lived, HMAC-sealed Spring webhook artifacts. It still has no native Spring adapter, Meta signature-verification endpoint, provider HTTP transport, or durable replay journal. Crash-safe private provider-ID recovery is therefore uncertified for SMS, voice, and WhatsApp, and ambiguous provider acceptance is never auto-replayed.

The encrypted workflow publication outbox protects orchestrator-owned requests and 13 of the 15 audited Spring direct STEP_REQUESTS lanes, including integration, internal-tool, legal, voice/receptionist, explicitly authorized scheduled-finance and CRM, and feedback dispatch. Commerce-intelligence and finance-market-data schedules remain deliberately undispatched because their profiles do not identify an authorized actor or service principal; they never substitute an arbitrary enabled user. The direct registrar joins an existing business transaction when present, persists an exact-scope running workflow receipt and outbox row, and leaves Kafka publication to the fenced relay.

Immediately before Kafka publication, the relay locks and rechecks the workflow, exact step generation, selected agent, and current actor authority. Definition-backed envelopes must match a fresh full-RBAC snapshot. Direct AppUser envelopes remain canonical identity-only claims (roles=[], permissions_scope=[], and no component claims); the relay verifies current identity and tenant/company scope without copying RBAC into the model-visible envelope. The exact external receptionist exception remains limited to sole role EXTERNAL_CONTACT and receives no runtime-authority token.

For every authoritative signature-v3 step, the worker repeats POST /api/internal/workflows/instances/{traceId}/state-preflight after context hydration and immediately before executor.dispatch, sending only a digest of the signed actor claims. Spring derives full-RBAC, identity-only, or external authority from the locked Workflow Instance. A deterministic mismatch terminalizes workflow/control and skips execution; a Spring or RBAC-store outage leaves the Kafka record uncommitted for retry.

HITL_REQUESTS and HITL_DECISIONS now use the same encrypted transactional outbox, binding the waiting Workflow Instance and terminal ApprovalTask update to the exact resume generation. Authoritative Spring lifecycle facts on agent.workflow.lifecycle.v1 and workflow-owned DLQ facts on agent.workflow.dlq.v1 use the separate encrypted V1865 transactional outbox. The legacy source top