Skip to content

feat(blocks): shared prompt and config blocks, with a sync command - #94

Draft
dhruva-vapi wants to merge 3 commits into
mainfrom
feat/blocks
Draft

dhruva-vapi wants to merge 3 commits into
mainfrom
feat/blocks

Conversation

@dhruva-vapi

Copy link
Copy Markdown
Contributor

Value

V.A.L.U.E. tier: small. One new engine feature with its guard rails, tests, an example and a guide.

  • Problem: teams repeat the same prompt paragraphs (safety wording, tone) and the same settings (voice, transcriber, squad overrides) across assistants, squads and orgs, and the copies drift. Nothing in the engine could hold one copy. YAML anchors only reach inside one file and pull expands them, merge keys (<<) aren't processed at all and get sent to the API as a field, and Liquid {% include %} renders as nothing on a call.
  • Who it affects: anyone running more than one assistant or more than one org from this repo, most of all a group of sites that share one set of prompts.

How it works

  1. Prompt blocks. A line that says only @include <name> in a system prompt is replaced by templates/blocks/<name>.md. It works in an assistant's Markdown body, a system message in a .yml assistant, and system messages in squad overrides. Nothing inside a block is interpreted, so {{variables}} and other Liquid reach Vapi as written.
  2. Config blocks. A $include: <name> key in any mapping pulls in templates/config/<name>.yml. The file's own keys win: mappings merge key by key, and anything else the file sets, lists included, replaces the block's value whole. Two blocks in one list that set the same field differently are refused, as is $include beside a merge key.
  3. An org's own blocks win. A name is looked up in resources/<org>/templates/ first, then templates/. An org block that includes its own name gets the shared one, so it can add to it instead of copying it. A missing block or a loop is an error, never empty text.
  4. Expanded in the loader. validate, push, PR checks, drift hashes and the audit all load through the same parser, so they all see the finished resource.
  5. Pull never writes a file that uses blocks. Pull rewrites a file when the dashboard matches it, when only the dashboard changed, under --force and under --resolve=theirs. Each of those would replace a marker with a copy of the block. It now leaves such a file as written and saves the dashboard version beside it as a .bkp. copy when the two differ, without moving the drift baseline, so the edit is still flagged at the next pull and push.
  6. npm run sync-blocks. A block edit changes many resources and none of their files. Push now records the block content each resource went up with in resources/<org>/.vapi-blocks.json (committed, like the state file). The command lists, across every org, the resources whose blocks changed since their last push. --apply runs apply per org for those files, so a resource edited in the dashboard is still refused by the drift check, and the command exits 1 naming what was left behind.
  7. Promotion and PR checks see a block edit. The promotion plan lists destination resources that need a push as sync, the promotion workflow runs on templates/**, and a shared block edit selects every PR check.
  8. validate warns about merge keys and Liquid include / render / layout tags, since both are dropped silently.

Guide: docs/guides/blocks.md. Example: examples/blocks/.

Verification

Nothing here was run against a live org. Every behaviour is covered by tests against fixtures or a local stub API.

Rule Test
Org block wins, then shared; an org block can extend the shared one tests/blocks.test.ts
Nesting, the loop error, the unknown-block error tests/blocks.test.ts
Liquid inside a block is untouched tests/blocks.test.ts
Config merge rule, and the refused cases tests/blocks.test.ts
Pull keeps the marker: in sync, dashboard ahead, --force, --resolve=theirs tests/blocks-pull.test.ts (all five fail with the guard removed)
Dry run lists affected resources across orgs; an org with its own block is not listed for a shared edit tests/blocks-sync.test.ts
--apply goes through apply → pull → push: the untouched resource is PATCHed, the dashboard-edited one is refused and stays listed tests/blocks-sync.test.ts
Promotion plans a block-only change as sync and deploys it tests/blocks-promotion.test.ts
A block-only change selects PR checks tests/blocks-promotion.test.ts
The example passes validate and the guide's snippets match its files tests/examples.test.ts

npm run build passes and npm test passes 620/620 (584 before).

Things to know

  • A resource that uses no blocks is loaded exactly as before: the expander returns the same object when it finds no marker.
  • The drift check only refuses when the checkout has a baseline for the resource. A fresh clone has none, with or without blocks.
  • While testing the sync path I found that an org with no credentials is re-bootstrapped on every push, which resets its baselines and so disables the drift check there. That predates this change. It's logged as entry 40 in improvements.md and not fixed here.
  • Promotion pushes with --resolve=ours, as it does for every file it promotes, so a sync entry overwrites a dashboard edit in the destination.

dhruva-vapi and others added 3 commits November 16, 2026 17:55
A system prompt can include a Markdown block with a line that says only
"@include <name>", and any mapping can include a YAML block with a
"$include" key, where the file's own keys win. Blocks are looked up in
resources/<org>/templates/ first, then in templates/ at the repository
root, so an org can replace or extend a shared block. The loader expands
them, so validate, push, PR checks and drift hashes all see the finished
resource. Liquid inside a block is passed through untouched.

Pull never writes a file that uses blocks. It used to rewrite a file
whenever the dashboard matched it, was ahead of it, or under --force and
--resolve=theirs, and each of those would replace a marker with a copy of
the block. It now leaves the file as written and saves the dashboard
version beside it when the two differ.

validate warns about YAML merge keys and Liquid include/render/layout tags,
which the engine and Vapi drop silently.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
A block edit changes what many resources send to Vapi without changing
their files, so nothing in git said which resources still ran old text.

Push now records the block content each resource went up with in
resources/<org>/.vapi-blocks.json. "npm run sync-blocks" lists, across
every org, the resources whose blocks changed since they were last pushed,
and with --apply deploys them through apply, so the drift check still
refuses a resource that was edited in the dashboard.

Promotion plans those resources as "sync" entries for the destination org,
the promotion workflow runs on templates/**, and a shared block edit
selects every PR check.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
Adds docs/guides/blocks.md and examples/blocks/, two clinics that share a
red-flags prompt block and a voice config block, one with its own version
of the block. The examples test now copies an example's templates/ folder,
so the example is validated and the guide's snippets are checked against
its files.

Also corrects two statements the feature depends on: YAML merge keys are
not processed by the engine, and an undefined Liquid variable is left in
the prompt as written, not replaced with an empty string.

Logs the pull behaviour this replaces as improvements entry 39, and a
drift-check gap found while testing, in orgs with no credentials, as
entry 40.

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
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