feat(granola): complete API coverage, note triggers, and connector validation (#6880)

* feat(granola): complete API coverage, note triggers, and validation fixes

Granola's public API exposes nine endpoints; Sim implemented three. Adds the
remaining six and wires the new programmatic webhook-endpoint lifecycle into a
managed trigger.

Tools (6 new, 9 total):
- get_transcript, list_audit_events
- create/list/update/delete_webhook_endpoint

Triggers: note.generated, note.edited, note.access_granted, plus an all-events
trigger. The provider handler registers the Granola endpoint on deploy and
deletes it on undeploy, scoped to the trigger's own event names, and verifies
every delivery with the Standard Webhooks HMAC-SHA256 signature Granola returns
on creation. event_id is the idempotency key, which Granola reuses across
retries.

Validation fixes to the shipped tools:
- get_note dropped speaker.attribution ("me"/"them"); now surfaced
- a 413 on get_note now explains that the transcript is too large inline and
  points at get_transcript, instead of surfacing a bare status code
- note IDs are URL-encoded rather than interpolated raw
- base URL, auth headers, and status-aware error handling are shared runtime
  helpers; params/outputs stay literal per file so the docs generator still
  reads them

Tests cover signature verification (including replay and body-tamper
rejection), event matching, subscription create/delete, and the block/tool
contract — plus a guard that ids shared between the tool and trigger surfaces
seed the same default, since block state is keyed by id and last-wins.

The knowledge-base connector was validated against the spec and needed no
changes.

* fix(granola): correct array output schemas, listing-truncation signal, and docs

Findings from validation passes over the tools, trigger, and connector.

Tools — array outputs were declared as `type: 'json'` with `properties`, which
describes an object, not an array. Agents and the output picker therefore saw
`notes.title` instead of `notes[i].title`. All 15 array outputs (including the
pre-existing three tools) now use `type: 'array'` with `items`, matching the
2000+ other tool files. The audit event `data` field stays `json`; it is
genuinely free-form per the spec.

Connector — `hasMore` was ANDed with the cursor, so a `hasMore: true` response
with no cursor was reported as a complete listing. The sync engine treats
exactly that shape as truncated and sets `listingTruncated` to block deletion
reconciliation; masking it meant a partial first page could be taken for the
whole corpus and reconciliation would hard-delete every note past it. Granola
would have to violate its own contract to emit that shape, but the engine
already handles it and the connector was hiding the signal. Also aligns
mimeType with the `.txt`/text-plain bytes the engine actually writes (it was
the only connector of 101 claiming text/markdown).

Trigger — the setup instructions named a Granola settings path that does not
exist; the help center says Settings > Connectors > API keys in the desktop app.

Both list parsers now split commas inside array entries, so an array-wrapped
free-text value cannot be sent as one malformed identifier.

Block — `id`, `events`, and `hasMore` are produced by several operations but
their descriptions named only one, unlike `folders` which already documented
both meanings.

Adds connector tests pinning all four listingCapped quadrants and the
truncation signal, and tool tests for the list parser and the PATCH body's
per-field "omit means unchanged" semantics.

* fix(granola): clean up webhook endpoints created by a failed registration

Raised independently by both reviewers. The registration service only rolls
external state back when createSubscription *returns* — its rollback is guarded
on `preparedProviderConfig`, so a handler that throws is assumed to have left
nothing behind. Granola's handler broke that contract: when Granola accepted the
POST but the success body was missing `id` or `signing_secret` (including a body
that failed to parse and became `{}`), it threw with the endpoint already live.

Nothing then recorded an external id, so undeploy could not remove it, and
Granola kept delivering to a callback whose signature could never be verified —
duplicating on every deploy retry.

The handler now removes what it created before rethrowing, matching the pattern
grain's multi-hook create already uses. It deletes by id when Granola returned
one, and otherwise recovers the endpoint by matching the callback URL, which
also covers a connection that fails after the request reached Granola.
Endpoints whose URL was redacted to its origin are never matched — that
comparison could delete another workflow's endpoint on the same host. Cleanup is
best effort and never masks the original failure. A non-2xx is left alone, since
no endpoint was created.

Also folds the delete call shared with deleteSubscription into one helper.

* fix(granola): never recover an orphaned endpoint by callback URL

The previous commit's URL-based recovery was unsafe. A redeploy reuses the live
registration's `path`, so the candidate and the currently serving endpoint share
a callback URL — listing by that URL and deleting every match would remove the
live deployment's endpoint and silently stop a working trigger, which is worse
than the leak it was trying to prevent.

Cleanup is now keyed solely on the id Granola returned. When the success body
carries no id there is no way to tell the candidate's endpoint from the live
one, so it is left in place: a leaked endpoint produces unverifiable deliveries
that Granola disables on its own, whereas deleting the wrong one takes down live
traffic with no signal.

The 2xx-missing-signing-secret case this originally fixed still cleans up, since
that response does carry an id.

Adds a test asserting no lookup or delete is attempted when the response has no
id, so URL matching cannot be reintroduced unnoticed.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/granola.mdx

@@ -0,0 +1,161 @@
+/**
+ * Guards the block/tool contract: the operation dropdown, `tools.access`, the tool params, and the
+ * declared inputs all describe the same set of operations, and drift in any one of them fails here.
+ *
+ * Also guards the seeded-default rule for duplicate subBlock ids — block state is keyed by id and
+ * the last definition in file order wins, so ids shared between the tool surface and trigger mode
+ * (`apiKey`, `scopes`, `folderIds`) must agree on the value they seed.
+ *
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import { GranolaBlock } from '@/blocks/blocks/granola'
+import type { SubBlockConfig } from '@/blocks/types'
+import * as granolaTools from '@/tools/granola'
+import type { ToolConfig } from '@/tools/types'
+
+const TRIGGER_FIELDS = new Set(['operation', 'selectedTriggerId'])
+
+const toolsById = new Map<string, ToolConfig>(
+  Object.values(granolaTools).map((tool) => [tool.id, tool])
+)
+
+const subBlocks: SubBlockConfig[] = GranolaBlock.subBlocks
+const access: string[] = GranolaBlock.tools.access ?? []
+const declaredInputs = Object.keys(GranolaBlock.inputs ?? {})
+
+const operationSubBlock = subBlocks.find((subBlock) => subBlock.id === 'operation')
+const operationOptions =
+  typeof operationSubBlock?.options === 'function'
+    ? operationSubBlock.options()
+    : (operationSubBlock?.options ?? [])
+const operations = operationOptions.map((option) => option.id as string)
+
+/** The block maps an operation onto its tool by prefixing the service name. */
+const toolIdFor = (operation: string) => `granola_${operation}`
+
+/**
+ * Trigger mode re-declares its own credential fields keyed on `selectedTriggerId`, so only the
+ * operation-gated subblocks describe the tool surface.
+ */
+const operationSubBlocks = subBlocks.filter((subBlock) => {
+  const condition = subBlock.condition
+  if (typeof condition === 'function') return false
+  return subBlock.id === 'operation' || !condition || condition.field === 'operation'
+})
+
+function visibleFor(operation: string): string[] {
+  return operationSubBlocks
+    .filter((subBlock) => {
+      const condition = subBlock.condition
+      if (typeof condition === 'function' || !condition) return true
+      return Array.isArray(condition.value)
+        ? condition.value.includes(operation)
+        : condition.value === operation
+    })
+    .map((subBlock) => subBlock.id)
+}
+
+describe('granola block/tool alignment', () => {
+  it('maps every operation to a registered tool and back', () => {
+    expect(operations.filter((operation) => !access.includes(toolIdFor(operation)))).toEqual([])
+    expect(access.filter((tool) => !operations.map(toolIdFor).includes(tool))).toEqual([])
+    expect(access.filter((tool) => !toolsById.has(tool))).toEqual([])
+  })
+
+  it('keeps operation-gated subBlock ids unique', () => {
+    const ids = operationSubBlocks.map((subBlock) => subBlock.id)
+    expect(ids.filter((id, index) => ids.indexOf(id) !== index)).toEqual([])
+  })
+
+  it('exposes a subBlock for every required tool param', () => {
+    const missing: string[] = []
+
+    for (const operation of operations) {
+      const tool = toolsById.get(toolIdFor(operation))
+      if (!tool) continue
+      const visible = visibleFor(operation)
+
+      for (const [name, param] of Object.entries(tool.params)) {
+        if (param.visibility === 'hidden' || !param.required) continue
+        if (!visible.includes(name)) missing.push(`${operation}.${name}`)
+      }
+    }
+
+    expect(missing).toEqual([])
+  })
+
+  it('backs every visible subBlock with a param on its operation tool', () => {
+    const stray: string[] = []
+
+    for (const operation of operations) {
+      const tool = toolsById.get(toolIdFor(operation))
+      if (!tool) continue
+
+      for (const id of visibleFor(operation)) {
+        if (TRIGGER_FIELDS.has(id)) continue
+        if (!tool.params[id]) stray.push(`${operation}.${id}`)
+      }
+    }
+
+    expect(stray).toEqual([])
+  })
+
+  it('declares every operation-gated subBlock in block inputs', () => {
+    const undeclared = operationSubBlocks
+      .filter((subBlock) => !TRIGGER_FIELDS.has(subBlock.id) && subBlock.condition)
+      .map((subBlock) => subBlock.id)
+      .filter((id) => !declaredInputs.includes(id))
+
+    expect(undeclared).toEqual([])
+  })
+})
+
+describe('granola duplicate subBlock defaults', () => {
+  it('seeds one value per subBlock id across the tool and trigger surfaces', () => {
+    const seeded = new Map<string, unknown[]>()
+
+    for (const subBlock of subBlocks) {
+      const value =
+        typeof subBlock.value === 'function' ? subBlock.value({}) : (subBlock.value ?? null)
+      const existing = seeded.get(subBlock.id) ?? []
+      existing.push(value ?? null)
+      seeded.set(subBlock.id, existing)
+    }
+
+    const divergent = [...seeded.entries()]
+      .filter(([, values]) => new Set(values.map((v) => JSON.stringify(v ?? null))).size > 1)
+      .map(([id, values]) => `${id}: ${JSON.stringify(values)}`)
+
+    expect(divergent).toEqual([])
+  })
+})
+
+describe('granola trigger wiring', () => {
+  it('registers every available trigger and renders its subBlocks', () => {
+    const available = GranolaBlock.triggers?.available ?? []
+
+    expect(GranolaBlock.triggers?.enabled).toBe(true)
+    expect(available).toEqual([
+      'granola_note_generated',
+      'granola_note_edited',
+      'granola_note_access_granted',
+      'granola_webhook',
+    ])
+
+    /* Each trigger contributes a webhook URL display gated on its own id. */
+    for (const triggerId of available) {
+      const rendered = subBlocks.some((subBlock) => {
+        const condition = subBlock.condition
+        if (typeof condition === 'function' || !condition) return false
+        return (
+          condition.field === 'selectedTriggerId' &&
+          (Array.isArray(condition.value)
+            ? condition.value.includes(triggerId)
+            : condition.value === triggerId)
+        )
+      })
+      expect(rendered, `no subBlocks rendered for ${triggerId}`).toBe(true)
+    }
+  })
+})