Skip to content

Optional fields in a flow piece's credential declaration - #484

Merged
wmobley merged 1 commit into
developfrom
feat/optional-secret-fields
Nov 20, 2026
Merged

wmobley merged 1 commit into
developfrom
feat/optional-secret-fields

Conversation

@wmobley

@wmobley wmobley commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

Why

A piece declares the runner's stored credentials it needs (runtime_json.secrets). Every field in env was required, so Formulation (draft-lexicon) refused any run whose model_server credential lacked an embedding address, even with keyword grounding, which never embeds.

Change

  • A secret entry may carry "optional": ["<field>", ...]. Each item must be a value of that entry's env (validated: list of strings, field-name pattern, subset of env, no duplicates; empty is dropped). Declarations without it behave exactly as before.
  • Submit and plan readiness require only the required fields. A field is required if any step requires it. A secret whose fields are all optional must still be stored.
  • The step fetch omits an optional field the stored secret lacks, and still returns 409 SECRET_FIELDS_INCOMPLETE for a missing required field. Every other fetch gate is unchanged: caller, rate limit, active run, HMAC, one use, trust re-check, version binding.
  • The EM passes optional through, and the credential dialog shows it ("optional embedding_base_url"). docs/api.md documents the schema.

Security review

No high or medium findings. Checked: optional can only make a step receive less, never another field or secret. A forged or changed optional fails the declaration check (STEP_SECRET_DECLARATION_CHANGED). Old plans and run rows stay all-required. Rolling back fails closed. An omitted field is not refilled from the container environment, because the piece reads only its inputs and the library refuses an OpenAI-compatible backend without an address. Low follow-ups, not in this PR:

  • sort optional when normalising;
  • show the credential fields (optional ones marked) in the ready state of the run dialog, not only when blocked;
  • record which optional fields were sent (names only) in the step_secret.issued provenance.

Tests

  • Adapter: 1522 passed; 4 pre-existing local test_demo_api failures (git-ignored .env). New tests in test_step_secrets.py: validation, required vs optional, all-optional, submit, fetch present/absent, required field lost after submit.
  • UI src/pages/modeling/thread: 336 passed; EM flowExecution.test.ts: 91 passed.

After deploy

Register draft-lexicon r4 from the library (wmobley/Semantic-Sensemaking feat/setting-schemas, ce4dc5d), which declares embedding_base_url optional, and register Formulation again on it. An adapter without this change rejects the r4 declaration.

🤖 Generated with Claude Code

A secret declaration may list "optional" fields, each a value of its env map.
Plan and submit no longer require them, the step fetch returns an optional
field only when the stored secret has it, and the plan lists them so the UI
can show them as optional. Declarations without it behave as before.
@vercel

vercel Bot commented Nov 20, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
monorepo Ready Ready Preview Nov 20, 2026 9:08pm UTC

@wmobley
wmobley merged commit 65ed7d0 into develop Nov 20, 2026
44 checks passed

This branch was successfully deployed

1 active deployment
Preview — b5c55fb6 Deployed Nov 20, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant