Skip to content

Self-improving AI Employees for everyone

docs(credentials): document placeholder secrets and the Stripe trigger gap

trohitge057a99a5905
diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.md
index b793b6b1..4316c26a 100644
--- a/docs-internal/SETUP.md
+++ b/docs-internal/SETUP.md
@@ -34,6 +34,10 @@ command provisions the Python side (uv, the venvs, bytecode; a minute or two).
`curl -fsSL https://opencompany.sh/install.sh | bash` (or `install.ps1` on
Windows) installs bun, Python and uv first and provisions eagerly.
+Provisioning also creates `.env` as a plain copy of `.env.template`, including
+its publicly known placeholder secrets. Replace them before you store any
+credentials; see [Environment Configuration](#environment-configuration).
+
**Known issue in registry installs (open since 0.2.0; the status line of
[errors.md #25 and #26](./errors.md) says whether your version is fixed)**: a
registry install provisions but then `company start` (and `company serve`)
@@ -173,7 +177,15 @@ Copy the example environment file:
cp .env.template .env
```
-Alternatively, `company build` scaffolds `.env` from `.env.template` automatically when it is missing (step `[0/6]`) and generates fresh random secrets for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the dev placeholders. An existing `.env` is never modified. If you copy the template by hand and later enable auth (or set `DEPLOYMENT_MODE` to anything other than `local`), the server logs a non-fatal error banner at startup until the placeholder secrets are replaced.
+`company build` also creates `.env` when it is missing (step `[0/6]`), and then generates fresh random values for `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` instead of the template's `dev-` placeholders. It never modifies an existing `.env`, and most installs already have one by then: `bun install` in a checkout, `company provision` and a global install's first `company` command all create `.env` as a plain copy of the template, placeholders included.
+
+**Replace the placeholder secrets before you store any credentials.** Generate one value per key, set it in `.env` (or the process environment), and restart:
+
+```bash
+python -c "import secrets; print(secrets.token_hex(24))"
+```
+
+The startup warning about placeholder secrets appears only with login on or `DEPLOYMENT_MODE` other than `local`, so a default local install never shows it. Never change `API_KEY_ENCRYPTION_KEY` once credentials are stored: they are encrypted with it, and a new key makes them unreadable, so they would have to be entered again. See [Credentials Encryption → Placeholder secrets](./credentials_encryption.md#placeholder-secrets).
### Key Settings
@@ -200,7 +212,7 @@ Add these to `.env` or configure via the Credentials UI:
When `VITE_AUTH_ENABLED=false` (the default):
- Login page is skipped entirely
- User is set as anonymous with owner privileges
-- Encryption service auto-initializes with `API_KEY_ENCRYPTION_KEY` as the password
+- Credentials are still encrypted with `API_KEY_ENCRYPTION_KEY`, exactly as with login on (the key never comes from a user's password)
- API keys can be saved/retrieved without user authentication
- Useful for local development and testing
diff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.md
index 6f46b482..8cfa0254 100644
--- a/docs-internal/TEMPORAL_ARCHITECTURE.md
+++ b/docs-internal/TEMPORAL_ARCHITECTURE.md
@@ -660,7 +660,7 @@ The Temporal binary + persistence are managed in-process by the plugin-folder pa
**Worker crash-restart (months-long durability)**: the SDK `Worker` is single-use — a second `run()` on the same instance raises `RuntimeError("Already started")`. Both restart loops therefore REBUILD a fresh worker per attempt: `TemporalWorkerManager._run_worker` via `_build_worker()`, and every `TemporalWorkerPool` queue worker runs under `_run_queue_worker` (previously a bare `worker.run()` task — one crash silently killed the queue's only worker and its activities pended forever). Backoff knobs: `TEMPORAL_WORKER_RESTART_BACKOFF_SECONDS` / `_MAX_SECONDS`. Locked by `tests/temporal/test_worker_restart.py`.
-**WS surface**: `_handlers.py` registers `temporal_status` / `temporal_start` / `temporal_stop` via `services.ws_handler_registry.register_ws_handlers`. `_refresh.py` registers a WS-connect callback via `services.status_broadcaster.register_service_refresh` so the FE health indicator stays current.
+**WS surface**: `_handlers.py` registers `temporal_status` / `temporal_start` / `temporal_stop` via `services.ws_handler_registry.register_ws_handlers`. `_refresh.py` registers a status-refresh callback via `services.status_broadcaster.register_service_refresh`, which seeds the FE health indicator once at startup (refresh callbacks run once, in a background task, not on each WebSocket connect).
**Months-long durability contract**: running and paused deployments survive backend restarts, are never auto-terminated, and keep executing for months. None of the mechanisms below carries a `workflow.patched` marker: the lifetime-cap removal and the poll-interval floor apply unconditionally, including when an older history is replayed.
diff --git a/docs-internal/authentication.md b/docs-internal/authentication.md
index 4ec675bc..f89800f7 100644
--- a/docs-internal/authentication.md
+++ b/docs-internal/authentication.md
@@ -74,10 +74,11 @@ class User(SQLModel, table=True):
**`UserAuthService` never initialises, derives or clears the encryption key.**
The container injects `EncryptionService` and `CredentialsDatabase` into it,
-but the only use of either is the read-only `is_encryption_initialized()`
-(a pass-through to `EncryptionService.is_initialized()`); `credentials_db` is
-held and unused. Earlier revisions of this document described `login()`
-calling `_initialize_encryption(password)` and `logout()` calling
+and neither is used: the only reference to the encryption service is
+`is_encryption_initialized()` (a pass-through to
+`EncryptionService.is_initialized()`), which nothing calls, and
+`credentials_db` is held and never read. Earlier revisions of this document
+described `login()` calling `_initialize_encryption(password)` and `logout()` calling
`self.encryption.clear()`. Neither method has ever existed. The Fernet key is
**server-scoped**: initialised once during startup in `main.py` from
`API_KEY_ENCRYPTION_KEY`, never derived from a user password and never
@@ -276,8 +277,11 @@ Recorded explicitly because each of these is easy to assume is handled.
and `dev_secret_offenders()`: server startup (lifespan) logs a non-fatal error
banner when `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` still
carry the dev template placeholders while auth is enabled or `DEPLOYMENT_MODE`
-is not `local`. A `company build`-scaffolded `.env` avoids this by generating
-fresh `secrets.token_hex(24)` values at scaffold time.
+is not `local`. Only a `.env` that `company build` creates itself gets fresh
+`secrets.token_hex(24)` values; `bun install` in a checkout and
+`company provision` copy the template as-is, and with login off in a local
+install nothing warns. See
+[Credentials Encryption → Placeholder secrets](./credentials_encryption.md#placeholder-secrets).
## Race Condition Handling (TanStack Query bootstrap)
The frontend starts before the backend is ready during cold launch, so the
@@ -367,7 +371,7 @@ useEffect(() => {
| `client/src/components/auth/LoginPage.tsx` | Login UI |
| `client/src/components/auth/ProtectedRoute.tsx` | Route guard |
| `server/models/auth.py` | User SQLModel with bcrypt |
-| `server/services/user_auth.py` | `UserAuthService`: register / login / JWT mint + verify / `get_current_user`. Holds the encryption service only for the read-only `is_encryption_initialized()` check (see the note under Auth Service) |
+| `server/services/user_auth.py` | `UserAuthService`: register / login / JWT mint + verify / `get_current_user`. Holds the encryption service and credentials database but uses neither; its `is_encryption_initialized()` has no callers (see the note under Auth Service) |
| `server/routers/auth.py` | REST endpoints |
| `server/middleware/auth.py` | Route protection (`PUBLIC_PATHS` / `PUBLIC_PREFIXES`) |
| `server/core/config.py` | Settings with `vite_auth_enabled` field |
diff --git a/docs-internal/credentials_encryption.md b/docs-internal/credentials_encryption.md
index f0876ce2..b4ba566e 100644
--- a/docs-internal/credentials_encryption.md
+++ b/docs-internal/credentials_encryption.md
@@ -78,7 +78,9 @@ Routers call AuthService.get_api_key() / get_oauth_tokens() ...
EncryptionService.clear()
```
-`EncryptionService.is_initialized()` is checked before any encrypt/decrypt call. If the server key is misconfigured, the service raises at startup rather than returning unusable ciphertext later.
+`encrypt()` and `decrypt()` raise `RuntimeError` if the cipher was never initialized, and the lifespan checks `is_initialized()` once before deriving the key.
+
+Only a missing or short key is caught at startup. `API_KEY_ENCRYPTION_KEY` is a required `Settings` field with `min_length=32`, so `Settings()` fails before anything else runs. A key that is present but differs from the one the credentials were stored with is not detected: PBKDF2 derives a valid Fernet key from any string, so startup succeeds, and every later lookup of a stored credential fails instead. `decrypt()` raises `ValueError`, and `CredentialsDatabase.get_api_key` / `get_oauth_tokens` log `Failed to decrypt ...` at ERROR and return `None`, so the app behaves as if nothing were stored. `AuthService.get_api_key` does not cache a miss, so the error repeats on every lookup.
## Two Separate Credential Systems
@@ -128,13 +130,13 @@ How the pieces are wired:
- `AuthService` maintains the memory-only decryption cache.
- `CredentialsDatabase` is a DI singleton (`container.credentials_database()`). The container injects it into `AuthService` and into `UserAuthService` (which holds it but never uses it), and `main.py` resolves it at startup to create tables and read the salt. The container does not stop anything else from resolving it, so "routers and services go through `AuthService`" is a rule to follow, not something DI enforces.
-The in-memory cache is important: decrypting on every request would be slow, and writing decrypted values to Redis would defeat the encryption. Each `AuthService` instance caches decrypted credentials in process memory only, and `AuthService.clear_cache()` flushes them on demand (used by the logout handler).
+The in-memory cache is important: decrypting on every request would be slow, and writing decrypted values to Redis would defeat the encryption. Each `AuthService` instance caches decrypted credentials in process memory only, and `AuthService.clear_cache()` flushes them on demand (`POST /api/auth/logout` calls it).
## Multi-Backend Abstraction
For deployment flexibility, `credential_backends.py` defines an abstract interface intended to be selected via the `CREDENTIAL_BACKEND` env var.
-**Status: not wired in.** Nothing in the server calls `create_backend()`, and `Settings.credential_backend` / `aws_secret_arn` / `aws_region` are read only inside it. `AuthService` always talks to `CredentialsDatabase` directly, so every install uses Fernet-encrypted SQLite and setting `CREDENTIAL_BACKEND` currently has no effect. The rest of this section describes the abstraction as written.
+**Status: not wired in.** Nothing in the server calls `create_backend()`, and `Settings.credential_backend` / `aws_secret_arn` / `aws_region` are read only inside it. `AuthService` always talks to `CredentialsDatabase` directly, so every install uses Fernet-encrypted SQLite and setting `CREDENTIAL_BACKEND` currently has no effect. The value is still validated: the field is a `Literal["fernet", "keyring", "aws"]`, so any other value fails `Settings` at startup. The rest of this section describes the abstraction as written.
```python
class CredentialBackend(ABC):
@@ -170,13 +172,15 @@ aws = ["boto3>=1.34.0"] # AWS Secrets Manager
```env
# .env at the repo root (scaffolded from .env.template; there is no server/.env)
-# Required for Fernet backend
-API_KEY_ENCRYPTION_KEY=<any string, at least 32 chars for good entropy>
+# Required, at least 32 characters (Settings enforces min_length=32).
+# Never change it once credentials are stored (see Placeholder secrets below).
+API_KEY_ENCRYPTION_KEY=<48 random hex characters>
-# Which backend to use -- currently has no effect (see Multi-Backend Abstraction)
-CREDENTIAL_BACKEND=fernet # fernet | keyring | aws
+# Which backend to use -- currently has no effect (see Multi-Backend Abstraction),
+# but a value other than fernet | keyring | aws fails Settings validation
+CREDENTIAL_BACKEND=fernet
-# Path to credentials SQLite file
+# Path to credentials SQLite file (a relative path resolves under DATA_DIR)
CREDENTIALS_DB_PATH=credentials.db
# AWS backend only (also unused until the backend layer is wired in)
@@ -184,15 +188,38 @@ AWS_SECRET_ARN=arn:aws:secretsmanager:...
AWS_REGION=us-east-1
```
-If `API_KEY_ENCRYPTION_KEY` is missing or changed, existing ciphertext becomes undecryptable. There is no key-rotation mechanism today: users re-enter their keys after a key change. This is a deliberate simplification inherited from the n8n pattern.
+A missing or short `API_KEY_ENCRYPTION_KEY` stops startup (see [Lifecycle](#lifecycle)). A changed one makes every existing ciphertext undecryptable: lookups return `None`, and users must re-enter their keys. There is no key-rotation mechanism today. This is a deliberate simplification inherited from the n8n pattern.
+
+### Placeholder secrets
+
+`.env.template` ships publicly known `dev-` placeholder values for `API_KEY_ENCRYPTION_KEY`, `SECRET_KEY` and `JWT_SECRET_KEY` (the exact literals are `DEV_SECRET_LITERALS` in `server/core/config.py`). Whether an install replaces them depends on how its `.env` was created:
+
+| How `.env` was created | Secrets |
+|---|---|
+| `bun install` in a source checkout (the root `postinstall` hook runs `scripts/install.js`) | Copied from the template as-is: placeholders |
+| Global install: `company provision`, the first `company` command, or the `install.sh` / `install.ps1` installers (all run `scripts/install.js`) | Copied from the template as-is: placeholders |
+| `company build` when no `.env` exists yet (step `[0/6]`, `_scaffold_env_secrets` in `cli/commands/build.py`) | A fresh `secrets.token_hex(24)` value for each `dev-` placeholder |
+| Docker (`docker/entrypoint.sh`) | Fresh values written to the env file on the data volume at first start |
+| `company deploy` | Fresh values for every deploy (`cli/commands/deploy/_secrets.py`) |
+| Desktop app | Nothing is generated: the template values apply unless `<userData>/desktop.env` sets them |
+
+An existing `.env` is never modified. So the usual checkout flow (`bun install`, then `bun run build`) keeps the placeholders: `install.js` has already created `.env` by the time `company build` looks for it.
+
+`dev_secret_offenders()` (`server/core/config.py`) makes startup log a non-fatal error banner only when login is on (`VITE_AUTH_ENABLED` is anything other than `false`) or `DEPLOYMENT_MODE` is not `local`. A default local install, with login off, runs on the placeholders without any warning.
+
+To replace them, generate one value per key and set it in `.env` or the process environment, which wins over `.env`:
+
+```bash
+python -c "import secrets; print(secrets.token_hex(24))"
+```
-When `company build` scaffolds `.env` from `.env.template` (step `[0/6]`), it generates a fresh `secrets.token_hex(24)` value for `API_KEY_ENCRYPTION_KEY` (and `SECRET_KEY` / `JWT_SECRET_KEY`) instead of copying the dev placeholder; an existing `.env` is never touched. If the dev placeholder survives while auth is enabled or `DEPLOYMENT_MODE != local`, startup logs a non-fatal error banner (`dev_secret_offenders()` in `core/config.py`).
+Do this before the first credential is saved. After that, never change `API_KEY_ENCRYPTION_KEY`, or every stored credential becomes unreadable (see above). Changing `JWT_SECRET_KEY` signs every user out.
## Security Properties
- **Server-scoped key**: not tied to user login sessions. JWT cookies expire, but the encryption key survives across restarts.
- **No plaintext on disk**: credentials are only decrypted in memory.
-- **No plaintext in Redis**: even in Redis mode, only encrypted envelopes cross the wire (the cache layer never stores decrypted credentials).
+- **No plaintext in Redis**: credentials never pass through the cache layer. `AuthService` receives a `CacheService` handle but does not use it for credentials, so neither plaintext nor ciphertext reaches Redis, even with `REDIS_ENABLED=true`.
- **Salt per install**: different OpenCompany installs have different salts, so ciphertext is not portable across installs even with the same server key.
- **Held for the process lifetime**: the derived key is never written to disk, but it is not wiped at shutdown either. `EncryptionService.clear()` (which drops the Fernet reference) is called only by tests; the `main.py` lifespan shutdown does not call it, so the key leaves memory when the process exits.
diff --git a/docs-internal/discord_service.md b/docs-internal/discord_service.md
index 5924a0c8..852ef343 100644
--- a/docs-internal/discord_service.md
+++ b/docs-internal/discord_service.md
@@ -153,7 +153,7 @@ ready" for a bad credential.
The reason is the deploy path: the engine marks a deployed trigger
`_pre_executed` and passes `_trigger_output` through verbatim
-([models.py:378-392](../server/services/execution/models.py)), so the node body
+(`ExecutionContext.create` in [`services/execution/models.py`](../server/services/execution/models.py)), so the node body
never runs and a download flag there would work on the canvas and silently do
nothing once deployed. `whatsappBusinessMedia` exists for the same reason and
documents it in its own module docstring.
@@ -246,10 +246,12 @@ walker touches. [`nodes/__init__.py`](../server/nodes/__init__.py) swallows
import errors during discovery, so a failing library import would make the
whole plugin silently disappear rather than report anything.
-**Both trigger frozensets matter.** Omitting a trigger from
-`EVENT_TRIGGER_TYPES` / `WORKFLOW_TRIGGER_TYPES` is a silent failure: deploy
-filters on them and ignores the node with no listener and no warning
-([constants.py:402-406](../server/constants.py)). Tests assert the membership.
+**Both trigger frozensets are asserted.** Omitting a trigger from
+`WORKFLOW_TRIGGER_TYPES` is a silent failure: `TriggerManager.find_trigger_nodes`
+filters on it, so deploy ignores the node with no listener and no warning (see
+the comment inside `WORKFLOW_TRIGGER_TYPES` in [`constants.py`](../server/constants.py);
+`stripeReceive` is missing from it today). `EVENT_TRIGGER_TYPES` has no
+production reader, but the tests assert membership in both.
## Testing
diff --git a/docs-internal/node-logic-flows/stripe/stripeReceive.md b/docs-internal/node-logic-flows/stripe/stripeReceive.md
index 4eaff6e0..0d147882 100644
--- a/docs-internal/node-logic-flows/stripe/stripeReceive.md
+++ b/docs-internal/node-logic-flows/stripe/stripeReceive.md
@@ -70,7 +70,7 @@ flowchart TD
S --> Q[source.receive: internal push queue] --> D[event_waiter.dispatch event]
D --> M{waiter.event_type == event.type}
M -- stripe.webhook vs stripe.charge.succeeded --> N[no match: waiter untouched]
- subgraph canvas Run / legacy deploy
+ subgraph canvas Run only
P[_check_precondition] -- daemon not started, not logged in --> E1[error Stripe not connected]
P -- daemon start failed --> E2[error Stripe daemon failed to start]
P -- ok --> G[event_waiter.register node_type=stripeReceive: event_type=stripe.webhook, filter=build_filter]
@@ -83,13 +83,13 @@ flowchart TD
- **Precondition** (`_check_precondition`, canvas Run only): if the listen
source is not `_started`, `has_credential()` (a filesystem sniff for
`_api_key` in the CLI's `config.toml`) must be true, else the run returns
- the error "Stripe not connected. Add Stripe API key in Credentials and
- connect." Then `source.start()` runs: `ensure_stripe_cli()`, the
+ the error "Stripe not connected. Log in with Stripe in Credentials."
+ Then `source.start()` runs: `ensure_stripe_cli()`, the
`DaemonEventSource` credential gate, and `ProcessService.start(name=
"stripe-listen", workflow_id="_stripe", working_directory=daemons_dir())`.
- A failed start returns "Stripe daemon failed to start: <error>". Deploying
- a Stripe workflow is the demand signal for the daemon; the status refresh
- never starts it.
+ A failed start returns "Stripe daemon failed to start: <error>". Only a
+ canvas Run reaches this precondition (deploy skips the node, see below),
+ and the status refresh never starts the daemon.
- **Signature verification fails closed**: no captured secret -> HTTP 503
with `Retry-After: 5`; missing header, missing `t=` / `v1=`, or no
matching `v1=` candidate -> HTTP 400. Multiple `v1=` values are accepted
@@ -106,11 +106,20 @@ flowchart TD
dispatches the envelope, whose `type` is `stripe.<stripe type>`, and
`event_waiter.dispatch` selects waiters by exact equality
`w.event_type == event_type`. As written, a real delivery therefore never
- resolves a `stripeReceive` waiter on either path. The node is NOT
- registered with `register_canary_trigger_type` (no call in
- `nodes/stripe/`), so deployment rides the legacy
- `TriggerManager.setup_event_trigger` collector, which registers through
- the same `event_waiter.register` and inherits the same key.
+ resolves a `stripeReceive` waiter. Deploy never registers one at all:
+ `stripeReceive` is not in `constants.WORKFLOW_TRIGGER_TYPES`, and
+ `TriggerManager.find_trigger_nodes` filters on that set, so a deployed
+ workflow starts no listener for it and logs no warning. It is not
+ canary-registered either (no `register_canary_trigger_type` call in
+ `nodes/stripe/`).
+- **Filter-input mismatch**: even with matching keys, `event_waiter.dispatch`
+ calls each waiter's filter with the envelope's `data`, not the envelope,
+ and `WebhookTriggerNode.build_filter` rebuilds a `WorkflowEvent` from what
+ it receives. That raises a `ValidationError`, which the dispatcher logs as
+ `[EventWaiter] Filter error`, so the waiter would still not resolve. The
+ regression test `test_dispatch_with_live_waiter_does_not_crash`
+ (`tests/services/test_events.py`) builds its waiter by hand, keyed on the
+ envelope type with an always-true filter, so it covers neither mismatch.
- **Data-shape mismatch**: `StripeWebhookSource.shape` stores only
`payload["data"]` (Stripe's `{object, previous_attributes?}`) in
`WorkflowEvent.data`, but `shape_output` and the livemode predicate read
@@ -135,9 +144,11 @@ flowchart TD
<whsec_...>, models=[])` whenever a `whsec_` token appears on the daemon's
stderr (fire-and-forget task).
- **Broadcasts**: `update_node_status(..., "waiting", {"event_type":
- "stripe.webhook", "waiter_id": ...})` from the trigger manager / executor;
- `make_status_refresh` mirrors `source.status()` plus login state into
- `broadcaster._status["stripe"]` under broadcast type `stripe_status`.
+ "stripe.webhook", "waiter_id": ...})` from the generic trigger handler
+ (`services/handlers/triggers.py`) on a canvas Run; `make_status_refresh`
+ mirrors `source.status()` (`type` / `running` / `pid`, without login state)
+ into `broadcaster._status["stripe"]` once at startup and broadcasts it as
+ `stripe_status`, which no frontend code handles.
- **HTTP**: `POST /webhook/stripe` answered by the router after
`handle()`; the source's `receive()` also enqueues the event on its
internal push queue (nothing consumes that queue for this source).
@@ -167,10 +178,11 @@ flowchart TD
- Secret race: events forwarded before the `whsec_` line is captured get a
503 and are retried by Stripe / the CLI.
- One account per install; the daemon is a single global process.
-- No auto-restart on daemon crash - status shows disconnected until the user
- reconnects.
-- The `stripe_service.md` request-flow diagram documents `data=payload`
- (the full event); the code stores `payload["data"]`.
+- No auto-restart on daemon crash, and nothing reports it: the source's
+ `_started` flag is cleared only by `stop()`, so `stripe_status` still says
+ `running: true`, the precondition skips the start, and the Credentials modal
+ still shows Stripe as connected. Disconnect, then Login with Stripe,
+ restarts it.
## Related
diff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.md
index 8f671673..9a98cb57 100644
--- a/docs-internal/plugin_system.md
+++ b/docs-internal/plugin_system.md
@@ -584,7 +584,7 @@ skips them. The two non-underscore `.py` files are the plugin classes
| OAuth callback path (`/api/<provider>/callback`) so `services.oauth_utils.get_redirect_uri` never cross-imports `nodes/<plugin>/_oauth.py` | `services.ws_handler_registry` | `register_oauth_callback_path(provider, path)` |
| Trigger event-filter builder | `services.event_waiter` | `register_filter_builder(node_type, fn)` |
| Trigger pre-execution check (e.g. "bot not connected") | `services.event_waiter` | `register_trigger_precheck(node_type, fn)` |
-| Service-status refresh on WebSocket connect | `services.status_broadcaster` | `register_service_refresh(callback)` |
+| Service-status refresh (runs once, in a background task at startup; not on each WebSocket connect) | `services.status_broadcaster` | `register_service_refresh(callback)` |
| Per-node output schema (when not auto-derivable) | `services.node_output_schemas` | `register_output_schema(node_type, ModelClass)` |
| Master-Skill expander (how a `masterSkill` node expands into its enabled skills during edge walking) | `services.plugin.edge_walker` | `register_master_skill_expander(fn)` — registered by `nodes.skill` on package import. |
| Agent Context descriptor (node connected on `input-context`) | `services.plugin.edge_walker` | `register_agent_context_builder(async_fn)` — RFC-0002; the framework walks the edge but owns no knowledge of the descriptor's keys or thread-selection rules. Reference: `nodes/context/_descriptor.py`. |
@@ -912,7 +912,7 @@ All Wave 10 invariants in `test_node_spec.py` still run; Wave 11 invariants in `
added Wave 11.I),
`event_waiter.register_filter_builder` (event filters),
`event_waiter.register_trigger_precheck` (trigger pre-execution
- checks), `status_broadcaster.register_service_refresh` (WS-connect
+ checks), `status_broadcaster.register_service_refresh` (service-status
refresh callbacks), `node_output_schemas.register_output_schema`
(output schemas).
- Wave 11.I — Eight more plugin domains migrated to the
diff --git a/docs-internal/speech_provider_rfc.md b/docs-internal/speech_provider_rfc.md
index 71823292..3114da1e 100644
--- a/docs-internal/speech_provider_rfc.md
+++ b/docs-internal/speech_provider_rfc.md
@@ -24,11 +24,11 @@ big**. That constraint, measured rather than assumed, drives nearly every decisi
|---|---|---|
| Temporal blob **error** — activity result, activity **input**, workflow result | **2,097,152 B** | server default; no custom `DataConverter` or `PayloadCodec` anywhere in the repo |
| Temporal blob **warning** | 524,288 B → `PayloadSizeWarning` | not covered by `pyproject.toml` `filterwarnings`, so it surfaces |
-| Retries burned before the failure is reported | **3** | `_PayloadSizeError` absent from `NON_RETRYABLE_ERROR_TYPES` ([`_retry_policies.py:51`](../server/services/temporal/_retry_policies.py)) |
-| Legacy `execute_node_activity` internal WS | 4 MiB inbound (aiohttp default, `max_msg_size` unset) | [`activities.py:243`](../server/services/temporal/activities.py) |
-| `node_outputs.data` | no cap; written **3×** per store (`output_main`/`output_top`/`output_0`) | [`activities.py:488`](../server/services/temporal/activities.py) |
-| WS broadcast | no size guard; retained in `_status` **forever** and replayed to every newly connecting client | [`status_broadcaster.py:90,683`](../server/services/status_broadcaster.py) |
-| In-memory `_outputs` | never evicted except by `clear_all_outputs` | [`workflow.py:74,766`](../server/services/workflow.py) |
+| Retries burned before the failure is reported | **3** | `_PayloadSizeError` absent from `NON_RETRYABLE_ERROR_TYPES` in [`_retry_policies.py`](../server/services/temporal/_retry_policies.py) |
+| Legacy `execute_node_activity` internal WS | 4 MiB inbound (aiohttp default, `max_msg_size` unset) | the `ws_connect` call in `NodeExecutionActivities.execute_node_activity` ([`activities.py`](../server/services/temporal/activities.py)) |
+| `node_outputs.data` | no cap; written **3×** per store (`output_main`/`output_top`/`output_0`) | `store_node_output_activity` in [`activities.py`](../server/services/temporal/activities.py) |
+| WS broadcast | no size guard; retained in `_status` **forever** and replayed to every newly connecting client. Since this RFC, `update_node_output` caches an output larger than `_CACHED_OUTPUT_MAX_BYTES` as a stub (`_elide_for_cache`); `update_node_status` still caches its `data` as given | `StatusBroadcaster._status`, `update_node_status` and `update_node_output` in [`status_broadcaster.py`](../server/services/status_broadcaster.py) |
+| In-memory `_outputs` | never evicted except by `clear_all_outputs` | `WorkflowService._outputs` and `clear_all_outputs` in [`workflow.py`](../server/services/workflow.py) |
### What actually happens to a 12 MB base64 TTS result
diff --git a/docs-internal/stripe_service.md b/docs-internal/stripe_service.md
index e2920f59..f1dc406d 100644
--- a/docs-internal/stripe_service.md
+++ b/docs-internal/stripe_service.md
@@ -15,6 +15,21 @@ supervision, lifecycle WebSocket handlers, status broadcasts, CLI
invocation) lives in [`services/events/`](../server/services/events/) —
this folder contributes only the Stripe-specific shapes.
+> **Known gap: `stripeReceive` never fires today.** Deploy skips it: the node
+> is not in `constants.WORKFLOW_TRIGGER_TYPES`, which
+> `TriggerManager.find_trigger_nodes` filters on, and it is not
+> canary-registered, so a deployed workflow starts no listener for it and logs
+> no warning. A canvas Run waits forever: `WebhookTriggerNode.__init_subclass__`
+> keys the waiter on the source type `stripe.webhook`, while
+> `WebhookSource.handle` dispatches the envelope, typed `stripe.<event>`, and
+> `event_waiter.dispatch` matches types exactly. Even with matching keys, the
+> dispatcher hands each filter the envelope's `data`, and
+> `WebhookTriggerNode.build_filter` raises a validation error rebuilding a
+> `WorkflowEvent` from it. The rest of the plugin (`stripeAction`, login, the
+> daemon) does not use this path. The
+> [`stripeReceive` card](./node-logic-flows/stripe/stripeReceive.md) also
+> records a field mismatch in `shape_output`.
+
## Architecture
```
@@ -73,10 +88,12 @@ StripeWebhookSource.handle(request)
│ → WorkflowEvent(id=evt_…, type="stripe.charge.succeeded",
│ source="stripe://acct_…", data=payload["data"])
│
- └── event_waiter.dispatch(source.type, event)
+ ├── self.receive(event) (queues it on the source)
+ │
+ └── event_waiter.dispatch(event) (the envelope alone; matched on event.type)
▼
- StripeReceiveNode waiters resolved
- (WebhookTriggerNode.execute returns the shaped event)
+ StripeReceiveNode waiters are keyed "stripe.webhook", so none match
+ (see the Known gap at the top)
```
### Request flow — outgoing CLI action
@@ -168,10 +185,12 @@ WS message: stripe_logout
handle_stripe_logout()
├── get_listen_source().stop()
├── run_cli_command([binary, "logout", "--all"])
- │ (clears ~/.config/stripe/config.toml)
+ │ (clears ~/.config/stripe/config.toml; if this process has not
+ │ resolved the CLI yet, e.g. right after a restart, the handler
+ │ deletes that file directly instead)
├── _mark_logged_out() ← marker-token clear
│ auth_service.remove_oauth_tokens("stripe")
- └── _broadcast_catalogue_updated()
+ └── _broadcast_credential_event("credential.oauth.disconnected")
(modal flips back to "Not Connected")
```
@@ -189,7 +208,7 @@ StripeListenSource.start() (lock-protected, idempotent)
│ command="<shlex-quoted-binary> listen
│ --forward-to http://localhost:{port}/webhook/stripe
│ --print-secret", # no --api-key
- │ workflow_id="_stripe_global",
+ │ workflow_id="_stripe", # the source's workflow_namespace
│ working_directory=<DATA_DIR>/daemons, # shared daemons_dir() root
│ line_handler=self._on_line, # ← per-line callback
│ )
@@ -207,23 +226,22 @@ StripeListenSource.start() (lock-protected, idempotent)
already runs.)
StripeListenSource.stop()
- └── ProcessService.stop("stripe-listen", "_stripe_global")
+ └── ProcessService.stop("stripe-listen", "_stripe")
```
## Key Files
| File | Description |
|---|---|
-| `server/nodes/stripe/__init__.py` | Wiring: 5 `register_*` calls + `make_status_refresh`. |
+| `server/nodes/stripe/__init__.py` | Wiring: `register_ws_handlers`, `register_webhook_source`, `register_service_refresh` (with `make_status_refresh`) and `register_output_schema` for both nodes. There is no `register_canary_trigger_type` call. |
| `server/nodes/stripe/_credentials.py` | `StripeCredential(Credential)` — thin marker class. The CLI manages auth at `~/.config/stripe/config.toml`; this class only exposes the captured `stripe_webhook_secret` for the framework's signature-verifier path. |
| `server/nodes/stripe/_install.py` | `ensure_stripe_cli()` — async, idempotent, lock-guarded. Resolves the binary path: in-process cache → system PATH → previously-downloaded copy at `<DATA_DIR>/packages/stripe/bin/stripe[.exe]` (`core.paths.package_dir("stripe") / "bin"`) → fresh download from GitHub releases (pinned `_VERSION = "1.40.9"`) into that same dir. Asset-name map covers Windows AMD64, Linux x86_64/arm64, macOS x86_64/arm64. Subsequent calls hit the cache instantly. |
-| `server/skills/payments_agent/stripe-skill/SKILL.md` | LLM teaching markdown for the `stripe_action` tool. ~10K chars covering customers, charges, payment_intents, refunds, invoices, products/prices, subscriptions, the `trigger` command, common workflows, quoting/escaping, idempotency, test vs live mode, error patterns, and webhook delivery. |
+| `server/skills/payments_agent/stripe-skill/SKILL.md` | LLM teaching markdown for the `stripe_action` tool, covering customers, charges, payment_intents, refunds, invoices, products/prices, subscriptions, the `trigger` command, common workflows, quoting/escaping, idempotency, test vs live mode, error patterns, and webhook delivery. |
| `server/config/credential_providers.json` | JSON-driven Credentials Modal catalogue. The `payments` category + `stripe` provider entry tell the frontend modal to render a **Login with Stripe** button (no API-key field) wired to the `stripe_login` / `stripe_logout` / `stripe_status` WebSocket handlers. No React file edits required. |
-| `server/nodes/stripe/stripe_action.py` | `tool_name = "stripe_action"` ClassVar (resolved via `services/node_registry.py`) and the matching `tool_description` — what the LLM sees when the action node is wired to an agent's `input-tools` handle. |
| `server/nodes/stripe/_source.py` | `StripeListenSource(DaemonEventSource)` and `StripeWebhookSource(WebhookSource)` plus their singletons. |
| `server/nodes/stripe/_handlers.py` | WS handlers via `make_lifecycle_handlers` (`stripe_connect` / `stripe_disconnect` / `stripe_reconnect`) plus the plugin-specific `stripe_login`, `stripe_logout`, `stripe_trigger` (synthetic test events) and `stripe_status` (overrides the factory's status handler to add login state). See [WebSocket handlers](#websocket-handlers). |
-| `server/nodes/stripe/stripe_action.py` | `StripeActionNode` — pass-through over the CLI via `run_cli_command`. |
-| `server/nodes/stripe/stripe_receive.py` | `StripeReceiveNode(WebhookTriggerNode)` — filter overrides + output reshape. |
+| `server/nodes/stripe/stripe_action.py` | `StripeActionNode` — pass-through over the CLI via `run_cli_command`. Its `tool_name = "stripe_action"` and the matching `tool_description` are what the LLM sees when the node is wired to an agent's `input-tools` handle. |
+| `server/nodes/stripe/stripe_receive.py` | `StripeReceiveNode(WebhookTriggerNode)` — filter overrides + output reshape. Never fires today (see the Known gap at the top). |
| `server/services/events/__init__.py` | Public framework surface — exports every base class + helper. |
| `server/services/events/daemon.py` | `DaemonEventSource` — supervises subprocess via `ProcessService`. Subscribes to ProcessService's per-line callback (`line_handler`) instead of re-tailing the on-disk log files. Credential gate is `await self.has_credential()` so non-api-key auth (Stripe → `is_logged_in()`) plugs in via subclass override. |
| `server/services/process_service.py` | Spawns + supervises long-lived subprocesses. Loops `stream.readline()` per stdout/stderr, writes to `.log`, broadcasts to Terminal, and forwards each decoded line to the optional `line_handler` async callback (Wave 12.B addition for typed event-source subscribers — see `DaemonEventSource._on_line`). |
@@ -236,8 +254,8 @@ StripeListenSource.stop()
| `server/nodes/visuals.json` | `stripeAction` skill map only (`{"skill": "stripe-skill"}`); no `stripeReceive` key. The `asset:stripe` icon and `#635BFF` colour come from `nodes/groups.py` (`payments` group) and `nodes/stripe/meta.json`. |
| `server/nodes/groups.py` | `payments` palette group. |
| `server/credentials/icons/stripe.svg` | Stripe credential-tile icon, served at `/api/schemas/credentials/stripe/icon`. |
-| `server/tests/services/test_events.py` | 27 framework tests (envelope, verifiers, polling/daemon lifecycle, WebhookSource). |
-| `server/tests/nodes/test_stripe_plugin.py` | 20 Stripe-specific tests (shape, filter, action passthrough, registrations). |
+| `server/tests/services/test_events.py` | Framework tests (envelope, verifiers, polling/daemon lifecycle, WebhookSource). |
+| `server/tests/nodes/test_stripe_plugin.py` | Stripe-specific tests (shape, filter, action passthrough, registrations). |
## Plugin classes
@@ -292,7 +310,7 @@ plus the per-line callback subscription via `ProcessService`'s
| `credential = StripeCredential` | Resolved by the framework before `build_command` is called. |
| `start()` (override) | `await ensure_stripe_cli()` then `super().start()`. Caches the resolved binary path so `build_command` (sync) can pick it up. |
| `build_command(secrets)` | Returns `<shlex.quote'd-binary> listen --forward-to … --print-secret`. The binary path is `shlex.quote`d so it round-trips through `ProcessService`'s POSIX-mode `shlex.split` unchanged. No `--api-key`: CLI reads its own config file. |
-| `has_credential()` (override) | Returns `is_logged_in()` — a filesystem check on `~/.config/stripe/config.toml`. Consulted by `DaemonEventSource.start` (the credential gate) and by `StripeReceiveNode._check_precondition` at deploy time (the demand-driven start; the status refresh is a passive probe since July 2026). |
+| `has_credential()` (override) | Returns `is_logged_in()` — a filesystem check on `~/.config/stripe/config.toml`. Consulted by `DaemonEventSource.start` (the credential gate) and by `StripeReceiveNode._check_precondition` when the trigger runs (the demand-driven start; only a canvas Run reaches it today, because deploy skips the node). The status refresh is a passive probe since July 2026. |
| `parse_line(stream, line)` | Invoked once per decoded stdout/stderr line via `ProcessService`'s `line_handler` callback. On `whsec_…` match, persists the secret via `auth_service.store_api_key("stripe_webhook_secret", …)`. The Stripe daemon doesn't emit workflow events itself — they arrive via the webhook receiver. |
### `StripeWebhookSource(WebhookSource)`
@@ -353,7 +371,7 @@ class StripeReceiveNode(WebhookTriggerNode):
Output = StripeReceiveOutput
async def _check_precondition(self) -> Optional[str]:
- # Refuse to register a waiter if the daemon isn't running.
+ # Start the listen daemon on demand; refuse if the CLI is not logged in.
...
def _extra_filter(self, params): # livemode filter on top of event-type
@@ -429,17 +447,18 @@ resources work without code changes.
The lifecycle factory `make_lifecycle_handlers(prefix="stripe",
source=…)` auto-generates `stripe_connect/disconnect/reconnect`
-from the source's `start/stop/restart` methods (user-initiated
-daemon lifecycle). The plugin-specific handlers wired into
-the modal's Connect button are `stripe_login` and `stripe_logout`:
+from the source's `start/stop/restart` methods (the daemon lifecycle;
+no button in the modal sends them). The plugin-specific handlers wired
+into the modal's **Login with Stripe** and **Disconnect** buttons are
+`stripe_login` and `stripe_logout`:
| Type | Handler | Purpose |
|---|---|---|
| `stripe_login` | `ensure_stripe_cli()` → `stripe login --non-interactive` (sync) → returns `{url, verification_code}` to the frontend; spawns background `_complete_login` task | **Modal "Login with Stripe" button** |
-| `stripe_logout` | stops daemon → `stripe logout --all` → `_mark_logged_out()` → `_broadcast_catalogue_updated()` | **Modal Disconnect button** |
-| `stripe_status` | returns `{logged_in, running, pid, webhook_secret_captured, connected = running ∧ logged_in}` | Optional read-only poll for diagnostics; the modal flips reactively from the catalogue refetch, not from this handler |
+| `stripe_logout` | stops daemon → `stripe logout --all` → `_mark_logged_out()` → `_broadcast_credential_event("credential.oauth.disconnected")` | **Modal Disconnect button** |
+| `stripe_status` | returns `{success, status: {type, running, pid, logged_in, connected}}`, where `connected = running and logged_in` | The modal's **Refresh** button sends it; the connection indicator still comes from the catalogue refetch, not from this reply |
| `stripe_trigger` | passes `["trigger", event]` to `run_cli_command` (after `ensure_stripe_cli`) | Synthetic test event |
-| `stripe_connect/disconnect/reconnect` | `source.start/stop/restart()` from the lifecycle factory | Daemon-only lifecycle, user-initiated |
+| `stripe_connect/disconnect/reconnect` | `source.start/stop/restart()` from the lifecycle factory | Daemon-only lifecycle. No button in the Credentials modal sends these |
Background `_complete_login(binary, next_step, pre_mtime)` flow:
@@ -501,12 +520,9 @@ is the LLM-facing manual for the `stripe_action` tool. It teaches:
credential automatically), surface Stripe error messages verbatim
to the user.
-The `payments_agent/` folder is a new skill bucket (the 12th,
-alongside `assistant`, `android_agent`, `autonomous`, `coding_agent`,
-`productivity_agent`, `rlm_agent`, `social_agent`, `task_agent`,
-`terminal`, `travel_agent`, `web_agent`). It opens up future
-payments integrations (PayPal CLI, Square, etc.) under the same
-agent type.
+The `payments_agent/` folder is the skill folder for payments,
+alongside the other folders under `server/skills/`. Other payments
+integrations (PayPal CLI, Square, etc.) would go in the same folder.
## Credentials Modal integration
@@ -582,8 +598,10 @@ secret lands.
## Status broadcasting — marker token + generic catalogue invalidation
-There is **no `stripe_status` broadcast type, no Zustand entry, no
-hardcoded case in `WebSocketContext.tsx`**. Stripe rides on two
+The frontend has **no Stripe-specific status handling**: no Zustand
+entry and no `stripe_status` case in `WebSocketContext.tsx`. (The
+backend does broadcast `stripe_status`, from `make_status_refresh`
+below, but no frontend code reads it.) The modal relies on two
existing generic mechanisms:
### 1. The catalogue's authoritative `stored` field
@@ -640,15 +658,18 @@ stripe-specific code anywhere on the frontend.**
### 3. `make_status_refresh` (passive status mirror)
-The plugin registers `make_status_refresh` so that on every
-WebSocket-client connect `source.status()` is mirrored into
-`broadcaster._status["stripe"]` for any consumers that read it
-directly. (The modal does not.) Since July 2026 the refresh **never
-starts the daemon** — a stored credential alone is not a reason to
-run `stripe listen`. The demand signals own the starts instead:
-`_complete_login` after a successful login, the user-initiated
-`stripe_connect` command, and `StripeReceiveNode._check_precondition`
-when a workflow with a Stripe trigger deploys.
+The plugin registers `make_status_refresh`. Service refresh callbacks
+run once, in a background task at startup (`_refresh_all_services`,
+scheduled from the `main.py` lifespan), not on each WebSocket connect.
+The callback mirrors `source.status()` (`type`, `running`, `pid`; no
+login state) into `broadcaster._status["stripe"]` and broadcasts it as
+`stripe_status`, which no frontend code handles. Since July 2026 the
+refresh **never starts the daemon** — a stored credential alone is not
+a reason to run `stripe listen`. The demand signals own the starts
+instead: `_complete_login` after a successful login, the
+`stripe_connect` command (no modal button sends it), and
+`StripeReceiveNode._check_precondition` when the trigger runs, which
+today means a canvas Run only.
### Frontend `connected` derivation (single generic line)
@@ -726,21 +747,24 @@ The Stripe panel lives in the Payments category (introduced
specifically for this plugin in the `payments` palette group). It
provides:
-- **Login with Stripe** button → fires `stripe_login`. The handler
- returns a `{url, verification_code}` pair; the modal opens the URL
- in a new tab and shows the verification code so the user can
- confirm the pairing on the Stripe Dashboard.
-- **Disconnect** button → fires `stripe_logout`, which stops the
- daemon and runs `stripe logout --all` to clear
+- **Login with Stripe** (shown until connected) → fires `stripe_login`.
+ The handler returns a `{url, verification_code}` pair; the modal
+ opens the URL in a new tab and shows the verification code so the
+ user can confirm the pairing on the Stripe Dashboard.
+- **Disconnect** (shown once connected) → fires `stripe_logout`, which
+ stops the daemon and runs `stripe logout --all` to clear
`~/.config/stripe/config.toml`.
-- **Status indicator** — derived from the catalogue's `config.stored`
- (`OAuthPanel.tsx:22`); the `stripe_status` WS handler is a read-only
- diagnostic poll.
-- **Reconnect** button — issues `stripe_reconnect` for stuck states.
-
-No webhook-secret input is needed — the daemon captures it
-automatically. The UI surfaces "secret captured ✓" once the value is
-persisted.
+- **Refresh** → sends `stripe_status` (the provider's `ws.status`).
+- **Status indicator** — `OAuthPanel` computes
+ `const connected = status ? !!status.connected : !!config.stored`.
+ Stripe declares no `status_hook`, so `status` is null and the
+ indicator follows the catalogue's `stored` flag.
+
+There is no Reconnect button: the `stripe_reconnect` handler exists, but
+nothing in the modal sends it. No webhook-secret input is needed, since
+the daemon captures the secret automatically, but the modal does not
+show whether it has been captured; the backend logs
+`webhook signing secret persisted` when it is.
## Operational notes
@@ -776,20 +800,25 @@ retried by the CLI the same way.
### Single global daemon
-One Stripe account per OpenCompany install. The daemon is
-singleton-global (`workflow_id="_stripe_global"`). Multi-account
+One Stripe account per OpenCompany install. The daemon is a single
+global process (`ProcessService` key `workflow_id="_stripe"`, the
+source's `workflow_namespace`). Multi-account
support is deferred to a future revision; the design holds — give
`StripeListenSource` a `__init__(account_id)` and key the singleton
by id.
### No auto-restart on crash
-If `stripe listen` exits unexpectedly, the framework surfaces the
-disconnected status and waits for the user to reconnect via the
-Credentials Modal. The per-line `parse_line` callback simply stops
-receiving lines when `ProcessService` reaps the process. There's no exponential-backoff respawn loop
-— that's deliberate to keep failing daemons visible rather than
-hidden behind silent retries.
+If `stripe listen` exits unexpectedly, nothing restarts it, and nothing
+reports it either. The source's `_started` flag is cleared only by
+`stop()`, so `stripe_status` still reports `running: true` and
+`StripeReceiveNode._check_precondition` skips the start; the modal's
+indicator follows the stored login marker, so Stripe still reads as
+connected. The per-line `parse_line` callback simply stops receiving
+lines when `ProcessService` reaps the process. To restart the daemon,
+click Disconnect and then Login with Stripe. There's no
+exponential-backoff respawn loop; that was deliberate, so a failing
+daemon is not hidden behind silent retries.
## Verification
@@ -799,42 +828,48 @@ End-to-end smoke (requires Stripe CLI installed and a Stripe account):
sends `{"type":"stripe_login"}` → reply contains `{url,
verification_code}`. Open the URL, confirm the code on Stripe
Dashboard, click Authorise. Within a few seconds the modal flips
- to "Connected" and `stripe_status` broadcasts
- `{logged_in: true, running: true, webhook_secret_captured: true}`.
+ to "Connected"; its **Refresh** button (`stripe_status`) then
+ reports `logged_in: true, running: true, connected: true`.
2. **Daemon start on login.** After login, confirm:
- - `process_service.list_processes("_stripe_global")` shows
+ - `process_service.list_processes("_stripe")` shows
`stripe-listen` running.
- Within ~3 s the stderr.log contains `whsec_…`.
- `auth_service.get_api_key("stripe_webhook_secret")` returns the
secret.
-3. **Synthetic event.** Build a workflow with `StripeReceiveNode`
- (filter: `charge.*`) → console node. Deploy. WS
- `{"type":"stripe_trigger","event":"charge.succeeded"}`. Console
- fires with `event_type="charge.succeeded"`, `event_id` matches the
- CLI's emitted event.
-4. **Filter rejection.** Set filter to `payment_intent.created`,
- retrigger `charge.succeeded` — node does NOT fire. Trigger
- `payment_intent.created` — it does.
+3. **Synthetic event (blocked by the Known gap).** Once `stripeReceive`
+ fires: build a workflow with `StripeReceiveNode` (filter: `charge.*`)
+ → console node, deploy it, and send WS
+ `{"type":"stripe_trigger","event":"charge.succeeded"}`. The console
+ should fire with `event_type="charge.succeeded"` and the CLI's
+ `event_id`. Today the forwarded event is verified and dispatched, but
+ no trigger fires.
+4. **Filter rejection (blocked by the Known gap).** Set filter to
+ `payment_intent.created`, retrigger `charge.succeeded` — node should
+ NOT fire. Trigger `payment_intent.created` — it should.
5. **Action node.** Configure `StripeActionNode` with
`command="customers create --email [email protected]"`. Run. Output
contains `id: cus_…`, `email: [email protected]`.
6. **AI tool surface.** From a chat agent, prompt
"create a Stripe test customer with email [email protected]"; the
- LLM emits a `stripeAction.run` tool call.
+ LLM calls the `stripe_action` tool.
7. **Signature failure.**
`curl -X POST -H "Stripe-Signature: t=0,v1=garbage" http://localhost:${PYTHON_BACKEND_PORT}/webhook/stripe -d '{}'`
- returns 400; no event dispatched.
+ returns 400 once the secret is captured (503 before that); no event
+ dispatched.
8. **Logout.** Credentials Modal → Disconnect. Confirm
- `process_service.list_processes("_stripe_global")` is empty AND
+ `process_service.list_processes("_stripe")` is empty AND
`~/.config/stripe/config.toml` no longer contains an `_api_key`
line.
-9. **Restart.** Restart OpenCompany. The status refresh does NOT
- auto-spawn the daemon; start it via the modal's Connect
- (`stripe_connect`) or by deploying a workflow with a Stripe trigger.
+9. **Restart.** Restart OpenCompany. The status refresh does not start
+ the daemon. The modal still shows Stripe as connected (the login
+ marker survives a restart), so it offers no Login button, and it has
+ no Connect button. The daemon starts again on a canvas Run of
+ `stripeReceive` (its precondition) or a `stripe_connect` WS message;
+ deploy skips Stripe triggers.
Unit tests live in [`server/tests/nodes/test_stripe_plugin.py`](../server/tests/nodes/test_stripe_plugin.py)
-(20 collected cases at time of writing) and [`server/tests/services/test_events.py`](../server/tests/services/test_events.py)
-(27 framework tests; counts via `pytest --collect-only -q`). Run via `pytest server/tests/services/test_events.py
+and [`server/tests/services/test_events.py`](../server/tests/services/test_events.py)
+(count them with `pytest --collect-only -q`). Run via `pytest server/tests/services/test_events.py
server/tests/nodes/test_stripe_plugin.py -v`.
## Related Docs
diff --git a/server/nodes/stripe/stripe_receive.py b/server/nodes/stripe/stripe_receive.py
index 4096c1f9..c5e0079e 100644
--- a/server/nodes/stripe/stripe_receive.py
+++ b/server/nodes/stripe/stripe_receive.py
@@ -70,11 +70,13 @@ class StripeReceiveNode(WebhookTriggerNode):
source = get_listen_source()
if source._started:
return None
- # Deploying a stripeReceive workflow IS the demand signal: start the
- # listen daemon here instead of relying on a credential-triggered
- # auto-start at boot (the status refresh is a passive probe now).
+ # Running this trigger is the demand signal: start the listen daemon
+ # here instead of relying on a credential-triggered auto-start at boot
+ # (the status refresh is a passive probe now). Only a canvas Run gets
+ # here: deploy skips stripeReceive, which is not in
+ # constants.WORKFLOW_TRIGGER_TYPES.
if not await source.has_credential():
- return "Stripe not connected. Add Stripe API key in Credentials and connect."
+ return "Stripe not connected. Log in with Stripe in Credentials."
result = await source.start()
if not (result or {}).get("success", False):
error = (result or {}).get("error") or "unknown error"
diff --git a/server/nodes/telegram/_refresh.py b/server/nodes/telegram/_refresh.py
index 13415683..14bb1fdf 100644
--- a/server/nodes/telegram/_refresh.py
+++ b/server/nodes/telegram/_refresh.py
@@ -5,8 +5,9 @@ The broadcaster no longer hardcodes a per-service refresh — instead
plugin packages register their own callback via
``status_broadcaster.register_service_refresh``.
-The callback runs once per WebSocket client connect (inside the
-``_refresh_all_services`` TaskGroup). Auth reads + owner restore
+The callback runs inside the ``_refresh_all_services`` TaskGroup, which
+runs once, in a background task at startup (not on each WebSocket client
+connect). Auth reads + owner restore
happen inside :class:`TelegramService`; this function just decides
whether to attempt an auto-reconnect and mirrors the resulting status
into the broadcaster cache.
diff --git a/server/services/events/lifecycle.py b/server/services/events/lifecycle.py
index 6cd51d38..70307076 100644
--- a/server/services/events/lifecycle.py
+++ b/server/services/events/lifecycle.py
@@ -81,10 +81,11 @@ def make_status_refresh(
The callback is a passive probe: it mirrors the source's status into
``broadcaster._status[status_key]`` and emits a ``broadcast_type``
- broadcast. It never starts the source — a stored credential alone is
- not a reason to run an optional daemon. Sources start on demand:
- user-initiated ``{prefix}_connect`` / login handlers, and trigger-node
- deploy prechecks (e.g. ``StripeReceiveNode._check_precondition``).
+ broadcast. Refresh callbacks run once, in a background task at startup.
+ It never starts the source — a stored credential alone is not a reason
+ to run an optional daemon. Sources start on demand: user-initiated
+ ``{prefix}_connect`` / login handlers, and trigger-node prechecks when
+ the trigger runs (e.g. ``StripeReceiveNode._check_precondition``).
"""
async def refresh(broadcaster: "StatusBroadcaster") -> None:
diff --git a/server/services/status_broadcaster.py b/server/services/status_broadcaster.py
index 2be8198c..feb38ca1 100644
--- a/server/services/status_broadcaster.py
+++ b/server/services/status_broadcaster.py
@@ -1337,8 +1337,9 @@ def register_service_refresh(callback: _ServiceRefreshCallback) -> None:
"""Register a per-service refresh callback.
Idempotent on re-import (same callable is a no-op). Each registered
- callback runs once per ``_refresh_all_services()`` cycle (i.e. on
- every WebSocket client connect).
+ callback runs once per ``_refresh_all_services()`` cycle, and the only
+ cycle is the background task the ``main.py`` lifespan schedules at
+ startup; client connects do not trigger one (see :meth:`connect`).
"""
_SERVICE_REFRESH_FANOUT.register(callback)
diff --git a/server/services/temporal/_refresh.py b/server/services/temporal/_refresh.py
index 47b52183..d4749580 100644
--- a/server/services/temporal/_refresh.py
+++ b/server/services/temporal/_refresh.py
@@ -1,9 +1,10 @@
-"""WS-connect status broadcast for the Temporal stack.
+"""Status-refresh broadcast for the Temporal stack.
-Registered via ``status_broadcaster.register_service_refresh`` so the
-frontend health indicator stays current — every WebSocket client
-connect triggers ``_refresh_all_services()`` which fans out to every
-registered callback. Same idiom :mod:`nodes.telegram._refresh` uses.
+Registered via ``status_broadcaster.register_service_refresh``, so it runs
+when ``_refresh_all_services()`` fans out to every registered callback.
+That happens once, in a background task the ``main.py`` lifespan
+schedules at startup; WebSocket client connects do not trigger it. Same
+idiom :mod:`nodes.telegram._refresh` uses.
Also exposes :func:`temporal_status_snapshot` — the single source of
truth for the ``{temporal}`` status shape consumed by both this refresh