: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.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import type {
ContentBlock,
RequestPermissionRequest,
SessionConfigOption,
SessionConfigSelectGroup,
SessionConfigSelectOption,
SessionConfigSelectOptions,
} from "@agentclientprotocol/sdk";
import type { Adapter, ModelAccess } from "@posthog/agent-contracts/adapter";
import type {
TaskRunArtifact,
TaskRunStatus,
} from "@posthog/agent-contracts/domain-types";
import type { ExecutionMode } from "@posthog/agent-contracts/exec-types";
import type { AcpMessage } from "@posthog/agent-contracts/session-events";
import type { SkillButtonId } from "./analytics-events";
export type { Adapter };
/** Entries the first paint of a big transcript renders; the rest pages in on scroll. */
export const TRANSCRIPT_TAIL_WINDOW = 2000;
export type PermissionRequest = Omit<RequestPermissionRequest, "sessionId"> & {
taskRunId: string;
receivedAt: number;
};
export interface QueuedMessage {
id: string;
content: string;
rawPrompt?: string | ContentBlock[];
queuedAt: number;
}
export type OptimisticItem =
| {
type: "user_message";
id: string;
content: string;
timestamp: number;
pinToTop?: boolean;
}
| {
type: "skill_button_action";
id: string;
buttonId: SkillButtonId;
};
export type SessionStatus =
| "connecting"
| "connected"
| "disconnected"
| "error";
export interface AgentSession {
taskRunId: string;
taskId: string;
taskTitle: string;
isTaskAuthor?: boolean;
channel: string;
events: AcpMessage[];
startedAt: number;
status: SessionStatus;
errorTitle?: string;
errorMessage?: string;
errorRetryable?: boolean;
isPromptPending: boolean;
isCompacting: boolean;
promptStartedAt: number | null;
currentPromptId?: number | null;
logUrl?: string;
/** Full cloud transcript entry count across the resume chain. */
cloudTranscriptEntryCount?: number;
/** Absolute chain index of the first hydrated entry; >0 while older history is not loaded. */
transcriptWindowStart?: number;
isLoadingOlderTranscript?: boolean;
/** True while the terminal transcript is being fetched. */
isHydratingTranscript?: boolean;
/** Leaf-run cursor used to reconcile live cloud log updates. */
processedLineCount?: number;
framework?: "claude";
adapter?: Adapter;
codexModelAccess?: ModelAccess;
claudeModelAccess?: ModelAccess;
model?: string;
executionMode?: ExecutionMode;
reasoningLevel?: string;
contextWindow?: "200k" | "1m";
fastMode?: boolean;
configOptions?: SessionConfigOption[];
/**
* Adapter's negotiated steering capability (`_meta.posthog.steering` from
* initialize). "native" means a mid-turn message folds into the running turn
* (claude, codex); "interrupt-resend" (legacy) or undefined
* means the host must cancel + resend. Drives the steer-vs-resend decision.
*/
steering?: string;
/**
* Adapter's `/clear` capability (`_meta.posthog.conversationClear`, relayed on
* `_posthog/run_started`). Absent on agents that predate it — the host must not
* record a conversation-cleared boundary they would ignore on resume.
*/
conversationClear?: boolean;
/**
* Adapter's negotiated side-question capability (`_meta.posthog.sideQuestion`
* from initialize). True means the adapter can answer a one-shot "/btw"
* question forked off the live transcript without touching the conversation.
*/
sideQuestion?: boolean;
pendingPermissions: Map<string, PermissionRequest>;
pausedDurationMs: number;
messageQueue: QueuedMessage[];
/**
* Id of the queued message the user currently has open in the composer for an
* in-place edit, if any. While set it acts as a drain boundary: when the turn
* ends, everything queued *before* this message auto-sends, but this message
* and everything after it stay queued until the edit is saved or cancelled.
* See {@link sendableQueuePrefixLength}.
*/
editingQueuedId?: string;
isCloud?: boolean;
cloudStatus?: TaskRunStatus;
cloudStage?: string | null;
cloudOutput?: Record<string, unknown> | null;
cloudArtifacts?: TaskRunArtifact[];
cloudErrorMessage?: string | null;
initialPrompt?: ContentBlock[];
cloudBranch?: string | null;
stopRequested?: boolean;
optimisticItems: OptimisticItem[];
contextUsed?: number;
contextSize?: number;
conversationSummary?: string;
idleKilled?: boolean;
agentVersion?: string;
/** Monotonic for one session: the run that emitted its first non-steer prompt. */
firstPromptForRunId?: string;
resumeAncestorRunIds?: string[];
agentIdleForRunId?: string;
}
/**
* How many messages at the head of the queue are eligible to auto-send when the
* turn ends. A message being edited in place ({@link AgentSession.editingQueuedId})
* is a hard boundary: the messages queued before it may send, but it and
* everything after it stay put until the edit is saved or cancelled. Returns the
* full queue length when nothing is being edited, or when the edited message has
* already left the queue (e.g. it was discarded).
*/
export function sendableQueuePrefixLength(
session: Pick<AgentSession, "messageQueue" | "editingQueuedId">,
): number {
const { messageQueue, editingQueuedId } = session;
if (!editingQueuedId) return messageQueue.length;
const editIndex = messageQueue.findIndex((m) => m.id === editingQueuedId);
return editIndex === -1 ? messageQueue.length : editIndex;
}
export function isSelectGroup(
options: SessionConfigSelectOptions,
): options is SessionConfigSelectGroup[] {
return (
options.length > 0 &&
typeof options[0] === "object" &&
"options" in options[0]
);
}
export function flattenSelectOptions(
options: SessionConfigSelectOptions,
): SessionConfigSelectOption[] {
if (!options.length) return [];
if (isSelectGroup(options)) {
return options.flatMap((group) => group.options);
}
return options as SessionConfigSelectOption[];
}
export function mergeConfigOptions(
live: SessionConfigOption[],
persisted: SessionConfigOption[],
): SessionConfigOption[] {
const persistedMap = new Map(persisted.map((opt) => [opt.id, opt]));
return live.map((liveOpt) => {
const persistedOpt = persistedMap.get(liveOpt.id);
if (persistedOpt) {
return {
...liveOpt,
currentValue: persistedOpt.currentValue,
} as SessionConfigOption;
}
return liveOpt;
});
}
/**
* Whether a persisted config option can be restored into a resumed session's
* live options. The live session must still advertise an option with the same
* id and type, and — for selects — must still offer the persisted value.
* Matching by id alone would restore a value the resumed agent dropped (e.g. a
* reasoning level the resumed model no longer supports), which the server
* rejects and which leaves the UI showing a setting that never took effect.
*/
export function isPersistedOptionSupported(
persisted: SessionConfigOption,
liveOptions: SessionConfigOption[],
): boolean {
const live = liveOptions.find((opt) => opt.id === persisted.id);
if (!live || live.type !== persisted.type) return false;
if (live.type === "select") {
return flattenSelectOptions(live.options).some(
(opt) => opt.value === persisted.currentValue,
);
}
return true;
}
export function getConfigOptionByCategory(
configOptions: SessionConfigOption[] | undefined,
category: string,
): SessionConfigOption | undefined {
return configOptions?.find((opt) => opt.category === category);
}
export function cycleModeOption(
modeOption: SessionConfigOption | undefined,
options?: { allowBypassPermissions?: boolean },
): string | undefined {
if (!modeOption || modeOption.type !== "select") return undefined;
const allOptions = flattenSelectOptions(modeOption.options);
const filtered = options?.allowBypassPermissions
? allOptions
: allOptions.filter(
(opt) =>
opt.value !== "bypassPermissions" && opt.value !== "full-access",
);
if (filtered.length === 0) return undefined;
const currentIndex = filtered.findIndex(
(opt) => opt.value === modeOption.currentValue,
);
if (currentIndex === -1) return filtered[0]?.value;
const nextIndex = (currentIndex + 1) % filtered.length;
return filtered[nextIndex]?.value;
}
export function getCurrentModeFromConfigOptions(
configOptions: SessionConfigOption[] | undefined,
): ExecutionMode | undefined {
const modeOption = getConfigOptionByCategory(configOptions, "mode");
return modeOption?.currentValue as ExecutionMode | undefined;
}
/**
* The safe non-bypass mode to revert to when "Bypass permissions" is turned
* off, chosen from the session's OWN mode options so it's always valid for that
* adapter. Claude exposes "default"; codex has no "default" (its presets are
* plan/read-only/auto/full-access) so it falls back to "auto" — reverting codex
* to "default" would set an unknown mode (no approvalPolicy → an undefined
* approval state). Returns undefined when there is no usable mode option.
*/
export function resolveBypassRevertMode(
modeOption: SessionConfigOption | undefined,
): string | undefined {
if (modeOption?.type !== "select") return undefined;
const opts = flattenSelectOptions(modeOption.options);
const isBypass = (v: string) =>
v === "bypassPermissions" || v === "full-access";
if (opts.some((o) => o.value === "default")) return "default";
if (opts.some((o) => o.value === "auto")) return "auto";
return opts.find((o) => !isBypass(o.value))?.value;
}
/**
* Whether a mid-turn message can be folded into the running turn (steered)
* rather than interrupt-and-resent. Decided by the adapter's negotiated
* `steering` capability: "native" folds (claude, codex app-server);
* "interrupt-resend" (legacy) does not.
*
* Fallback: if `steering` is unset (a start path that predates capability
* plumbing), Claude is still treated as native — it has always steered — so the
* capability rollout can never regress it.
*/
export function sessionSupportsNativeSteer(
session: Pick<AgentSession, "isCloud" | "steering" | "adapter">,
): boolean {
if (session.steering === "native") return true;
if (session.isCloud) return false;
return session.steering == null && session.adapter === "claude";
}
/**
* Whether the session can answer a one-shot "/btw" side question (a
* single-turn, tool-less query forked off the live transcript). Decided by the
* adapter's negotiated `sideQuestion` capability where one was negotiated.
*
* Cloud runs never complete the ACP `initialize` handshake with this client, so
* the capability is inferred from the adapter instead: the sandbox runs the same
* `@posthog/agent` build, and the fork happens there against its own transcript.
* A sandbox predating the `side_question` command rejects it, which surfaces as
* an error on the card rather than a missing command.
*/
export function sessionSupportsSideQuestion(
session: Pick<AgentSession, "isCloud" | "sideQuestion" | "adapter">,
): boolean {
if (session.sideQuestion === true) return true;
if (session.sideQuestion === false) return false;
return session.adapter === "claude";
}