Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 7 additions & 7 deletions .agents/skills/add-block/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -177,7 +177,7 @@ When adding or changing an OAuth integration block:
`packages/sim-setup/src/capability-config.ts`. The CLI catalog is exhaustively typed and checked
against the runtime field list; do not infer secrecy from the field name.
4. If the canonical OAuth service declares `serviceAccountProviderId`, run
`bun run deployment-config:generate`; this regenerates the provider-ID facts in
`bun run generate:deployment-config`; this regenerates the provider-ID facts in
`packages/deployment-config/src/service-account-providers.generated.ts`. Never hand-edit that
generated map. Add `deploymentRequirement` policy in
`packages/deployment-config/src/service-account-metadata.ts` only when the service-account path
Expand Down Expand Up @@ -959,11 +959,11 @@ Verify it with `bun run check:block-successors`.
Adding a block on its own needs no **tool metadata** regeneration — a block references existing
tool IDs through `tools.access` and does not change any tool's shape.

But if the same change also adds, edits **or removes** a tool, run `bun run tool-metadata:generate` and commit the result, or CI fails on stale artifacts. That matters here because a block's `outputs` are authored to match its tools' outputs, and the UI reads those from the generated metadata, not the executable registry — an unregenerated tool change makes the block's outputs disagree with what the panel renders. See `.agents/skills/tool-registry-boundary/SKILL.md`.
But if the same change also adds, edits **or removes** a tool, run `bun run generate:tool-metadata` and commit the result, or CI fails on stale artifacts. That matters here because a block's `outputs` are authored to match its tools' outputs, and the UI reads those from the generated metadata, not the executable registry — an unregenerated tool change makes the block's outputs disagree with what the panel renders. See `.agents/skills/tool-registry-boundary/SKILL.md`.

A visible integration block does require the generated integration catalog and docs to be refreshed:
`bun run tool-metadata:generate` (only when a tool changed), `bun run scripts/generate-docs.ts`,
`bun run deployment-config:generate`, then `bun run check:audits`. Also run
`bun run generate:tool-metadata` (only when a tool changed), `bun run scripts/generate-docs.ts`,
`bun run generate:deployment-config`, then `bun run check:audits`. Also run
`bun run apps/sim/scripts/check-block-registry.ts origin/staging` (CI runs it outside `check:audits`). Commit the
full generator output. For what each check verifies, see the `validate-integration` skill →
Regenerate Derived Artifacts.
Expand All @@ -986,10 +986,10 @@ Regenerate Derived Artifacts.
- [ ] Outputs match tool outputs
- [ ] Block + meta registered in registry-maps.ts (`BLOCK_REGISTRY` / `BLOCK_META_REGISTRY`)
- [ ] If `sunset.replacedBy` changed: regenerated and committed the block successor map; `bun run check:block-successors` passes
- [ ] If any tool was added, changed or removed alongside the block: ran `bun run tool-metadata:generate` and committed the artifacts
- [ ] If any tool was added, changed or removed alongside the block: ran `bun run generate:tool-metadata` and committed the artifacts
- [ ] Ran `bun run scripts/generate-docs.ts`, reviewed the generated diff, and committed the integration catalog changes
- [ ] `bun run integration-catalog:check` passes
- [ ] `bun run docs:check` passes (CI gate — fails on any stale generated docs page)
- [ ] `bun run check:integration-catalog` passes
- [ ] `bun run check:docs` passes (CI gate — fails on any stale generated docs page)
- [ ] If icon missing: asked user to provide SVG
- [ ] If triggers exist: `triggers` config set, trigger subBlocks spread
- [ ] Optional/rarely-used fields set to `mode: 'advanced'`
Expand Down
18 changes: 9 additions & 9 deletions .agents/skills/add-integration/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -293,7 +293,7 @@ export const tools: Record<string, ExecutableToolConfig> = {
Then regenerate the generated tool metadata and commit it:

```bash
bun run tool-metadata:generate
bun run generate:tool-metadata
```

Client code reads `params`/`outputs` from these artifacts rather than importing
Expand Down Expand Up @@ -370,7 +370,7 @@ the OAuth service configuration, deployment availability, and the setup CLI.
infer secret fields from naming; the CLI mapping is exhaustively checked against the runtime
fields.
4. If the canonical OAuth service has `serviceAccountProviderId`, run
`bun run deployment-config:generate` to refresh
`bun run generate:deployment-config` to refresh
`packages/deployment-config/src/service-account-providers.generated.ts`; never hand-edit the
generated provider-ID map. In `packages/deployment-config/src/service-account-metadata.ts`, use:
- no `deploymentRequirement` when the service-account path works independently of OAuth client fields;
Expand All @@ -386,8 +386,8 @@ a resolvable capability must fail validation; an independent service account use

## Step 8: Generate and Validate the Catalog

Run `bun run tool-metadata:generate`, `bun run scripts/generate-docs.ts`,
`bun run deployment-config:generate`, then `bun run check:audits` (see the `validate-integration`
Run `bun run generate:tool-metadata`, `bun run scripts/generate-docs.ts`,
`bun run generate:deployment-config`, then `bun run check:audits` (see the `validate-integration`
skill → Regenerate Derived Artifacts for the full list and what each check verifies).

The docs generator creates `apps/docs/content/docs/integrations/{service}.mdx` — one page per service carrying the block's Actions and, if it has one, its Triggers section. Never hand-edit generated pages; the only editable region is the `{/* MANUAL-CONTENT */}` block (see `scripts/README.md`).
Expand Down Expand Up @@ -457,7 +457,7 @@ If creating V2 versions (API-aligned outputs):
- [ ] All optional outputs have `optional: true`
- [ ] Created `index.ts` barrel export
- [ ] Registered all tools in `tools/registry.ts`
- [ ] Ran `bun run tool-metadata:generate` and committed the regenerated artifacts
- [ ] Ran `bun run generate:tool-metadata` and committed the regenerated artifacts
- [ ] Classified every model-visible, opaque, Sim-durable, and internal-execution request field
- [ ] Added shared model-input projection or private provenance only where required; ordinary
external resource locators and control inputs retain their request semantics
Expand Down Expand Up @@ -530,15 +530,15 @@ If creating V2 versions (API-aligned outputs):

### Docs and deployment metadata
- [ ] Ran `bun run scripts/generate-docs.ts`
- [ ] Ran `bun run deployment-config:generate` for OAuth or service-account changes
- [ ] Ran `bun run generate:deployment-config` for OAuth or service-account changes
- [ ] Verified docs file created
- [ ] Wrote the `{/* MANUAL-CONTENT-START:intro */}` section under `<BlockInfoCard />` and confirmed it survives a regenerate
- [ ] Reviewed and committed the generated `packages/deployment-config/src/integrations.json` change
- [ ] `bun run integration-catalog:check` passes
- [ ] `bun run docs:check` passes — CI fails on stale generated docs, so commit the full generator
- [ ] `bun run check:integration-catalog` passes
- [ ] `bun run check:docs` passes — CI fails on stale generated docs, so commit the full generator
output, including catch-up regeneration for pages another PR left stale (never revert it as
"unrelated drift")
- [ ] `bun run deployment-config:check` passes
- [ ] `bun run check:deployment-config` passes

### Final Validation (Required)
- [ ] Read every tool file and cross-referenced inputs/outputs against the API docs
Expand Down
8 changes: 4 additions & 4 deletions .agents/skills/add-model/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ Use a precise WebFetch prompt: *"Extract for {model_id}: exact model id string,
| `reasoningEffort` | `openai/core.ts`, `azure-openai`, `xai`, `deepseek`, `groq`, `zai`, `kimi`, `cerebras`, `meta`, `litellm` (each `index.ts`) | Not read by anthropic/gemini (they use `thinking`) or by mistral, openrouter, fireworks, vertex — re-grep before assuming |
| `verbosity` | `openai/core.ts`, `azure-openai/index.ts` only | Dead elsewhere |
| `thinking` | `anthropic/core.ts`, `gemini/core.ts`; `deepseek`, `groq`, `zai`, `kimi` (each `index.ts`) read the resolved `thinkingLevel` | Dead elsewhere |
| `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`agent-stream-docs:check` fails without it); other families fall back to provider defaults |
| `thinking.streamed` | Docs generator + `getThinkingStreamVisibility` (`models.ts`); `anthropic/core.ts` uses `'summary'` to request `display: 'summarized'` on agent-events runs | **Mandatory on Anthropic-family thinking models** (`check:agent-stream-docs` fails without it); other families fall back to provider defaults |
| `nativeStructuredOutputs` | `anthropic/core.ts`, `bedrock/index.ts` (via `models.ts` `supportsNativeStructuredOutputs`, which reads the flag) | Dead elsewhere — fireworks/baseten/together/openrouter call their own provider-level `supportsNativeStructuredOutputs` that ignores the model flag (always on, always off, or OpenRouter API metadata) |
| `maxOutputTokens` | Read by UI + executor for token estimation | Always meaningful — set if provider documents a cap |
| `computerUse` | `providers/utils.ts` (`getComputerUseModels` → `computerUseModels` routing) | Set only on actual computer-use SKUs |
Expand Down Expand Up @@ -143,9 +143,9 @@ The Consumption Matrix (Step 2) tells you which capability *flags* are honored b

If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it appears in the autogenerated "Streamed thinking and tool calls" table on the Agent block docs page:

- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run agent-stream-docs:check` (CI) fails if the field is missing.
- **Anthropic-family (`anthropic`, `azure-anthropic`) thinking models MUST declare `capabilities.thinking.streamed`** (`'full' | 'summary' | 'none'`). Verify against Anthropic's current thinking-display and streaming docs: visible thinking returned by the API is summarized, including when Sim opts models whose default display is `omitted` into `display: 'summarized'` on agent-events runs, so current Claude thinking models use `'summary'`. Use `'full'` only if future official API docs explicitly guarantee raw thinking deltas. `bun run check:agent-stream-docs` (CI) fails if the field is missing.
- Other families usually omit the field and inherit the provider default in `getThinkingStreamVisibility` (Gemini/OpenAI → summaries; Bedrock/Meta → none; OpenAI-compatible vendors with documented reasoning fields → full deltas). Set it explicitly only when the model deviates from its family.
- After inserting the entry, run `bun run agent-stream-docs:generate` and commit the regenerated `apps/docs/content/docs/workflows/blocks/agent.mdx` — CI diffs it.
- After inserting the entry, run `bun run generate:agent-stream-docs` and commit the regenerated `apps/docs/content/docs/workflows/blocks/agent.mdx` — CI diffs it.
- Include the `streamed` value (with its source URL) in the verification report when set.

### Wrong family entirely?
Expand All @@ -157,7 +157,7 @@ If the entry has `capabilities.thinking` or `capabilities.reasoningEffort`, it a

```bash
bun run lint
bun run agent-stream-docs:generate # only when the entry has thinking/reasoningEffort
bun run generate:agent-stream-docs # only when the entry has thinking/reasoningEffort
```

Lint must pass before you report done — fix the entry you wrote, never delete it to make lint pass.
Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/add-tools/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -455,7 +455,7 @@ export const tools = {
3. Regenerate the tool metadata artifacts:

```bash
bun run tool-metadata:generate
bun run generate:tool-metadata
```

Client code reads a tool's `params`/`outputs` from generated metadata rather than
Expand Down Expand Up @@ -614,10 +614,10 @@ If creating V2 tools (API-aligned outputs), use `_v2` suffix:
- [ ] Types file has all interfaces
- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`)
- [ ] Tools registered in `tools/registry.ts`
- [ ] `bun run tool-metadata:generate` run and the regenerated artifacts committed
- [ ] `bun run generate:tool-metadata` run and the regenerated artifacts committed
- [ ] `bun run scripts/generate-docs.ts` run and the refreshed docs committed — the integration's
docs page is rendered from each tool's description, params, and outputs, and CI's
`bun run docs:check` fails on stale pages
`bun run check:docs` fails on stale pages
- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs
- [ ] Model, durable-storage, and internal-execution boundaries use the shared provenance mechanisms
only where a concrete Sim `{{...}}` resolution path requires them
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/add-trigger/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -539,5 +539,5 @@ registered `InternalToolConfig.operation`; a `directExecution` property fails
- [ ] Manually verify output keys match trigger `outputs` keys
- [ ] Trigger UI shows correctly in the block
- [ ] Ran `bun run scripts/generate-docs.ts` and committed the refreshed pages — trigger sections
render into the owning integration's docs page, and CI's `bun run docs:check` fails on stale
render into the owning integration's docs page, and CI's `bun run check:docs` fails on stale
pages
Loading
Loading