: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
from __future__ import annotations
from collections.abc import Iterable
from decimal import Decimal
from enum import StrEnum
from typing import TYPE_CHECKING, Any
from posthog.dataclasses import frozen
if TYPE_CHECKING:
from posthog.temporal.oauth import PosthogMcpScopes
class Read(StrEnum):
CREATOR = "creator"
TEAM = "team"
class DrivePolicy(StrEnum):
OWNER = "owner"
AUDIENCE = "audience"
NONE = "none"
class GithubResolution(StrEnum):
ALWAYS = "always"
WITH_REPOSITORY = "with_repository"
NEVER = "never"
class OAuthApp(StrEnum):
ARRAY = "array"
POSTHOG_AI = "posthog_ai"
SIGNALS = "signals"
class PrAuthorship(StrEnum):
USER = "user"
BOT = "bot"
class WarmQuota(StrEnum):
NONE = "none"
AI_CREDITS = "ai_credits"
POSTHOG_AI = "posthog_ai"
class GithubAccess(StrEnum):
NONE = "none"
READ = "read"
WRITE = "write"
class NetworkAccess(StrEnum):
TRUSTED = "trusted"
FULL = "full"
CUSTOM = "custom"
class ContractCheck(StrEnum):
PUBLIC_OPTIONS = "public_options"
RUNTIMES = "runtimes"
SANDBOX_TEMPLATES = "sandbox_templates"
MCP_SCOPES = "mcp_scopes"
GITHUB_ACCESS = "github_access"
IDLE_MINUTES = "idle_minutes"
DRIVE = "drive"
class SourceKind(StrEnum):
SIGNAL_REPORT = "signal_report"
HOG_FLOW = "hog_flow"
LOOP = "loop"
@frozen
class TaskSource:
kind: SourceKind
id: str
@frozen
class WarmPolicy:
"""Lets a profile start a sandbox before the first message arrives, so the first reply is fast."""
# AI_CREDITS checks the team's AI credit quota before it warms a sandbox. NONE warms with no quota check.
quota: WarmQuota
# The most warm runs one user may hold at once. A warm run stops counting when it gets its first message.
per_user_cap: int
# The most warm runs one organization may hold at once, counted the same way.
per_org_cap: int
# Feature flag checked for the user and their organization before warming. None warms for every user.
feature_flag: str | None
@frozen
class NetworkPolicy:
levels: tuple[NetworkAccess, ...]
allowed_domains: tuple[str, ...] = ()
include_default_domains: bool = False
def __post_init__(self) -> None:
if not self.levels:
raise TaskProfileError("A network policy needs at least one level")
@frozen
class TaskProfile:
"""The limits and defaults for one kind of task.
Each product defines its own profiles and registers them when its app loads, so the tasks
product never imports another product. A task keeps its profile for its whole life. Values
that change per call go in TaskRunOptions, which can only choose from or narrow what the profile
allows.
"""
# Stable ID stored on Task.profile, such as "signals.implementation". Never rename a key,
# because stored tasks keep the old one.
key: str
# The analytics label, stored on Task.origin_product. Each profile has exactly one.
# Behavior comes from the fields below, never from this label.
origin_product: str
# True lets callers create this kind of task through the public task API.
public: bool
# The TaskRunOptions fields a public API caller may set. The server refuses any other field from
# a public caller.
public_options: frozenset[str]
# The kind of row that starts every task on this profile, such as SIGNAL_REPORT. Task creation
# refuses a source of any other kind. None means the task takes no source.
source_kind: SourceKind | None
# True shows the task in task lists, personal channel filing, auto-archive, the MCP task filter
# and the Desktop staff toggle. Automated work such as loops and scouts is unlisted.
# Task.internal stores the inverse of this value.
listed: bool
# Who can read a task that is not filed in a channel. CREATOR means only the creator. TEAM
# means every member of the team. A task in a channel follows the channel's members instead.
read_without_channel: Read
# False hides the task from the public task API, because it holds another product's data that
# only that product reads through its own facade. The sandbox that runs the task keeps access.
api_visible: bool
# Who can send follow-up messages. OWNER means only the owner. Everyone else gets a 403.
# AUDIENCE means anyone who can read the task, such as the people in a Slack thread.
# NONE means nobody, for tasks that finish on their own.
drive: DrivePolicy
# The most queued or running tasks one person may have on this profile at once. Create and
# wake refuse at the cap. None means no cap.
max_live_per_user: int | None
# How the profile warms sandboxes before the first message. None means it cannot warm.
warm: WarmPolicy | None
# The agent runtimes a task may use, "acp" or "pi". The first one is the default.
runtimes: tuple[str, ...]
# The sandbox templates a task may boot from. The first one is the default.
sandbox_templates: tuple[str, ...]
# A user-picked sandbox environment overrides this, so it covers internal environments and runs without one.
network: NetworkPolicy
# True applies the creator's and the team's default model settings to each run.
inherit_user_defaults: bool
# True also installs the creator's personal MCP servers. It has no effect when
# mcp_store_servers is False.
personal_mcp: bool
# The built-in MCP agent the task acts as: "support", "scout" or "workflow". The sandbox then
# gets that agent's MCP servers instead of its creator's MCP store connections. None means the
# task uses its creator's connections.
mcp_agent: str | None
# The widest PostHog MCP scope preset the agent can get. TaskRunOptions.mcp_scopes can narrow it
# but never widen it.
mcp_scopes: PosthogMcpScopes
# True installs the team's MCP store servers in the sandbox. False installs none, personal
# servers included.
mcp_store_servers: bool
mcp_exclude_tools: tuple[str, ...]
# The OAuth application that mints the sandbox's PostHog tokens. The LLM gateway pins billing
# products per application, so a token from a shared application is valid for every product on
# it. A product with its own billing needs its own application.
oauth_app: OAuthApp
# When the task gets the team's GitHub integration. ALWAYS attaches it. WITH_REPOSITORY
# attaches it only when the task has a repository. NEVER attaches none. Use NEVER for tasks
# that read text members wrote, because a token there turns planted text into repository access.
github_resolution: GithubResolution
github_access: GithubAccess
# True lets runs open pull requests as the creator through their personal GitHub installation.
# A creator without a usable installation falls back to the bot. False always uses the bot.
user_authorable_prs: bool
# Who authors pull requests when the run does not set TaskRunOptions.pr_authorship_mode.
default_pr_authorship: PrAuthorship
# True lets a run open a pull request when it finishes. A caller can still turn it off for one
# run. False means runs never open one, whatever the caller passes.
create_pr: bool
# True gives the agent a finish tool that moves the task to done.
finish_tool: bool
# True moves the task to done when a turn closes, including a failed turn. Use it for work that
# nobody replies to, such as loops, workflow steps and scouts, so idle tasks don't pile up.
done_on_turn_close: bool
# How long the sandbox stays up after a turn closes, in case someone replies. After that the
# task snapshots, releases the sandbox and goes idle. TaskRunOptions.idle_minutes can lower it.
idle_minutes: int
# How long an open turn may go without an agent heartbeat. After that the run fails, so a retry
# can pick the task back up.
inactivity_minutes: int
# How long one tool call or permission prompt may hold the sandbox. None means no cap.
tool_call_minutes: int | None
# Wall-clock cap on one wake. Heartbeats do not reset it, so it stops an agent that hangs but
# keeps heartbeating. None means no cap.
max_wake_minutes: int | None
# The exact LLM gateway product, pinned on the run's credential when it is minted. The gateway
# ignores any product the agent sends. The usage report groups customer billing by this value.
billing_product: str
# True bills sandbox compute to the customer. Compute cost is recorded either way.
bills_compute: bool
# Spend cap for one wake, counting inference and compute. It resets on every wake. None means
# no cap.
max_cost_usd: Decimal | None
# Spend cap for the whole task across every wake, counting inference and compute. None means
# no cap.
task_budget_usd: Decimal | None
# True lets a running wake finish when the organization runs out of credit. False stops the
# wake and snapshots the task.
finish_in_flight: bool
enforced_checks: frozenset[ContractCheck] = frozenset()
@frozen
class Repository:
# The GitHub repository as "org/repo".
name: str
# The branch the first run starts from. Later runs boot from the task's snapshot instead.
initial_branch: str | None = None
@frozen
class TaskRunOptions:
"""Per-call settings for one task, checked against its TaskProfile.
A public API caller can only set the fields in TaskProfile.public_options. A field left at its
default falls back to the profile's value.
"""
# "acp" or "pi". It must be one of TaskProfile.runtimes and cannot change after create.
runtime: str | None = None
# The agent harness, "claude" or "codex". The server derives it from the model when unset.
adapter: str | None = None
# The LLM model ID. A pi task runs any listed model and takes no adapter.
model: str | None = None
# Reasoning effort for models that expose an effort control. A follow-up can change it.
reasoning_effort: str | None = None
# The repositories cloned into the sandbox.
repositories: tuple[Repository, ...] = ()
# A local folder used as the workspace instead of repositories. Local runs only.
folder: str | None = None
# It must be one of TaskProfile.sandbox_templates.
sandbox_template: str | None = None
# A JSON schema that the agent's final answer must match.
output_schema: dict[str, Any] | None = None
# It can lower TaskProfile.idle_minutes but never raise it.
idle_minutes: int | None = None
# NONE, READ or WRITE. It can never go above the GitHub access the profile allows.
github_access: GithubAccess | None = None
# It can narrow TaskProfile.mcp_scopes but never widen it.
mcp_scopes: PosthogMcpScopes | None = None
# The MCP servers to install, by ID. An empty tuple allows no servers. Only server callers can set
# it. The profile must have an mcp_agent.
mcp_server_ids: tuple[str, ...] | None = None
# Context window size for models that support the 1M window.
context_window: str | None = None
# Fast mode for models that support it.
fast_mode: bool | None = None
# The agent's starting permission mode, such as "plan". Claude and Codex accept different values.
permission_mode: str | None = None
# Who authors pull requests for this task. It overrides TaskProfile.default_pr_authorship.
pr_authorship_mode: PrAuthorship | None = None
# True makes the agent push its work and open a draft pull request when it finishes, without
# waiting to be asked.
auto_publish: bool | None = None
@frozen
class TaskOrigin:
origin_product: str
internal: bool
profile_key: str | None
class TaskProfileError(ValueError):
pass
class TaskRunOptionsError(ValueError):
pass
class TaskSourceError(ValueError):
pass
# Tasks stored without a profile and SQL filters only know a task's origin_product, so every profile
# that shares an origin must agree on these fields.
_ORIGIN_SCOPED_FIELDS = (
"read_without_channel",
"drive",
"api_visible",
"idle_minutes",
"max_wake_minutes",
"warm",
)
MAX_MCP_EXCLUDE_TOOLS = 32
_profiles: dict[str, TaskProfile] = {}
def register_task_profile(profile: TaskProfile) -> None:
if len(profile.mcp_exclude_tools) > MAX_MCP_EXCLUDE_TOOLS:
raise TaskProfileError(f"Task profile {profile.key!r} hides more than {MAX_MCP_EXCLUDE_TOOLS} MCP tools")
existing = _profiles.get(profile.key)
if existing is not None and existing != profile:
raise TaskProfileError(f"Task profile {profile.key!r} is already registered with different values")
if (profile.github_access == GithubAccess.NONE) != (profile.github_resolution == GithubResolution.NEVER):
raise TaskProfileError(
f"Task profile {profile.key!r} must set github_access to none exactly when github_resolution is never"
)
for other in _profiles.values():
if other.key == profile.key or other.origin_product != profile.origin_product:
continue
for name in _ORIGIN_SCOPED_FIELDS:
if getattr(other, name) != getattr(profile, name):
raise TaskProfileError(
f"Task profiles {other.key!r} and {profile.key!r} share origin {profile.origin_product!r} "
f"but disagree on {name}"
)
_profiles[profile.key] = profile
def register_task_profiles(profiles: Iterable[TaskProfile]) -> None:
for profile in profiles:
register_task_profile(profile)
def get_task_profile(key: str) -> TaskProfile:
try:
return _profiles[key]
except KeyError:
raise TaskProfileError(f"Unknown task profile {key!r}") from None
def find_task_profile(key: str | None) -> TaskProfile | None:
return _profiles.get(key) if key else None
def task_profiles() -> tuple[TaskProfile, ...]:
return tuple(_profiles.values())
def resolve_task_origin(
*, profile: TaskProfile | None, origin_product: str | None, internal: bool | None
) -> TaskOrigin:
if profile is None:
if not origin_product:
raise TaskProfileError("Pass a task profile or an origin product")
return TaskOrigin(origin_product=origin_product, internal=bool(internal), profile_key=None)
if origin_product is not None and origin_product != profile.origin_product:
raise TaskProfileError(f"Origin {origin_product!r} does not match task profile {profile.key!r}")
if internal is not None and internal == profile.listed:
raise TaskProfileError(f"internal={internal} does not match task profile {profile.key!r}")
return TaskOrigin(origin_product=profile.origin_product, internal=not profile.listed, profile_key=profile.key)
def check_task_source(*, profile: TaskProfile | None, source: TaskSource | None) -> None:
if profile is None:
return
kind = source.kind if source is not None else None
if kind != profile.source_kind:
raise TaskSourceError(f"Task profile {profile.key!r} takes source {profile.source_kind}, got {kind}")