Skip to content

Commit 99fa527

Browse files
docs(skills): teach connector_action input as an evaluated value slot and the openapi include allowlist (#28012)
<!-- claude-projects-attribution: {"github_login":"os-elon-musk"} --> _Requested by **Elon** · [project thread](https://claude.ai/code/project/chan_01WedDzV26nniwxv7jC88B9D?thread=cmsg_01WedDzV26nniwxv7jC88B9DQaSHbveqsCnSo8ERWam3N6)_ domain:skills#2 · os-elon-musk · session_016WV4cwkH2Pj7G4DWB8WTaf Fixes #27982 The family card folds #27987 (closed by triage as a duplicate of this card), so its two locations are fixed here too. ## What changes The automation skill re-teaches two things from the code, at the five locations the card lists: 1. `skills/objectstack-automation/SKILL.md`, the `connector_action` row: `connectorConfig.input` is a value-slot map like `subflow` `input`; `os validate` does not judge it yet, so a malformed envelope fails at run time. (Was: "sent as written — no CEL or `{{ }}` in it".) 2. `references/integration-recipes.md`, the "Holds on every recipe" input bullet: a top-level CEL envelope is evaluated, any other value is sent as written (`{…}` and `{{ }}` are literal text), with one example that reads a record field into the input (`input: { customer: { dialect: 'cel', source: 'record.stripe_id' } }`), and the same registration-gap note. 3. `references/integration-recipes.md`, recipe 1's closing sentence: `providerConfig.include` allowlists operation keys as the `mcp` provider's does (absent = every operation; a non-array or unknown entry is fatal); trimming still keeps the package small. (Was: "The `openapi` provider has no `include` key — the trimmed document is the allowlist".) 4. and 5. `evals/integrations-declared.json` case 1 `expected_output`: the trimmed document stays, with `include` named as the alternative allowlist; the per-contract payload now reads the record through a CEL envelope, so the "Three gaps" become two. Assertions are unchanged. Plus a `@objectstack/skills` patch changeset and one ratchet row (below). ## Why - **Input slot.** `packages/services/service-automation/src/builtin/connector-nodes.ts` (after PR #27980) calls `resolveValueSlotMap(engine, cfg.input, variables, 'input', context)` before dispatch. `builtin/value-slot-map.ts` lists `connector_action` `connectorConfig.input` beside `subflow`/`map` `input`, `script` `inputs`, `screen` `defaults` and `notify` `templateData`: an envelope-shaped top-level value is evaluated, a malformed one throws, and every other value is a literal copy. - **Registration gap.** #27968 measured that a malformed CEL envelope, a template envelope and a bare `'{rec.id}'` all register under `connectorConfig.input`, because the spec ledger `FLOW_NODE_EXPRESSION_PATHS` only addresses `node.config`. The texts therefore do not tell the author that a `{…}` token there is refused (as Valid-but-silently-wrong item 1 says for the ledger slots); they say it is literal text. The skill names no card number, as elsewhere in the skills tree. - **`include`.** `packages/connectors/connector-openapi/src/openapi-provider.ts:54-84` declares `providerConfig.include` with "the same allowlist meaning as the `mcp` provider's `include`"; `resolveIncludeList` returns `undefined` when absent and throws on a non-array or a non-string entry; `:293-298` refuses an entry the document does not carry. ## Token budget - `SKILL.md`: 6457 / 6457, no row change. Paid in the same file by cutting the row's restatement "(a `connectors:` entry with a `provider`, …)" of § *Integrations are declared, not coded*. - `references/integration-recipes.md`: 2204 → 2236 (+32). Three same-file restatements cut first: recipe 1's comment "3.x only, … every `$ref` dereferenced offline" (the paragraph under the recipe says it), recipe 5's ", written from the vendor's docs" (its heading says it), the OAuth bullet's "four variants and" (the Holds `auth` bullet lists them). The remainder moves the row on the standing path: maintainer ruling 2026-10-27 「A:先削重复,余额按实测提高」, made the gate-recognised path by ruling record 6513306068 on #27847. Arithmetic is in the row comment. - The eval file is measured, not ratcheted (6513306068); `ui/scripts/check-skill-eval-tokens.mjs` is green (every `must_contain` token taught by its bundle). ## Verification Head `1f28d891`, base `origin/main` `8f41b2d1`. `node scripts/pm/dispatch-gates.mjs --commands` derives 64 families; reconciled with `--ran`: **60 exit 0, 4 NOT MEASURED, 0 red, 0 unrun.** - Green, among them: `check-skills-token-ratchet.mjs` (and `--self-test`), `check:skill-docs`, `check:skill-refs`, `check:skill-compatibility`, `check:skill-frame-sync`, `check:skill-identifier-liveness`, `check:pm-skill-id-lint`, `check-changeset-no-major`, `check-empty-changeset`, `check-closing-keyword-parity`, `check:doc-formula-expressions` (after `turbo run build --filter=@objectstack/formula --filter=@objectstack/lint`). - Also run by hand: `node ui/scripts/check-skill-eval-tokens.mjs` exit 0; `integrations-declared.json` parses, its assertions are unchanged, and the new `expected_output` holds every `must_contain` token and no `must_not_contain` token. - NOT MEASURED (exit 3, prerequisite: a whole-tree `dist`): `check:dts-closure`, `check:dual-build-cjs-loads`, `check:lean-entry-closure`, `check:sourcemap-no-sources-content`. This diff touches no package source or build output; CI sweeps them. Clause-②: no Metadata-protocol: none ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. (not touched) - [x] 2. Every name I added uses the casing for its kind. (no names added) - [x] 3. No formatter ran; `pnpm lint` passes. (no lint-covered source changed) - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: n/a. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English (the 维护者速读 block is the repo's Chinese channel). ## Acceptance notes - None beyond the card. The registration half stays on #27968. ## 维护者速读 - 改了什么:自动化技能三个文件五处文字:连接器节点的 `input` 改教为会求值的值槽,`openapi` 提供方改教为有 `include` 白名单;评测用例 1 随之更正。 - 为什么改:执行器已按值槽求值 `input`(#27980),`include` 也已上线(#27387),旧文字会让 AI 把按记录取值当成平台缺口、把裁剪文档当成唯一白名单。 - 风险与回滚:只改说明文字与评测期望,不动代码;回滚即还原本 PR。 - 先看:`skills/objectstack-automation/references/integration-recipes.md` 的 Holds 第二条与配方 1 末句。 - 两分钟验证:`node scripts/check-skills-token-ratchet.mjs` 与 `node ui/scripts/check-skill-eval-tokens.mjs` 均为 0。 - 需要你做的:contract review owed(fable),席位复核 PASS 之前不求批。 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_016WV4cwkH2Pj7G4DWB8WTaf Co-authored-by: Claude <noreply@anthropic.com>
1 parent ab75996 commit 99fa527

5 files changed

Lines changed: 43 additions & 10 deletions

File tree

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
---
2+
'@objectstack/skills': patch
3+
---
4+
5+
docs(skills): the automation skill teaches `connector_action`'s `connectorConfig.input` as an evaluated value slot, and the `openapi` provider's `providerConfig.include`
6+
7+
Clause-②: no
8+
Metadata-protocol: none
9+
10+
- **`connectorConfig.input` is a value-slot map**, like `subflow` `input`: a top-level CEL envelope is evaluated in the run's scope, so a per-record payload (`{ dialect: 'cel', source: 'record.stripe_id' }`) is a declarative dispatch now. Any other value is sent as written; a `{…}` or `{{ }}` in it is literal text. The skill says plainly that `os validate` does not judge this slot yet, so a malformed envelope fails the step at run time.
11+
- **`providerConfig.include` exists on the `openapi` provider**, with the `mcp` provider's allowlist meaning: absent exposes every operation, and a non-array or an unknown entry is a fatal configuration fault. Trimming the document is still taught, as the way to keep the package small, not as the only allowlist.
12+
- The `integrations-declared` eval's first case follows: it no longer grades either stale limit.

‎scripts/check-skills-token-ratchet.mjs‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -868,7 +868,25 @@ export const CEILINGS = new Map([
868868
// request body or response, so the derived schema silently loses it):
869869
// 8705 -> 8814 bytes, 2177 -> 2204.
870870
// ceil($(wc -c < skills/objectstack-automation/references/integration-recipes.md) / 4) == ceil(8814 / 4)
871-
['skills/objectstack-automation/references/integration-recipes.md', 2204],
871+
// 8814 -> 8942 (card #27982): the "Holds on every recipe" input bullet
872+
// re-teaches `connectorConfig.input` as an evaluated value-slot map, with a
873+
// record-field example and the not-yet-judged-at-`os validate` note, and
874+
// recipe 1's closing sentence teaches `providerConfig.include` (the `mcp`
875+
// allowlist meaning, a non-array or unknown entry fatal) instead of denying
876+
// the key. Paid down first, three restatements each with a surviving home:
877+
// recipe 1's comment "3.x only, … every `$ref` dereferenced offline" (the
878+
// same comment says "OpenAPI 3.x document"; the paragraph under the recipe
879+
// says to dereference every `$ref` offline), recipe 5's comment ", written
880+
// from the vendor's docs" (its heading says write the document by hand),
881+
// and the OAuth bullet's "four variants and" (the Holds `auth` bullet lists
882+
// them). Arithmetic: 8814 -> 8942 (+128 net) -> ceil(8942 / 4) = 2236;
883+
// headroom was 0 tokens, so the ceiling moves +32, pinned AT the
884+
// measurement. Maintainer ruling 2026-10-27 on the seat's decision card
885+
// 「skills 修复卡的教学和 eval 都撞 token 天花板,怎么付?」, tap A verbatim
886+
// and untranslated: 「A:先削重复,余额按实测提高」 — the standing path of
887+
// ruling record 6513306068 on #27847.
888+
// ceil($(wc -c < skills/objectstack-automation/references/integration-recipes.md) / 4) == ceil(8942 / 4)
889+
['skills/objectstack-automation/references/integration-recipes.md', 2236],
872890
// 5569 -> 5587 (card #26298, audit #26184 row A2): the approval config table
873891
// gains `excludeSubmitter` (refused beside `onEmptyApprovers: 'auto_approve'`),
874892
// +105 tokens. Paid down first: Best Practices 1 and 4 restated the Branching

‎skills/objectstack-automation/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ Flows are built from **built-in node types** (plugins register more, e.g.
8585
|:-----|:--------|
8686
| `http` | Call an external HTTP API — always set `timeoutMs` (unset = no timeout). `url` and `headers` are served as written with the definition to every member who can read flows — only `signingSecret` and a start node's `secret` are withheld — so never a credential there: a credential means a declared connector called via `connector_action` |
8787
| `notify` | Send a notification through the messaging service (inbox by default) |
88-
| `connector_action` | Dispatch an action of a declared connector (a `connectors:` entry with a `provider`, § *Integrations are declared, not coded*) or a plugin's. `connectorConfig.input` is sent as written — no CEL or `{{ }}` in it |
88+
| `connector_action` | Dispatch an action of a declared connector (§ *Integrations are declared, not coded*) or a plugin's. `connectorConfig.input` is a value-slot map like `subflow` `input`; `os validate` does not judge it yet, so a malformed envelope fails at run time |
8989
| `script` | Call a **registered** function named by `config.function` (see *Valid-but-silently-wrong* #3) |
9090
| `screen` | Display a UI form to the user (screen flows only). `config.fields[]`: `{ name, label, type, required, options, defaultValue }`, `type` an open widget hint; `'file'` renders the upload widget and resumes with the `sys_file` id bound to `name` — a later `create_record` / `update_record` writes it into a `file` field, which claims the file: collect first, write after the last screen. `'record_link'` (never `'record'`, an object field type) takes no input — it shows the `reference` record whose id `defaultValue` evaluates to, by display name, as a link to its record page: the result screen of a flow that created records, `{ name: 'account_link', type: 'record_link', reference: 'crm_account', defaultValue: { dialect: 'cel', source: 'account.id' } }` over a `create_record` `outputVariable: 'account'`. Both keys required; `required` / `options` / `placeholder` / `min` / `max` refused; a resume value under its name refused (`400 INVALID_SCREEN_INPUT`). A completed `end` `message` is refused and a markdown link in a screen `description` renders literally. Next / Submit and "Step N of M" are not authored: the engine reads the graph when the screen pauses and serves `progress` (`nextScreen: 'none' | 'possible' | 'certain'`; `step` / `stepCount` only when every path agrees), which alone labels the button and draws the counter. A `decision`, `fault` edge, loop back, non-screen pause (`approval`, `wait`) or `subflow` after a screen answers `possible` — "Next", no count. `progress` in a node `config` is refused; never hand-roll a button label or step counter into `fields` |
9191

‎skills/objectstack-automation/evals/integrations-declared.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
{
55
"id": 1,
66
"prompt": "Our contract-lifecycle app (objects `contract`, `crm_account`) needs DocuSign: send a contract out for signature, read an envelope's status, and reflect status changes on the record. DocuSign publishes a 4.7 MB Swagger 2.0 document with several hundred operations, authenticates with OAuth 2.0, and its Connect webhooks sign posts with their own HMAC header. Propose what to build and where.",
7-
"expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a trimmed, packaged OpenAPI 3.x document carrying only the three operations (create envelope, get envelope, list status changes), converted offline from the Swagger 2.0 document — the `openapi` provider has no `include` key, so the trimmed document is the allowlist. Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. Three gaps are named plainly, each blocked on its platform card: the declarative `auth` union has no `oauth2`, so the integration is marked **blocked** on outbound OAuth (no short-lived token parked behind a `bearer` `credentialRef`); DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified; `connectorConfig.input` is sent as written, so a per-contract payload waits on the platform too. The answer proposes no `registerConnector` code and no plugin.",
7+
"expected_output": "A declarative instance inside the app, not a platform plugin and not a `connector-esign` family: `defineConnector` with `provider: 'openapi'`, whose `providerConfig.spec` is a packaged OpenAPI 3.x document converted offline from the Swagger 2.0 document and trimmed to the three operations (create envelope, get envelope, list status changes) (or `providerConfig.include` names those three operation keys, the `mcp` provider's allowlist meaning, where a non-array or unknown entry is fatal; trimming still keeps the package small). Fields on `contract` (`envelope_id`, `signature_status`). Flows dispatch `connector_action`; the callback is an `api` flow with a start-node `secretRef`. Two gaps are named plainly, each blocked on its platform card: the declarative `auth` union has no `oauth2`, so the integration is marked **blocked** on outbound OAuth (no short-lived token parked behind a `bearer` `credentialRef`); DocuSign Connect signs its own header, which the `api` door does not verify, so status is polled until vendor schemes are verified. `connectorConfig.input` is a value slot: the per-contract payload reads the record through a CEL envelope (`envelopeId: { dialect: 'cel', source: 'record.envelope_id' }`). The answer proposes no `registerConnector` code and no plugin.",
88
"files": [],
99
"assertions": {
1010
"must_contain": ["defineConnector", "provider: 'openapi'", "credentialRef", "connector_action", "type: 'api'", "secretRef", "Swagger 2.0", "blocked"],

‎skills/objectstack-automation/references/integration-recipes.md‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -15,9 +15,10 @@ deployment and to the sender. Scaffolded apps list the three executors in
1515

1616
- Actions come from the upstream (an OpenAPI `operationId`, an MCP tool name,
1717
the `rest` provider's single `request`) — authored on the entry, they are refused.
18-
- `connectorConfig.input` is sent **as written** — no CEL envelope, no `{{ }}`
19-
hole — so a per-record payload (an id from `record.*`) is not a declarative
20-
dispatch today: a gap to name, not a plugin to write.
18+
- `connectorConfig.input` is a value-slot map like `subflow` `input`: a top-level
19+
CEL envelope is evaluated, any other value sent as written (`{…}`, `{{ }}` are
20+
literal text) — `input: { customer: { dialect: 'cel', source: 'record.stripe_id' } }`.
21+
`os validate` does not judge it yet, so a malformed envelope fails at run time.
2122
- The answer lands as `<nodeId>.<key>` (`rest` / `openapi`: `{ status, ok, body }`;
2223
`mcp`: `{ ok, content, structuredContent? }`), read from a later node's value
2324
slot: `{ dialect: 'cel', source: 'bal.body.available[0].amount' }`.
@@ -31,7 +32,7 @@ deployment and to the sender. Scaffolded apps list the three executors in
3132

3233
```ts
3334
// Trim the vendor's OpenAPI 3.x document to the operations the app calls and ship
34-
// it in the package: 3.x only, package-relative, every `$ref` dereferenced offline.
35+
// it in the package, package-relative.
3536
export const StripeConnector = defineConnector({
3637
name: 'stripe', label: 'Stripe', type: 'api', provider: 'openapi',
3738
providerConfig: { spec: './src/connectors/stripe.trimmed.json' }, // holds `GetBalance` alone
@@ -60,7 +61,9 @@ export const StripeBalanceSweep = defineFlow({
6061
`requires: ['automation', 'triggers', 'job']`. Convert Swagger 2.0 or YAML and
6162
dereference every `$ref` offline, in-document ones included: the loader skips a
6263
`$ref` parameter, request body or response, and the derived input/output schema
63-
silently loses it. The `openapi` provider has no `include` key — the trimmed document is the allowlist.
64+
silently loses it. `providerConfig.include` allowlists operation keys as the
65+
`mcp` provider's does (absent = every operation; a non-array or unknown entry is
66+
fatal); trimming still keeps the package small.
6467

6568
## 2 · Remote MCP server, static header — GitHub
6669

@@ -124,7 +127,7 @@ name the gap and poll its status (recipe 1's shape) until vendor schemes verify.
124127
```ts
125128
export const LegacyErp = defineConnector({
126129
name: 'legacy_erp', label: 'Legacy ERP', type: 'api', provider: 'openapi',
127-
providerConfig: { spec: { // inline OpenAPI 3.x, written from the vendor's docs
130+
providerConfig: { spec: { // inline OpenAPI 3.x
128131
openapi: '3.0.3', info: { title: 'Legacy ERP', version: '1' },
129132
servers: [{ url: 'https://erp.example.com' }],
130133
paths: { '/v2/open-orders': { get: { operationId: 'listOpenOrders',
@@ -141,7 +144,7 @@ palette and to agents; `provider: 'rest'` instead when the path is per call.
141144
## Not yet — declare the rest, mark the integration blocked, write no plugin
142145

143146
- **OAuth-protected vendor** (DocuSign, Salesforce, Google): the declarative `auth`
144-
union has four variants and no `oauth2`; the authorization-code / refresh
147+
union has no `oauth2`; the authorization-code / refresh
145148
lifecycle is not delivered in the open tier. Do not park a short-lived access
146149
token behind a `bearer` ref. Declare the connector, fields and flows, mark the
147150
integration **blocked** on the platform's outbound-OAuth card, and say so.

0 commit comments

Comments
 (0)