Skip to content

:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.

feat(cdp): let the run scout step report queued fires and opt out of queueing (#123704)

posthog[bot]b466e8e2b48a
diff --git a/nodejs/src/cdp/async-functions/run-scout.ts b/nodejs/src/cdp/async-functions/run-scout.ts
index 44ea66a9e896..547f5b88d4c2 100644
--- a/nodejs/src/cdp/async-functions/run-scout.ts
+++ b/nodejs/src/cdp/async-functions/run-scout.ts
@@ -56,6 +56,8 @@ registerAsyncFunction('postHogRunScout', {
}
const token = jwt.mint({ team_id: context.invocation.teamId, hog_flow_id: hogFlow.id }, TOKEN_TTL_SECONDS)
const note = typeof payload.note === 'string' ? truncateNote(payload.note.trim()) : ''
+ // Anything else is left out, so the endpoint applies its default and queues.
+ const whenBusy = payload.when_busy === 'queue' || payload.when_busy === 'skip' ? payload.when_busy : undefined
result.invocation.queueParameters = CyclotronInvocationQueueParametersFetchSchema.parse({
type: 'fetch',
@@ -69,6 +71,7 @@ registerAsyncFunction('postHogRunScout', {
skill_name: payload.skill_name,
idempotency_key: idempotencyKey,
...(note ? { note } : {}),
+ ...(whenBusy ? { when_busy: whenBusy } : {}),
}),
})
},
diff --git a/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.test.ts b/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.test.ts
index 81d58042fdf8..08ce04cf125b 100644
--- a/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.test.ts
+++ b/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.test.ts
@@ -29,6 +29,7 @@ describe('posthog run scout template', () => {
expect(parseJSON(params.body!)).toEqual({
skill_name: 'signals-scout-error-tracking',
idempotency_key: `${response.invocation.id}:action_1:0`,
+ when_busy: 'queue',
})
const token = (params.headers?.['Authorization'] ?? '').replace('Bearer ', '')
@@ -64,6 +65,17 @@ describe('posthog run scout template', () => {
}
})
+ it.each([
+ ['forwards skip', 'skip', 'skip'],
+ ['leaves an unknown value to the endpoint default', 'later', undefined],
+ ])('%s for a busy scout', async (_name, whenBusy, expected) => {
+ const response = await tester.invoke({ ...inputs, when_busy: whenBusy }, undefined, workflowOptions)
+ expect(response.error).toBeUndefined()
+
+ const params = response.invocation.queueParameters as CyclotronInvocationQueueParametersFetchType
+ expect(parseJSON(params.body!).when_busy).toEqual(expected)
+ })
+
it('fails without staging a request when no scout is chosen', async () => {
const response = await tester.invoke({ skill_name: '' }, undefined, workflowOptions)
expect(response.error).toMatch(/A scout is required/)
@@ -92,6 +104,18 @@ describe('posthog run scout template', () => {
})
})
+ it('finishes without parking when the busy scout queued the trigger', async () => {
+ let response = await tester.invoke(inputs, undefined, workflowOptions)
+ response = await tester.invokeFetchResponse(response.invocation, {
+ status: 202,
+ body: { scout: 'signals-scout-error-tracking', workflow_id: null, queued: true },
+ })
+
+ expect(response.error).toBeUndefined()
+ expect(response.finished).toBe(true)
+ expect(response.execResult).toEqual({ skipped: false, queued: true, scout: 'signals-scout-error-tracking' })
+ })
+
it('skips instead of failing on a 409 response', async () => {
let response = await tester.invoke(inputs, undefined, workflowOptions)
response = await tester.invokeFetchResponse(response.invocation, {
diff --git a/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.ts b/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.ts
index 5517eca808b1..d3725d0f5930 100644
--- a/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.ts
+++ b/nodejs/src/cdp/templates/_destinations/posthog_signals/posthog-run-scout.template.ts
@@ -20,7 +20,7 @@ if (empty(inputs.skill_name)) {
throw Error('A scout is required')
}
-let response := postHogRunScout({ 'skill_name': inputs.skill_name, 'note': inputs.note })
+let response := postHogRunScout({ 'skill_name': inputs.skill_name, 'note': inputs.note, 'when_busy': inputs.when_busy })
if (response.status == 409) {
print(f'Scout not run: {apiErrorMessage(response)}')
@@ -32,6 +32,10 @@ if (response.status >= 400) {
}
let run := response.body
+if (run.queued) {
+ print('Scout busy: the trigger is queued, and a later run handles it')
+ return { 'skipped': false, 'queued': true, 'scout': run.scout }
+}
if (not empty(run.workflow_id)) {
// Park the workflow step until the run finishes: the scout runtime cap plus slack for its wake.
run.await := { 'max_wait': '35m', 'label': 'scout run' }
@@ -57,10 +61,30 @@ return run
description:
'Optional. Tells the scout what triggered this run, so it can focus on it. Use identifiers such as a PR number or URL, for example PR #{event.properties.pr_number}, not free text like a title or body from the event. The scout sees the note for this run only. Notes longer than 1,000 characters are cut. Adding a note requires editor access to skills.',
},
+ {
+ // Hidden like the status codes below: queueing is the default, and an author who only
+ // wants the latest event to count sets "skip" through the API or MCP. Not required, so
+ // a step saved before this input existed sends nothing and queues.
+ key: 'when_busy',
+ type: 'choice',
+ label: 'When the scout is busy',
+ secret: false,
+ required: false,
+ hidden: true,
+ templating: false,
+ choices: [
+ { label: 'Queue the trigger', value: 'queue' },
+ { label: 'Skip it', value: 'skip' },
+ ],
+ default: 'queue',
+ description:
+ 'What happens when the scout is already running, or ran from a workflow in the last 30 minutes. Queue the trigger, and a later run handles its note. Or skip it.',
+ },
{
// The engine treats a 4xx as a step failure before the code above runs, unless the
// status is listed here. 409 is the endpoint's answer for every kind of backpressure
- // (paused, cooldown, budget, quota), which the code above turns into a graceful skip.
+ // (paused, budget, quota, and a busy scout when `when_busy` is "skip"), which the code
+ // above turns into a graceful skip.
// A missing or unrunnable scout answers 404, deliberately NOT listed here, so a
// misconfigured node fails loudly.
// required (despite being hidden): the backend only fills a schema default for a
diff --git a/nodejs/tests/fixtures/hog-bytecode/d338a043a0d8c01e83f8574f7e43b7697aaaca35ca446180d315c64740644a40.json b/nodejs/tests/fixtures/hog-bytecode/d338a043a0d8c01e83f8574f7e43b7697aaaca35ca446180d315c64740644a40.json
new file mode 100644
index 000000000000..247cf1873729
--- /dev/null
+++ b/nodejs/tests/fixtures/hog-bytecode/d338a043a0d8c01e83f8574f7e43b7697aaaca35ca446180d315c64740644a40.json
@@ -0,0 +1 @@
+["_H",1,52,"apiErrorMessage",1,0,28,36,0,32,"body",45,32,"error",45,47,9,35,36,0,32,"body",45,32,"detail",45,47,6,35,36,0,32,"body",45,38,53,0,32,"skill_name",32,"inputs",1,2,2,"empty",1,40,6,32,"A scout is required",2,"Error",1,49,32,"skill_name",32,"skill_name",32,"inputs",1,2,32,"note",32,"note",32,"inputs",1,2,32,"when_busy",32,"when_busy",32,"inputs",1,2,42,3,2,"postHogRunScout",1,33,409,36,1,32,"status",45,11,40,29,32,"Scout not run: ",36,1,36,0,54,1,2,"concat",2,2,"print",1,35,32,"skipped",29,32,"reason",36,1,36,0,54,1,42,2,38,33,400,36,1,32,"status",45,14,40,22,32,"Failed to run scout (",36,1,32,"status",45,32,"): ",36,1,36,0,54,1,2,"concat",4,2,"Error",1,49,36,1,32,"body",45,36,2,32,"queued",45,40,22,32,"Scout busy: the trigger is queued, and a later run handles it",2,"print",1,35,32,"skipped",30,32,"queued",29,32,"scout",36,2,32,"scout",45,42,3,38,36,2,32,"workflow_id",45,2,"empty",1,5,40,15,36,2,32,"await",32,"max_wait",32,"35m",32,"label",32,"scout run",42,2,46,36,2,38,35,35,35]