@posthog/wizard 2.81.1 → 2.82.0

package/dist/{agent-interface-DMP3DZRd.js → agent-interface-3YfIWZmY.js}

@@ -1,11 +1,13 @@
-import { a as initLogFile, i as getLogFilePath, o as logToFile, r as formatLogLine, v as runtimeEnv } from "./debug-C3tLP-ZW.js";
-import { $ as WIZARD_REMARK_EVENT_NAME, it as wizardUserAgentForProgram, l as AWS_SKILLS_BASE_URL, n as analytics } from "./analytics-X7JfAmh6.js";
+import { a as initLogFile, i as getLogFilePath, o as logToFile, r as formatLogLine, v as runtimeEnv } from "./debug-BvEbemym.js";
+import { $ as WIZARD_REMARK_EVENT_NAME, it as wizardUserAgentForProgram, l as AWS_SKILLS_BASE_URL, n as analytics } from "./analytics-B_xFshPY.js";
 import { i as classifyAuthFailure } from "./errors-DhFeR8Sp.js";
-import { a as safeReadFile, i as readProjectFile, o as walkProjectFiles } from "./bounded-fs-iDiqDQ9v.js";
-import { c as REMARK_INSTRUCTION, d as gatewayAuth, f as isPastRefresh, i as gatewayApiFor, l as RESUME_INSTRUCTION, n as buildGatewayModel, s as AgentSignals, u as buildWizardPropertiesBlob } from "./gateway-IQjQ582o.js";
-import { i as modelCapabilities, o as triageModelFor } from "./models-Cow22jET.js";
-import { _ as makeMutex, l as buildOrchestratorTools, v as writeJsonAtomic } from "./queue-tools-DrJKvFHZ.js";
-import { C as coerceAuditChecks, _ as downloadSkill, l as prewarmYaraScanner, n as createPostToolUseYaraHooks, p as scanInstalledSkill, r as createPreToolUseYaraHooks, x as AUDIT_CHECKS_FILE, y as fetchSkillMenu } from "./yara-hooks-canFIYTc.js";
+import { a as safeReadFile, i as readProjectFile, o as walkProjectFiles } from "./bounded-fs-iRaQcKYL.js";
+import { c as isGrantRevoked, i as oauthCredentials, s as rotateAfterUnauthorized } from "./oauth-session-Bi1MLRCC.js";
+import { c as REMARK_INSTRUCTION, d as gatewayAuth, f as isPastRefresh, i as gatewayApiFor, l as RESUME_INSTRUCTION, n as buildGatewayModel, s as AgentSignals, u as buildWizardPropertiesBlob } from "./gateway-CWoYlPz7.js";
+import { i as modelCapabilities, o as triageModelFor } from "./models-C9rjXPZ6.js";
+import { _ as makeMutex, l as buildOrchestratorTools, v as writeJsonAtomic } from "./queue-tools-BoIITT7w.js";
+import { C as coerceAuditChecks, _ as downloadSkill, l as prewarmYaraScanner, n as createPostToolUseYaraHooks, p as scanInstalledSkill, r as createPreToolUseYaraHooks, x as AUDIT_CHECKS_FILE, y as fetchSkillMenu } from "./yara-hooks-BS0n3ekf.js";
+import { a as createMarkdownNotebook, f as updateMarkdownNotebook, s as fetchMarkdownNotebook } from "./api-C_9KsN-7.js";
 import { createRequire } from "node:module";
 import * as fs$1 from "fs";
 import fs from "fs";
@@ -13,7 +15,8 @@ import path from "path";
 import path$1 from "node:path";
 import { spawnSync } from "node:child_process";
 import { closeSync, constants, fchmodSync, lstatSync, openSync, renameSync, unlinkSync, writeSync } from "node:fs";
-import { randomBytes, randomUUID } from "node:crypto";
+import axios from "axios";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
 import * as os from "os";
 import { minimatch } from "minimatch";
 import { randomUUID as randomUUID$1 } from "crypto";
@@ -1518,6 +1521,173 @@ const WIZARD_TOOL_NAMES = {
 	readHandoffs: `mcp__${SERVER_NAME}__read_handoffs`
 };
 //#endregion
+//#region src/agent/tools/handoff-notebook.ts
+/**
+* The PostHog notebook that mirrors a run's handoff report. The first call of a
+* run creates it, later calls (a report task retry) update the same one, so a
+* run owns one notebook. It never throws: a notebook that can't be written is a
+* skip the caller reports, not a failed handoff.
+*/
+const NOTEBOOK_SCOPE = "notebook:write";
+const DEFAULT_TITLE = "PostHog setup report";
+/** One deadline for the whole sync, so a slow PostHog cannot hold the agent's tool call. */
+const SYNC_DEADLINE_MS = 8e3;
+/** The notebook each program of a run holds: where to update it and the version to send. */
+const notebooks = /* @__PURE__ */ new Map();
+/** An alphanumeric id of the 12 characters the backend allows, the same for one key every time. */
+const shortIdFor = (key) => createHash("sha256").update(key).digest("hex").slice(0, 12);
+/** The backend's title limit, the one the MCP's notebook tools enforce. */
+const MAX_TITLE_LENGTH = 256;
+/** The report's first H1, which the report is told to open with. */
+const titleOf = (markdown) => (/^# +(.+)$/m.exec(markdown)?.[1].trim() || DEFAULT_TITLE).slice(0, MAX_TITLE_LENGTH);
+const failed = (reason, description, heldUrl) => {
+	logToFile(`[publish_handoff] notebook ${heldUrl ? "not updated" : "skipped"} (${reason})`);
+	return heldUrl ? {
+		outcome: "not_updated",
+		reason,
+		description,
+		url: heldUrl
+	} : {
+		outcome: "skipped",
+		reason,
+		description
+	};
+};
+const responseStatus = (err) => axios.isAxiosError(err) ? err.response?.status : void 0;
+const TIMEOUT_CODES = new Set([
+	"ERR_CANCELED",
+	"ECONNABORTED",
+	"ETIMEDOUT"
+]);
+const isTimeout = (err, signal) => signal.aborted || err instanceof Error && TIMEOUT_CODES.has(err.code ?? "");
+/** A short code for telemetry and a few words for the agent; neither carries a body or a token. */
+function failureFor(err, signal, heldUrl) {
+	if (isTimeout(err, signal)) return failed("timeout", "PostHog did not answer in time", heldUrl);
+	const status = responseStatus(err);
+	if (status === 401) return failed("unauthorized", "PostHog rejected the login", heldUrl);
+	if (status === 403) return failed("http_403", "PostHog denied access", heldUrl);
+	if (status !== void 0) return failed(`http_${status}`, `PostHog returned HTTP ${status}`, heldUrl);
+	return failed("error", "the request to PostHog failed", heldUrl);
+}
+/** A write worth one more try: no response at all (not a cancel), or a server error. */
+function isTransient(err, signal) {
+	if (isTimeout(err, signal)) return false;
+	const status = responseStatus(err);
+	return status === void 0 || status >= 500;
+}
+/** Whether a failed create may still have made the notebook: lost response, server error, or an id clash. */
+function mayHaveLanded(err) {
+	const status = responseStatus(err);
+	return status === void 0 || status >= 500 || status === 400 || status === 409;
+}
+/** Give up on `work` when the deadline passes, even if the call under it ignores the signal. */
+function beforeDeadline(work, signal) {
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => reject(signal.reason);
+		signal.addEventListener("abort", onAbort, { once: true });
+		work.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+	});
+}
+/** Create this program's notebook from `markdown`, or update it when an earlier call in the run made one. */
+async function syncHandoffNotebook(markdown, programId = "") {
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), SYNC_DEADLINE_MS);
+	try {
+		return await sync(markdown, programId, controller.signal);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+async function sync(markdown, programId, signal) {
+	const key = `${analytics.runId}:${programId}`;
+	const held = notebooks.get(key);
+	const shortId = held?.shortId ?? shortIdFor(key);
+	const heldUrl = held?.url;
+	let fetched;
+	try {
+		fetched = await beforeDeadline(oauthCredentials(), signal);
+	} catch (err) {
+		return failureFor(err, signal, heldUrl);
+	}
+	const urlFor = (login) => `${login.host.appHost}/project/${login.projectId}/notebooks/${shortId}`;
+	if (!fetched) return failed("no_login", "not logged in to PostHog", heldUrl);
+	let credentials = fetched;
+	if (credentials.missingScopes?.includes(NOTEBOOK_SCOPE)) return failed("missing_scope", `the login lacks the ${NOTEBOOK_SCOPE} permission`, heldUrl);
+	/** Push `markdown` as this login: create, or update at the version the server holds. */
+	const push = async (login, retried) => {
+		const args = [
+			login.accessToken,
+			login.projectId,
+			login.host.apiHost
+		];
+		let version = held?.version;
+		const lookup = async () => {
+			try {
+				return await fetchMarkdownNotebook(...args, shortId, signal);
+			} catch {
+				return null;
+			}
+		};
+		if (retried) {
+			const found = await lookup();
+			if (found?.markdown === markdown) return found.version;
+			version = found?.version ?? version;
+		}
+		if (version === void 0) try {
+			return await createMarkdownNotebook(...args, {
+				shortId,
+				title: titleOf(markdown),
+				markdown
+			}, signal);
+		} catch (err) {
+			const found = mayHaveLanded(err) ? await lookup() : null;
+			if (!found) throw err;
+			if (found.markdown === markdown) return found.version;
+			version = found.version;
+		}
+		return updateMarkdownNotebook(...args, {
+			shortId,
+			markdown,
+			version
+		}, signal);
+	};
+	/** One try, plus one more with a rotated token after a 401. */
+	const authorized = async (retried) => {
+		try {
+			return await push(credentials, retried);
+		} catch (err) {
+			if (responseStatus(err) !== 401) throw err;
+			const recovery = await beforeDeadline(rotateAfterUnauthorized(credentials, { requireRefreshToken: false }), signal);
+			if (recovery.kind !== "rotated") throw err;
+			credentials = recovery.credentials;
+			return push(credentials, retried);
+		}
+	};
+	let version;
+	try {
+		try {
+			version = await beforeDeadline(authorized(false), signal);
+		} catch (err) {
+			if (!isTransient(err, signal)) throw err;
+			version = await beforeDeadline(authorized(true), signal);
+		}
+	} catch (err) {
+		return failureFor(err, signal, heldUrl);
+	}
+	const url = urlFor(credentials);
+	notebooks.set(key, {
+		shortId,
+		version,
+		url
+	});
+	logToFile(`[publish_handoff] notebook ${held ? "updated" : "created"}`);
+	return {
+		outcome: held ? "updated" : "created",
+		url
+	};
+}
+//#endregion
 //#region src/shared/utils/needs-attention.ts
 /** The heading of the warning block a handoff report opens with when work is left. */
 const NEEDS_ATTENTION_HEADING = "Needs your attention";
@@ -1557,7 +1727,7 @@ const PUBLISH_HANDOFF_TOOL_NAME = "publish_handoff";
 * full report per step, each replaced by the next, and a step that read the
 * call as its own finish skipped `complete_task` and was restarted.
 */
-const PUBLISH_HANDOFF_DESCRIPTION = `Publish the handoff document — the full markdown report of what the whole run did — to the wizard session. A run publishes once: call it only when your own instructions ask you to write that report, passing the complete report as \`content\`, and never write the report to a file yourself. When anything is left for the user to do, open the report, right under the H1, with a \`> ⚠️ **${NEEDS_ATTENTION_HEADING}**\` block quote, one \`> - \` bullet per item. It is not how you report your own work — in a run made of several tasks each step finishes with complete_task, and a step that was not asked for the run report leaves this one uncalled, because the section it owns travels in its handoff.`;
+const PUBLISH_HANDOFF_DESCRIPTION = `Publish the handoff document — the full markdown report of what the whole run did — to the wizard session. A run publishes once: call it only when your own instructions ask you to write that report, passing the complete report as \`content\`, and never write the report to a file yourself. When anything is left for the user to do, open the report, right under the H1, with a \`> ⚠️ **${NEEDS_ATTENTION_HEADING}**\` block quote, one \`> - \` bullet per item. It is not how you report your own work — in a run made of several tasks each step finishes with complete_task, and a step that was not asked for the run report leaves this one uncalled, because the section it owns travels in its handoff. When the result names a PostHog notebook, the wizard already mirrored the report there: never create a notebook yourself.`;
 /** Appended for a task agent: the reminder lands as it decides it has finished. */
 const TASK_REPORTING_NOTE = " This does not report your task: call complete_task to finish.";
 const PUBLISH_HANDOFF_CONTENT_DESCRIPTION = "The complete handoff report as markdown, starting with an H1 heading.";
@@ -1621,7 +1791,14 @@ function writeHandoffFileAtomically(targetPath, text) {
 		};
 	}
 }
-function publishHandoff(content, emit, opts = {}) {
+const notebookNote = (notebook) => {
+	switch (notebook.outcome) {
+		case "skipped": return `Notebook not created: ${notebook.description}.`;
+		case "not_updated": return `Notebook not updated: ${notebook.description}. It still holds the earlier report: ${notebook.url}.`;
+		default: return `Notebook ${notebook.outcome}: ${notebook.url}. Do not create another notebook.`;
+	}
+};
+async function publishHandoff(content, emit, opts = {}) {
 	if (content.trim() === "") {
 		analytics.wizardCapture("handoff published", {
 			handoff_ok: false,
@@ -1649,18 +1826,28 @@ function publishHandoff(content, emit, opts = {}) {
 			logToFile(`[publish_handoff] host output write failed (${write.reason}): ${write.detail}`);
 		}
 	}
+	const notebookRequested = opts.handoffNotebook === true;
+	const notebook = notebookRequested ? await syncHandoffNotebook(text, opts.programId) : void 0;
+	if (notebook?.outcome === "created" || notebook?.outcome === "updated") emit?.({
+		kind: "url",
+		which: "notebook",
+		url: notebook.url
+	});
 	analytics.wizardCapture("handoff published", {
 		handoff_ok: true,
 		handoff_chars: text.length,
 		handoff_truncated: truncated,
-		handoff_output_written: handoffOutputWritten
+		handoff_output_written: handoffOutputWritten,
+		notebook_requested: notebookRequested,
+		notebook_outcome: notebook?.outcome,
+		notebook_skip_reason: notebook?.outcome === "skipped" || notebook?.outcome === "not_updated" ? notebook.reason : void 0
 	});
 	const notes = [];
 	if (truncated) notes.push("truncated to the 64 KB limit");
 	if (handoffOutputError) notes.push(`host output write failed: ${handoffOutputError}`);
 	return {
 		ok: true,
-		message: `Handoff published (${text.length} chars${notes.length > 0 ? `, ${notes.join("; ")}` : ""}).${opts.taskAgent ? TASK_REPORTING_NOTE : ""}`
+		message: `Handoff published (${text.length} chars${notes.length > 0 ? `, ${notes.join("; ")}` : ""}).${notebook ? ` ${notebookNote(notebook)}` : ""}${opts.taskAgent ? TASK_REPORTING_NOTE : ""}`
 	};
 }
 //#endregion
@@ -1746,7 +1933,7 @@ async function getSDKModule$1() {
 * Must be called asynchronously because the SDK is an ESM module loaded via dynamic import.
 */
 async function createWizardToolsServer(options) {
-	const { workingDirectory, detectPackageManager, skillsBaseUrl, askBridge, askMaxQuestions = 10, secretVault = createSecretVault(), orchestrator, triageProvider, emit } = options;
+	const { workingDirectory, detectPackageManager, skillsBaseUrl, askBridge, askMaxQuestions = 10, secretVault = createSecretVault(), orchestrator, triageProvider, emit, programId, handoffNotebook } = options;
 	const { tool, createSdkMcpServer } = await getSDKModule$1();
 	const askAccounting = createAskAccounting(askMaxQuestions);
 	let cachedSkillMenu = {};
@@ -2032,8 +2219,12 @@ async function createWizardToolsServer(options) {
 					};
 				}
 			}),
-			tool(PUBLISH_HANDOFF_TOOL_NAME, PUBLISH_HANDOFF_DESCRIPTION, { content: z.string().describe(PUBLISH_HANDOFF_CONTENT_DESCRIPTION) }, (args) => {
-				const result = publishHandoff(args.content, emit, { taskAgent: orchestrator?.currentTaskId !== void 0 });
+			tool(PUBLISH_HANDOFF_TOOL_NAME, PUBLISH_HANDOFF_DESCRIPTION, { content: z.string().describe(PUBLISH_HANDOFF_CONTENT_DESCRIPTION) }, async (args) => {
+				const result = await publishHandoff(args.content, emit, {
+					taskAgent: orchestrator?.currentTaskId !== void 0,
+					programId,
+					handoffNotebook
+				});
 				logToFile(`publish_handoff: ${result.message}`);
 				return {
 					content: [{
@@ -2200,34 +2391,6 @@ function classifyToolToStage(toolName) {
 	return null;
 }
 //#endregion
-//#region src/shared/auth-session-state.ts
-/**
-* Whether this run's OAuth grant is known to be dead.
-*
-* Process-global on purpose. A run has exactly one login, but the two sides of
-* this fact are far apart: the pre-run refresh learns it in `authenticate.ts`,
-* and the only consumer is the 401 handler inside the agent message loop, which
-* holds no session. Threading it would mean a field on `AgentConfig` set at four
-* `initializeAgent` call sites — and the session it would read from may be a
-* shallow copy (`prepareRunSession`), so the value could be written to one
-* object and read from another.
-*
-* A leaf module with no imports, so either side can depend on it without a cycle.
-*/
-let grantRevoked = false;
-/**
-* Record that the token endpoint permanently refused this grant. Not an abort:
-* the access token in hand may still have minutes of life, so the run continues
-* and this only decides what a later 401 gets blamed on.
-*/
-function markGrantRevoked() {
-	grantRevoked = true;
-}
-/** True once a token refresh failed because the grant itself is gone. */
-function isGrantRevoked() {
-	return grantRevoked;
-}
-//#endregion
 //#region src/agent/output-signals.ts
 /**
 * Parses the signal-bearing lines out of agent output and discards the rest.
@@ -3101,7 +3264,9 @@ async function initializeAgent(config, options) {
 			askMaxQuestions: config.askMaxQuestions,
 			orchestrator: config.orchestrator,
 			triageProvider,
-			emit: config.emit
+			emit: config.emit,
+			programId: config.programId,
+			handoffNotebook: config.handoffNotebook
 		});
 		const model = config.modelOverride ?? "claude-sonnet-5";
 		const agentRunConfig = {
@@ -4052,6 +4217,6 @@ function handleSDKMessage(message, options, spinner, signals, emit, receivedSucc
 	}
 }
 //#endregion
-export { seedAuditChecks as $, AUDIT_SEED_CHECKS_DESCRIPTION as A, WIZARD_TOOL_NAMES as B, publishHandoff as C, AUDIT_ADD_CHECKS_PARAM_DESCRIPTION as D, AUDIT_ADD_CHECKS_DESCRIPTION as E, ENV_FILE_PATH_DESCRIPTION as F, ensureGitignoreCoverage as G, checkEnvKeys as H, WIZARD_ASK_KIND_DESCRIPTION as I, normaliseAskSubject as J, legacyKeyNameRefusal as K, WIZARD_ASK_SENSITIVE_DESCRIPTION as L, AUDIT_STATUSES as M, CHECK_ENV_KEYS_DESCRIPTION as N, AUDIT_RESOLVE_CHECKS_DESCRIPTION as O, CHECK_ENV_KEYS_FILE_PATH_DESCRIPTION as P, resolveEnvSecretRefs as Q, WIZARD_ASK_SUBJECT_DESCRIPTION as R, PUBLISH_HANDOFF_TOOL_NAME as S, readNeedsAttention as T, createAskAccounting as U, addAuditChecks as V, describeAskCancellation as W, resolveAuditChecks as X, resolveAskQuestionKinds as Y, resolveEnvPath as Z, markGrantRevoked as _, wizardCanUseTool as a, shouldDisableAsk as at, PUBLISH_HANDOFF_CONTENT_DESCRIPTION as b, checkAllSettingsConflicts as c, parseEnvKeyNames as ct, restoreClaudeSettings as d, templateEnvWriteRefusal as et, sanitizeAgentSubprocessEnv as f, isGrantRevoked as g, AgentOutputSignals as h, runAgent as i, LONGER_ASK_TIMEOUT_MS as it, AUDIT_SEED_CHECKS_PARAM_DESCRIPTION as j, AUDIT_RESOLVE_CHECKS_PARAM_DESCRIPTION as k, classifySettingsConflicts as l, toPromptSafeRelativePath as lt, runCleanups as m, buildRunTags as n, createWizardAskBridge as nt, createIsolatedAgentConfigDir as o, MAX_ENV_KEY_SET as ot, registerCleanup as p, mergeEnvValues as q, initializeAgent as r, isFullyCancelled as rt, backupAndFixClaudeSettings as s, isEnvFileName as st, buildAgentEnv as t, vaultSensitiveAnswers as tt, recoverOrphanedSettingsBackups as u, createTriageLLMProvider as ut, assembleCommandments as v, NEEDS_ATTENTION_HEADING as w, PUBLISH_HANDOFF_DESCRIPTION as x, createSecretVault as y, WIZARD_ASK_TOOL_DESCRIPTION as z };
+export { vaultSensitiveAnswers as $, AUDIT_STATUSES as A, checkEnvKeys as B, readNeedsAttention as C, AUDIT_RESOLVE_CHECKS_PARAM_DESCRIPTION as D, AUDIT_RESOLVE_CHECKS_DESCRIPTION as E, WIZARD_ASK_SENSITIVE_DESCRIPTION as F, mergeEnvValues as G, describeAskCancellation as H, WIZARD_ASK_SUBJECT_DESCRIPTION as I, resolveAuditChecks as J, normaliseAskSubject as K, WIZARD_ASK_TOOL_DESCRIPTION as L, CHECK_ENV_KEYS_FILE_PATH_DESCRIPTION as M, ENV_FILE_PATH_DESCRIPTION as N, AUDIT_SEED_CHECKS_DESCRIPTION as O, WIZARD_ASK_KIND_DESCRIPTION as P, templateEnvWriteRefusal as Q, WIZARD_TOOL_NAMES as R, NEEDS_ATTENTION_HEADING as S, AUDIT_ADD_CHECKS_PARAM_DESCRIPTION as T, ensureGitignoreCoverage as U, createAskAccounting as V, legacyKeyNameRefusal as W, resolveEnvSecretRefs as X, resolveEnvPath as Y, seedAuditChecks as Z, createSecretVault as _, wizardCanUseTool as a, isEnvFileName as at, PUBLISH_HANDOFF_TOOL_NAME as b, checkAllSettingsConflicts as c, createTriageLLMProvider as ct, restoreClaudeSettings as d, createWizardAskBridge as et, sanitizeAgentSubprocessEnv as f, assembleCommandments as g, AgentOutputSignals as h, runAgent as i, MAX_ENV_KEY_SET as it, CHECK_ENV_KEYS_DESCRIPTION as j, AUDIT_SEED_CHECKS_PARAM_DESCRIPTION as k, classifySettingsConflicts as l, runCleanups as m, buildRunTags as n, LONGER_ASK_TIMEOUT_MS as nt, createIsolatedAgentConfigDir as o, parseEnvKeyNames as ot, registerCleanup as p, resolveAskQuestionKinds as q, initializeAgent as r, shouldDisableAsk as rt, backupAndFixClaudeSettings as s, toPromptSafeRelativePath as st, buildAgentEnv as t, isFullyCancelled as tt, recoverOrphanedSettingsBackups as u, PUBLISH_HANDOFF_CONTENT_DESCRIPTION as v, AUDIT_ADD_CHECKS_DESCRIPTION as w, publishHandoff as x, PUBLISH_HANDOFF_DESCRIPTION as y, addAuditChecks as z };
 
-//# sourceMappingURL=agent-interface-DMP3DZRd.js.map
+//# sourceMappingURL=agent-interface-3YfIWZmY.js.map