Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
docs(credentials): document placeholder secrets and the Stripe trigger gap
trohitge057a99a5905
diff --git a/docs-internal/SETUP.md b/docs-internal/SETUP.mdindex 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` onWindows) 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)**: aregistry 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 testingdiff --git a/docs-internal/TEMPORAL_ARCHITECTURE.md b/docs-internal/TEMPORAL_ARCHITECTURE.mdindex 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.mdindex 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 errorbanner when `SECRET_KEY` / `JWT_SECRET_KEY` / `API_KEY_ENCRYPTION_KEY` stillcarry 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.mdindex 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 AbstractionFor 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.```pythonclass 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.mdindex 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 bodynever runs and a download flag there would work on the canvas and silently donothing once deployed. `whatsappBusinessMedia` exists for the same reason anddocuments it in its own module docstring.@@ -246,10 +246,12 @@ walker touches. [`nodes/__init__.py`](../server/nodes/__init__.py) swallowsimport errors during discovery, so a failing library import would make thewhole 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.## Testingdiff --git a/docs-internal/node-logic-flows/stripe/stripeReceive.md b/docs-internal/node-logic-flows/stripe/stripeReceive.mdindex 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 TDS --> 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 onlyP[_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 listensource 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 503with `Retry-After: 5`; missing header, missing `t=` / `v1=`, or nomatching `v1=` candidate -> HTTP 400. Multiple `v1=` values are accepted@@ -106,11 +106,20 @@ flowchart TDdispatches 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'sstderr (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 itsinternal 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 a503 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.## Relateddiff --git a/docs-internal/plugin_system.md b/docs-internal/plugin_system.mdindex 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-statusrefresh callbacks), `node_output_schemas.register_output_schema`(output schemas).- Wave 11.I — Eight more plugin domains migrated to thediff --git a/docs-internal/speech_provider_rfc.md b/docs-internal/speech_provider_rfc.mdindex 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 resultdiff --git a/docs-internal/stripe_service.md b/docs-internal/stripe_service.mdindex 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, CLIinvocation) 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_logouthandle_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 = StripeReceiveOutputasync 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 verbatimto 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 twoexisting 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 (introducedspecifically for this plugin in the `payments` palette group). Itprovides:-- **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-accountsupport is deferred to a future revision; the design holds — give`StripeListenSource` a `__init__(account_id)` and key the singletonby 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 StripeDashboard, 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 thesecret.-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. Outputcontains `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.pyserver/tests/nodes/test_stripe_plugin.py -v`.## Related Docsdiff --git a/server/nodes/stripe/stripe_receive.py b/server/nodes/stripe/stripe_receive.pyindex 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.pyindex 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 — insteadplugin 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 restorehappen inside :class:`TelegramService`; this function just decideswhether to attempt an auto-reconnect and mirrors the resulting statusinto the broadcaster cache.diff --git a/server/services/events/lifecycle.py b/server/services/events/lifecycle.pyindex 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.pyindex 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.pyindex 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 oftruth for the ``{temporal}`` status shape consumed by both this refresh